Configuring Your Application

Although different variations of ASP.NET have distinct application initialization methods, careful consideration was taken to make the API versioning configuration as similar as possible across all applications models.

ASP.NET Web API

The configuration for ASP.NET Web API applications typically occurs in the Register method of the WebApiConfig.cs file. To enable API versioning support with the default options, use the following configuration:

public static void Register( HttpConfiguration configuration )
{
    configuration.AddApiVersioning();

    // remaining web api setup omitted for brevity
}

If you intend to use the URL segment versioning method, then you also need to register the appropriate route constraint:

public static void Register( HttpConfiguration configuration )
{
    var constraintResolver = new DefaultInlineConstraintResolver()
    {
        ConstraintMap =
        {
            ["apiVersion"] = typeof( ApiVersionRouteConstraint )
        }
    };
    configuration.MapHttpAttributeRoutes( constraintResolver );
    configuration.AddApiVersioning();

    // remaining setup omitted for brevity
}

Custom route constraints in ASP.NET Web API can only be configured through the MapHttpAttributeRoutes method. This method is only expected to be called once in an application. Since API versioning may be added to an existing application, you must explicitly add the route constraint to ensure the current configuration does not break.

This is also the same basic setup for OData applications, except that you do not need to add any route constraints or map attribute routes. OData uses its own route constraints and convention-based routing. For more information, see the topic on API versioning with OData.

ASP.NET Core

Two methods of configuration are supported. All examples will use the new top-level statements method, but the older Startup.cs method is still supported.

Top-Level Statements

var builder = WebApplication.CreateBuilder( args );

builder.Services.AddControllers();
builder.Services.AddProblemDetails();
builder.Services.AddApiVersioning()
                .AddMvc(); // ← brings in MVC Core; unnecessary for Minimal APIs

// remaining setup omitted for brevity

Startup

The configuration for ASP.NET Core applications typically occur in the ConfigureServices method of the Startup.cs file. To enable API versioning support with the default options, use the following configuration:

public void ConfigureServices( IServiceCollection services )
{
    services.AddControllers();
    services.AddProblemDetails();
    services.AddApiVersioning()
            .AddMvc(); // ← brings in MVC Core; unnecessary for Minimal APIs

    // remaining setup omitted for brevity
}

The mechanism in which route constraints are configured is different than in ASP.NET Web API. For this reason, you do not need to explicitly register any additional route constraints to use URL segment versioning because it will be done for you.