versioning

1. Introduction

If you were looking for information about API versioning support for ASP.NET Core you’ve probably come across Microsoft.AspNetCore.Mvc.Versioning library. The library itself allows you to set up versioning in a couple of different ways, for instance, via attributes or via manual convention setup. All of this options are really nice but unfortunately, they have one significant drawback, namely, you have to set them up manually. As I tend to forget about this kind of things I wanted to automate that process as much as possible. Thankfully ASP.NET Core has a very nice feature called ApplicationModelConventions which allows you to add some metadata(like routing information, API versioning ) to your controller, actions etc.

2. Convention

I’ve decided to implement versioning by routing which means the API will be accessible via this template

"v{version:apiVersion}/[controller]"

1	"v{version:apiVersion}/[controller]"

The template itself doesn’t give you much, as you also have to add information to the controllers which version of API they support. In my case, I decided to go with a version by namespace convention, which means that supported version will be deduced from namespace in which given controller resides. So, in fact, there will be two conventions, one for applying routing and a second one for applying versioning

3. Creating conventions.

In order to write an ASP.NET Core convention, we have to implement IApplicationModelConvention interface. This interface has a single method Apply which takes ApplicationModel class as an argument. This class gives us access to all of our controllers, actions and other parts of the application. So if we want to apply a routing with versioning for all of the controllers, we can do it in following way

public class ApiVersionRoutePrefixConvention : IApplicationModelConvention
{
    private readonly string _versionConstraintTemplate;
    private readonly string _versionedControllerTemplate;

    public ApiVersionRoutePrefixConvention()
    {
        _versionConstraintTemplate = "v{version:apiVersion}";
        _versionedControllerTemplate = $"{_versionConstraintTemplate}/[controller]";
    }

    public void Apply(ApplicationModel application)
    {
        foreach (var applicationController in application.Controllers)
        {
            foreach (var applicationControllerSelector in applicationController.Selectors)
            {
                if (applicationControllerSelector.AttributeRouteModel != null)
                {
                    var versionedConstraintRouteModel = new AttributeRouteModel
                    {
                        Template = _versionConstraintTemplate
                    };

                    applicationControllerSelector.AttributeRouteModel =
                            AttributeRouteModel.CombineAttributeRouteModel(versionedConstraintRouteModel,
                                applicationControllerSelector.AttributeRouteModel);
                }
                else
                {
                    applicationControllerSelector.AttributeRouteModel = new AttributeRouteModel
                    {
                        Template = _versionedControllerTemplate
                    };
                }
            }
        }
    }
}

public class ApiVersionRoutePrefixConvention : IApplicationModelConvention

{

private readonly string _versionConstraintTemplate;

private readonly string _versionedControllerTemplate;

public ApiVersionRoutePrefixConvention()

{

_versionConstraintTemplate = "v{version:apiVersion}";

_versionedControllerTemplate = $"{_versionConstraintTemplate}/[controller]";

}

public void Apply(ApplicationModel application)

{

foreach (var applicationController in application.Controllers)

{

foreach (var applicationControllerSelector in applicationController.Selectors)

{

if (applicationControllerSelector.AttributeRouteModel != null)

{

var versionedConstraintRouteModel = new AttributeRouteModel

{

Template = _versionConstraintTemplate

};

applicationControllerSelector.AttributeRouteModel =

AttributeRouteModel.CombineAttributeRouteModel(versionedConstraintRouteModel,

applicationControllerSelector.AttributeRouteModel);

}

else

{

applicationControllerSelector.AttributeRouteModel = new AttributeRouteModel

{

Template = _versionedControllerTemplate

};

}

As you can see we iterate through all of the Selectors and then apply new route model to them. If selector already had a route attribute applied we combine two attributes together. Once our convention is applied our actions will be accessible with following routing prefix

"v{version:apiVersion}/[controller]"

1	"v{version:apiVersion}/[controller]"

or via

"v{version:apiVersion}/previous_route_for_controller"

1	"v{version:apiVersion}/previous_route_for_controller"

Having our routing ready now it is time to add versioning information to our controllers. Once again it will be done via application model convention. The version of the controller will be deduced from the namespace given controller is located in.

public class ApiVersionByNamespaceConvention : IApplicationModelConvention
{
    public void Apply(ApplicationModel application)
    {
        foreach (var controllerModel in application.Controllers)
        {
            var version = DeduceControllerVersion(controllerModel);
            var builder = new ControllerApiVersionConventionBuilder<ControllerModel>();
            builder.HasApiVersion(new ApiVersion(version, 0));
            builder.ApplyTo(controllerModel);
        }
    }

    private int DeduceControllerVersion(ControllerModel model)
    {
        // super trivial way of retrieving version number from namespace
        if (!int.TryParse(model.ControllerType.Namespace.Last().ToString(), out var version))
        {
            throw new InvalidOperationException("Unable to retrieve version information from namespace");
        }
        
        return version;
     }
}

public class ApiVersionByNamespaceConvention : IApplicationModelConvention

{

public void Apply(ApplicationModel application)

{

foreach (var controllerModel in application.Controllers)

{

var version = DeduceControllerVersion(controllerModel);

var builder = new ControllerApiVersionConventionBuilder<ControllerModel>();

builder.HasApiVersion(new ApiVersion(version, 0));

builder.ApplyTo(controllerModel);

}

private int DeduceControllerVersion(ControllerModel model)

{

// super trivial way of retrieving version number from namespace

if (!int.TryParse(model.ControllerType.Namespace.Last().ToString(), out var version))

{

throw new InvalidOperationException("Unable to retrieve version information from namespace");

}

return version;

}

As you can see I iterate through all of the controller models of our application, then check the version of controller based on its namespace and finally with

var builder = new ControllerApiVersionConventionBuilder<ControllerModel>();
builder.HasApiVersion(new ApiVersion(version, 0));
builder.ApplyTo(controllerModel);

var builder = new ControllerApiVersionConventionBuilder<ControllerModel>();

builder.HasApiVersion(new ApiVersion(version, 0));

builder.ApplyTo(controllerModel);

I am able to inform the framework which version of API given controller supports.

4. Adding convention to application

Having all of our conventions prepared now we can enable versioning support

// Add framework services.
services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
});

// Add framework services.

services.AddApiVersioning(options =>

{

options.ReportApiVersions = true;

});

And of course, we have to add newly created conventions to list of application conventions

services.AddMvc(options =>
{
    options.Conventions.Remove<ApiVersionConvention>();
    options.Conventions.Remove<ImplicitControllerVersionConvention>();
    options.Conventions.Add(new ApiVersionRoutePrefixConvention());
    options.Conventions.Add(new ApiVersionByNamespaceConvention());
});

services.AddMvc(options =>

{

options.Conventions.Remove<ApiVersionConvention>();

options.Conventions.Remove<ImplicitControllerVersionConvention>();

options.Conventions.Add(new ApiVersionRoutePrefixConvention());

options.Conventions.Add(new ApiVersionByNamespaceConvention());

});

Note that I removed ApiVersionConvention and ImplicitControllerVersionConvention with simple extension method Remove<T>

public static class CollectionExtensions
{
    public static void Remove<T>(this IList<IApplicationModelConvention> conventionsCollection)
            where T : IApplicationModelConvention
    {
        var conventions = conventionsCollection.OfType<T>().ToList();

        foreach (var convention in conventions)
        {
            conventionsCollection.Remove(convention);
        }
    }
}

public static class CollectionExtensions

{

public static void Remove<T>(this IList<IApplicationModelConvention> conventionsCollection)

where T : IApplicationModelConvention

{

var conventions = conventionsCollection.OfType<T>().ToList();

foreach (var convention in conventions)

{

conventionsCollection.Remove(convention);

}

to make sure that only my convention is responsible for API versioning.

Source code for this post can be found here

1. Introduction.

When you start versioning your API sometimes you want to have access to your endpoints without specifying version explicitly. Thanks to Microsoft.AspNetCore.Mvc.Versioning library this can be easily achieved with proper setup of configuration action. However, it turns out that in order to enable default API version for url path versioning, there are a couple additional steps to do.

2. Default API version without url path versioning

Let’s start with the initial setup of API versioning which will work for every type of versioning apart from url path versioning. All you have to do is to assign an ApiVersionSelector and set the AssumeDefaultVersionWhenUnspecified property to true.

public void ConfigureServices(IServiceCollection services)
{
    // Add framework services.
    services.AddApiVersioning(options =>
    {
        options.ApiVersionReader = new QueryStringApiVersionReader();
        options.AssumeDefaultVersionWhenUnspecified = true;
        options.ApiVersionSelector = new CurrentImplementationApiVersionSelector(options);
    });
}

public void ConfigureServices(IServiceCollection services)

{

// Add framework services.

services.AddApiVersioning(options =>

{

options.ApiVersionReader = new QueryStringApiVersionReader();

options.AssumeDefaultVersionWhenUnspecified = true;

options.ApiVersionSelector = new CurrentImplementationApiVersionSelector(options);

});

}

Now when the user will try to access the endpoint without specifying version explicitly the ApiVersionSelector will select proper version – in this case highest available version.

3. Default Api version with URL path versioning

Running the same configuration against controllers which are versioned via url path (not query string)

namespace AspNetCoreDefaultApiVersionAndRoutePrefix.Controllers.V1
{
    [Route("v{version:apiVersion}/[controller]")]
    [ApiVersion("1")]
    public class ValuesController : Controller
    {
        // GET api/values
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] {"V1"};
        }
    }
}

namespace AspNetCoreDefaultApiVersionAndRoutePrefix.Controllers.V2
{
    [Route("v{version:apiVersion}/[controller]")]
    [ApiVersion("2")]
    public class ValuesController : Controller
    {
        // GET api/values
        [HttpGet]
        public IEnumerable<string> Get()
        {
            return new string[] {"V2"};
        }
    }
}

namespace AspNetCoreDefaultApiVersionAndRoutePrefix.Controllers.V1

{

[Route("v{version:apiVersion}/[controller]")]

[ApiVersion("1")]

public class ValuesController : Controller

{

// GET api/values

[HttpGet]

public IEnumerable<string> Get()

{

return new string[] {"V1"};

}

namespace AspNetCoreDefaultApiVersionAndRoutePrefix.Controllers.V2

{

[Route("v{version:apiVersion}/[controller]")]

[ApiVersion("2")]

public class ValuesController : Controller

{

// GET api/values

[HttpGet]

public IEnumerable<string> Get()

{

return new string[] {"V2"};

}

will result with 404 status code, as routing is not able to match the url.

Fortunately, unlike the ASP.NET Web API, ASP.NET Core allows us to have multiple route attributes applied to given controller, so in order to fix the issue we just have to add

[Route("[controller]")]

1	[Route("[controller]")]

attribute to versioned controllers. From now on we can access our API without specifying version as well as with version specified.

4. Adding default route with convention

If you don’t want to specify default route manually for every controller, you can do it via application model convention. The interesting thing about it is the fact that apart from changing existing values of application model we can also add new items to it. This means that we can add additional SelectorModel with our default route to Selectors’ collection

public class DefaultRoutePrefixConvention : IApplicationModelConvention
{
    public void Apply(ApplicationModel application)
    {
        foreach (var applicationController in application.Controllers)
        {
            applicationController.Selectors.Add(new SelectorModel
            {
                AttributeRouteModel = new AttributeRouteModel
                {
                    Template = "[controller]"
                }
            });
        }
    }
}

public class DefaultRoutePrefixConvention : IApplicationModelConvention

{

public void Apply(ApplicationModel application)

{

foreach (var applicationController in application.Controllers)

{

applicationController.Selectors.Add(new SelectorModel

{

AttributeRouteModel = new AttributeRouteModel

{

Template = "[controller]"

}

});

}

Now we can get rid of [Route(“[controller]”)] attribute from our versioned controllers and just rely on convention which can be added as follows

public void ConfigureServices(IServiceCollection services)
{
    // rest of the code omitted for brevity 
    services.AddMvc(mvc =>
    {
        mvc.Conventions.Add(new DefaultRoutePrefixConvention());
    });
}

public void ConfigureServices(IServiceCollection services)

{

// rest of the code omitted for brevity

services.AddMvc(mvc =>

{

mvc.Conventions.Add(new DefaultRoutePrefixConvention());

});

}

Source code for this post can be found here

.NET BLOG

.NET, C# blog

ASP.NET Core – API versioning by convention

1. Introduction

2. Convention

3. Creating conventions.

4. Adding convention to application

ASP.NET Core – default API version with url path versioning

1. Introduction.

2. Default API version without url path versioning

3. Default Api version with URL path versioning

4. Adding default route with convention