C# Academy · Lesson

Configuring Asp.Versioning

Set up versioning in ASP.NET Core.

Configuring Asp.Versioning is a free C# Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the C# Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

The Asp.Versioning Package

ASP.NET Core API versioning lives in the community-maintained Asp.Versioning packages (the successor to Microsoft.AspNetCore.Mvc.Versioning).

dotnet add package Asp.Versioning.Mvc
dotnet add package Asp.Versioning.Mvc.ApiExplorer

AddApiVersioning

Register versioning with AddApiVersioning. The options control the default version and how missing versions are handled.

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});

ReportApiVersions

ReportApiVersions = true adds api-supported-versions and api-deprecated-versions response headers, so clients can discover what is available.

// Response headers:
// api-supported-versions: 1.0, 2.0
// api-deprecated-versions: 1.0

Choosing the Version Reader

The ApiVersionReader decides where the version is read from. UrlSegmentApiVersionReader reads it from the route path.

options.ApiVersionReader = new UrlSegmentApiVersionReader();

Combining Readers

Accept the version from several places at once with ApiVersionReader.Combine.

options.ApiVersionReader = ApiVersionReader.Combine(
    new UrlSegmentApiVersionReader(),
    new HeaderApiVersionReader("X-Api-Version"),
    new QueryStringApiVersionReader("api-version"));

Adding the API Explorer

Chain AddApiExplorer so versioning integrates with OpenAPI. The format string controls how version group names look.

builder.Services
    .AddApiVersioning(options => { /* ... */ })
    .AddApiExplorer(options =>
    {
        options.GroupNameFormat = "'v'VVV";
        options.SubstituteApiVersionInUrl = true;
    });

Versioning a Controller

Decorate a controller with [ApiVersion] and put the version placeholder in the route template.

[ApiVersion(1.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new { version = "1.0" });
}

A Second Version

A separate controller serves v2 on the same route template. The {version:apiVersion} segment routes requests to the right one.

[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() =>
        Ok(new { version = "2.0", extra = true });
}

Multiple Versions on One Controller

A single controller can serve several versions, mapping individual actions with [MapToApiVersion].

[ApiVersion(1.0)]
[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/orders")]
public class OrdersController : ControllerBase
{
    [HttpGet, MapToApiVersion(1.0)]
    public IActionResult GetV1() => Ok("v1");

    [HttpGet, MapToApiVersion(2.0)]
    public IActionResult GetV2() => Ok("v2");
}

Deprecating a Version

Mark a version deprecated to advertise its sunset while keeping it functional.

[ApiVersion(1.0, Deprecated = true)]
[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsController : ControllerBase { }

Versioning Minimal APIs

Minimal APIs use a version set built with NewApiVersionSet, then attach versions per endpoint.

var versionSet = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1, 0))
    .HasApiVersion(new ApiVersion(2, 0))
    .Build();

app.MapGet("/api/v{version:apiVersion}/ping", () => "pong")
   .WithApiVersionSet(versionSet)
   .MapToApiVersion(2.0);

Quick Check

Confirm what AddApiExplorer is for.

Recap

You configured Asp.Versioning:

AddApiVersioning sets the default version and reporting.
ApiVersionReader.Combine reads versions from URL, header or query.
[ApiVersion] and {version:apiVersion} route requests; [MapToApiVersion] targets actions.
Minimal APIs use a version set.

Next: generating OpenAPI documents.

Frequently asked questions

Is the “Configuring Asp.Versioning” lesson free?

Yes — the full text of “Configuring Asp.Versioning” is free to read here on the web, and the C# Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the C# Academy course, upgrade to CoddyKit PRO.

What will I learn in “Configuring Asp.Versioning”?

Set up versioning in ASP.NET Core. You practise C# Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start C# Academy?

No prior experience is required. C# Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Configuring Asp.Versioning” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this C# Academy lesson?

Yes. Every C# Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to C# Academy