.NET 8中从旧版API版本控制包迁移至Asp.Versioning.Mvc.ApiExplorer遇错求助

问题根源 #

你碰到的错误是因为新版Asp.Versioning包拆分了功能模块：

• ApiVersionAttribute、ApiVersion这类核心版本控制类型，并不在Asp.Versioning.Mvc.ApiExplorer包中，而是属于Asp.Versioning.Mvc核心包
• Asp.Versioning.Mvc.ApiExplorer仅负责API文档生成（比如配合Swagger），不包含版本控制的核心属性定义

修复步骤 #

1. 安装正确的NuGet包 #

确保同时安装以下两个包（版本统一为7.1.0）：

Install-Package Asp.Versioning.Mvc -Version 7.1.0
Install-Package Asp.Versioning.Mvc.ApiExplorer -Version 7.1.0

或者用.NET CLI执行：

dotnet add package Asp.Versioning.Mvc --version 7.1.0
dotnet add package Asp.Versioning.Mvc.ApiExplorer --version 7.1.0

2. 修正命名空间引用 #

控制器代码里的命名空间要换成正确的，核心版本控制属性在Asp.Versioning.Mvc下：

using Microsoft.AspNetCore.Mvc;
using Asp.Versioning.Mvc; // 替换之前错误的Asp.Versioning.Mvc.ApiExplorer

namespace Catalog.API.Controllers;

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiController]
//[Authorize(Policy = "CanRead")]
public class ApiController : ControllerBase
{   
}

如果需要用API Explorer的功能（比如配置版本化Swagger），可以保留using Asp.Versioning.Mvc.ApiExplorer，但必须同时添加Asp.Versioning.Mvc的引用。

3. 更新Program.cs的服务配置 #

新版API版本控制的注册方式和旧版不同，需要在Program.cs里正确配置：

var builder = WebApplication.CreateBuilder(args);

// 注册API版本控制服务
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
})
.AddApiExplorer(options =>
{
    // 配置API Explorer，生成带版本号的API描述
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

// 其他服务注册（比如AddControllers）
builder.Services.AddControllers();

var app = builder.Build();

// 中间件配置...
app.MapControllers();

app.Run();

关键提示 #

• 旧版Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer中，ApiVersionAttribute在Microsoft.AspNetCore.Mvc命名空间，新版Asp.Versioning把它移到了Asp.Versioning.Mvc下，这是找不到类型的核心原因
• Asp.Versioning.Mvc.ApiExplorer是可选包，只有需要生成版本化API文档（如Swagger）时才需要安装，核心版本控制只依赖Asp.Versioning.Mvc

内容的提问来源于stack exchange，提问作者Panco