C# Academy · 课时

配置 Asp.Versioning

Q: 「配置 Asp.Versioning」这节课中我会学到什么？

在 ASP.NET Core 中设置版本控制。 你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

在 ASP.NET Core 中设置版本控制。

配置 Asp.Versioning 是 CoddyKit 上的免费 C# Academy 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 C# Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 C# Academy 课程共包含 4 节课。

Asp.Versioning 包

ASP.NET Core 应用程序接口版本控制通过社区维护的 Asp.Versioning 软件包实现（它是 Microsoft.AspNetCore.Mvc.Versioning 的后继者）。

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

AddApiVersioning

使用 AddApiVersioning 注册版本控制。选项可以控制默认版本以及缺少版本时的处理方式。

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

ReportApiVersions

ReportApiVersions = true 会添加 api-supported-versions 和 api-deprecated-versions 响应标头，让客户端能够发现可用的版本。

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

选择版本读取器

ApiVersionReader 决定从哪里读取版本。UrlSegmentApiVersionReader 从路由路径中读取版本。

options.ApiVersionReader = new UrlSegmentApiVersionReader();

组合读取器

使用 ApiVersionReader.Combine 同时接受来自多个位置的版本。

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

添加 API 浏览器

链式调用 AddApiExplorer，使版本控制与 OpenAPI 集成。格式字符串控制版本组名称的显示方式。

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

为控制器进行版本控制

使用 [ApiVersion] 标注控制器，并将版本占位符放入路由模板中。

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

第二个版本

独立的控制器在同一个路由模板上提供 v2。{version:apiVersion} 段会将请求路由到正确的控制器。

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

在一个控制器上支持多个版本

单个控制器可以提供多个版本，使用 [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");
}

弃用版本

将某个版本标记为已弃用，以提示其即将结束支持，同时保持其可用。

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

为最小 API 进行版本控制

最小 API 使用通过 NewApiVersionSet 构建的版本集，然后为每个端点附加版本。

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);

快速检查

请确认 AddApiExplorer 的用途。

回顾

您配置了 Asp.Versioning：

AddApiVersioning 设置默认版本并启用版本报告。
ApiVersionReader.Combine 从 URL、标头或查询字符串中读取版本。
[ApiVersion] 和 {version:apiVersion} 负责路由请求；[MapToApiVersion] 用于指定操作的版本。
最小 API 使用版本集。

接下来：生成 OpenAPI 文档。

常见问题解答

「配置 Asp.Versioning」课时是免费的吗？

是的 — 「配置 Asp.Versioning」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 C# Academy 课程的其余内容，请升级到 CoddyKit PRO。 C# Academy 课程共包含 4 节课。

「配置 Asp.Versioning」这节课中我会学到什么？

在 ASP.NET Core 中设置版本控制。你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 C# Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 C# Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「配置 Asp.Versioning」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 C# Academy 课中编写并运行代码吗？

能。每节 C# Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 C# Academy