What's new in Downlink 0.2: Hosting

This is part of a series of posts on the new features added in Downlink 0.2! Check out this post for more or hit the docs.

So one of the biggest cornerstones of the rebuilt Downlink is that it is no longer a monolithic Web API! Downlink is now a modular MVC-based component that you can add to any ASP.NET Core app (targeting .NET Core 2.0).

Using the pre-built version

Just because we've made all these changes doesn't make Downlink any harder to get started with!

If you've already got a config file (like config.yml), you can run it just like this:

docker run -it --rm -p 80:80 -v $PWD/config.yml:/downlink/config.yml agc93/downlink:latest

Even if you don't use a config file, you can use environment variables instead:

docker run -it --rm \
-p 80:80 \
-e DOWNLINK:Storage=GitHub \
-e DOWNLINK:GitHubStorage:Repository=gohugoio/hugo \
agc93/downlink:latest

(we're just using Hugo as an example here)

The trick is, you might not want to run a whole separate app/image just for your downloads. What if you want to add Downlink's awesome magic to your existing apps?

Hosting Downlink in another app

Downlink 0.2 has now been re-built as an MVC component, so you can install it into an existing app much more easily.

In fact, when you run the Docker image above, you're actually running a super-lightweight ASP.NET Core app with Downlink pre-installed!

So, how do you host it yourself? Just create a new app (say, with dotnet new api for example) and follow the steps below:

1. Install Downlink

Just run dotnet add package Downlink or add the PackageReference to your csproj:

<PackageReference Include="Downlink" Version="0.2.0" />

2. Add the configuration to your Program.cs

In Program.cs, just update your BuildWebHost to add the required configuration:

WebHost.CreateDefaultBuilder(args)
            .ConfigureDownlink() // <-- add this line!
            .UseStartup<Startup>()
            .Build();

You'll need to provide configuration such as from environment variables or config files, just like when running directly.

3. Add Downlink to your app (in Startup.cs)

Now in Startup.cs, just add a single call to your ConfigureServices method:

services.AddMvc().AddDownlink();

That's it! Downlink is now installed and when you run your app (such as using dotnet run), Downlink will register itself with MVC and be listening for requests.

A note of caution

It's worth noting that Downlink's routing is quite aggressive so I recommend using Downlink 0.2's new routing support! Check back on Thursday for the full details on controlling your routing.

The technical details

Since Downlink uses a whole bunch of the built-in MVC features, it's not as easy as adding a new middleware and standing back. Instead, Downlink uses MVC's new Application Part abstraction.

You can see here that we only need to register the hosting assembly as an application part and MVC will use it to pull resources (controllers etc) and add them to the hosting app. Downlink's internal DownlinkBuilder type is then responsible for configuration and extensions (see tomorrow's post for more on that!).

The only other important part is that ConfigureDownlink() method that we added earlier. That just adds in the configuration that Downlink expects!

And just to prove the point you can see that the app we package in the Docker image is built like any other hosting app, no magic here!

You can find detailed documentation on hosting Downlink here (or check out all the online docs)