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.

On Tuesday, we saw how you can now self-host Downlink in an existing (or new) ASP.NET MVC Core app. However, Downlink's routing pattern is quite aggressive and you might find it kicking in for routes you'd prefer it didn't.

While before the rebuild, you had very little control over Downlink's internals, if you're self-hosting, you have much more power!

In fact, you can now easily add a route prefix to Downlink through no less than 3 different methods:

1. Configuration

The easiest method is to define the DownlinkPrefix configuration key (using a config file, or environment variable). When you do so, that prefix will be automatically added to Downlink's routes, no further changes required!

Since this is part of the default setup, this configuration also works the same for the Docker image!

Add the prefix to your configuration, such as 'download':

{
  "DownlinkPrefix": "download"
}

Now, instead of a request to yourapp.com/v1.2/windows/x64 triggering your download, you'll want yourapp.com/download/v1.2/windows/x64. It's that simple!

2. Code

If you're self-hosting you can also easily add a new route prefix in the startup code of your app. Use the fluent overload of the AddDownlink() method to call the UseRoutePrefix method. For example, to add the same 'download' prefix we used above:

// in Startup.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().AddDownlink(d => d.UseRoutePrefix("download"));
}

Now this works pretty well for simple "add a string to the start" routing scenarios, but there's another much more powerful option!

3. Extension point

We saw yesterday that Downlink 0.2 now supports extensibility for most of it's core and internal functionality. Fortunately, that even extends to the routing behaviour!

Internally, Downlink attempts to resolve an instance of IRoutePrefixBuilder to determine what route prefix (if any) to apply to Downlink routes when the app starts. In fact, the two methods above are using those same extension points (they're ConfigurationRoutePrefixBuilder and StaticRoutePrefixBuilder, respectively).

So, to control the routing prefix more directly, you can also use the builder to add your own prefix implementation with whatever logic you like. For example:

// in Startup.cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc().AddDownlink(d => d.UseRouteBuilder<MyAwesomeBuilder>());
}

Then, Downlink will call your builder's GetPrefix method when the app starts to get the prefix to prepend to Downlink's routes

The technical details

The IRoutePrefixBuilder that we use to resolve the route prefix (see above) is a very simple interface just used to get a prefix. The actual routing changes are done in the DownlinkRouteConvention. This type makes use of ASP.NET Core's new IActionModelConvention to apply an app-wide "convention" to any actions.

The default convention (which you can replace if you're feeling very adventurous) just goes through the actions in the DownlinkController and merges the prefix we resolved into the existing attribute routes to create our new route table entries.

As you can see, Downlink's routing is now much more flexible and puts the control back in your hands! Check back tomorrow for more posts on new features in the rebuilt Downlink 0.2!