如何在 ASP.NET Core Web Api 中进行版本控制

Question

在之前的asp.net web api 中，我实现了DefaultHttpControllerSelector 来指定我希望请求如何定位我的控制器。我经常有不同名称的不同控制器，但用于相同的进程。唯一的区别是一个版本比另一个版本高。

例如，我可以有一个名为 BookingV1Controller 的控制器，用于处理服务的版本一。我也会有BookingV2Controller，它旨在处理服务的第二版。然后，客户端应用程序将使用此 URL http://myservice.com/api/v2/booking/someaction?id=12 向服务发出请求。为了处理请求，我将提供DefaultHttpControllerSelector 的自定义实现，以根据请求的版本选择所需的控制器的适当版本。

但是，我似乎没有办法在 ASP.NET Core 中执行此操作。我到处搜索都无济于事。也没有可以提供帮助的文档。

如果有人可以在这里帮助我，我将不胜感激。谢谢。

更新 如果在自定义标头中指定了版本，我还想知道该怎么做。例如X-Version:v1

更新 2

要求是服务的版本不应在 URL 中公开。如果不存在版本，则服务将返回有关如何添加版本的说明。如果请求的控制器不存在于请求的版本中，系统将搜索较低的版本。如果它在任何较低版本中找到它，它就会使用它。这样做的原因是为了防止在所有版本上重复控制器。但是对于 ASP.NET Core，这可能是不可能的。

Answer 1

使用路由属性控制版本。

即

[Route("api/v1/[controller]")]
public class BookingV1Controller : Controller
{
  ....
}

[Route("api/v2/[controller]")]
public class BookingV2Controller : Controller
{
  ....
}

有关从标准 Web Api 和 .NET Core ASP.NET 迁移的更多信息，请查看：MSDN: Migrating from ASP.NET Web Api

Answer 2

我为此问题专门研究了几天后，为此目的创建了一个包。它不需要属性。

https://github.com/GoAheadTours/NamespaceVersioning

总而言之，您可以在启动文件中注册一个 IApplicationModelConvention，它可以遍历控制器并根据命名空间注册路由。我创建了一个 v1 文件夹，并将我的控制器放入其中

实现 IApplicationModelConvention 的类实现了一个带有 ApplicationModel 参数的 Apply 方法，该参数将有权访问您应用中的控制器及其现有路由。如果我看到控制器没有在我的类中设置路由，我会从命名空间获取版本并使用预定义的 URL 前缀为该版本生成路由。

public void Apply(ApplicationModel application) {
    foreach (var controller in application.Controllers) {
        var hasRouteAttribute = controller.Selectors.Any(x => x.AttributeRouteModel != null);
        if (hasRouteAttribute) {
            continue;
        }
        var nameSpace = controller.ControllerType.Namespace.Split('.');
        var version = nameSpace.FirstOrDefault(x => Regex.IsMatch(x, @"[v][\d*]"));
        if (string.IsNullOrEmpty(version)) {
            continue;
        }
        controller.Selectors[0].AttributeRouteModel = new AttributeRouteModel() {
            Template = string.Format(urlTemplate, apiPrefix, version, controller.ControllerName)
        };
    }
}

我在 github 上提供了所有代码，并在 nuget 上提供了包的链接

Answer 3

这是我偶然发现的一个非常古老的问题，但现在有更好的解决方案。有这个包

Microsoft.AspNetCore.Mvc.Versioning

它具有更丰富的实现版本控制的方式。其中包括能够使用 URL 查询字符串、url 路径、标题或自定义版本阅读器。能够从 HTTPContext 等读取版本。

简而言之，您将以下内容添加到 startup.cs 中的 ConfigureServices 方法中

services.AddApiVersioning(o => {
    o.ReportApiVersions = true;
    o.AssumeDefaultVersionWhenUnspecified = true;
            o.DefaultApiVersion = new ApiVersion(1, 0);
});

然后你必须用 ApiVersion 来装饰你的控制器。

[ApiVersion("1.0")]
[Route("api/home")]
public class HomeV1Controller : Controller
{
    [HttpGet]
    public string Get() => "Version 1";
}

[ApiVersion("2.0")]
[Route("api/home")]
public class HomeV2Controller : Controller
{
    [HttpGet]
    public string Get() => "Version 2";
}

你也可以通过把它放在路由中来实现它。

[ApiVersion("1.0")]
[Route("api/{version:apiVersion}/home")]
public class HomeV1Controller : Controller
{
    [HttpGet]
    public string Get() => "Version 1";
}

[ApiVersion("2.0")]
[Route("api/{version:apiVersion}/home")]
public class HomeV2Controller : Controller
{
    [HttpGet]
    public string Get() => "Version 2";
}

当您采用这种通过 Microsoft 包实际实现的方法时，这也意味着您能够弃用版本、进行版本发现、轻松地从 HttpContext 访问版本号等。这些都不是您真正可以做到的如果它只是在您的路线中硬编码，请执行此操作。

更多信息（包括在标题中使用）：

• http://dotnetcoretutorials.com/2017/01/17/api-versioning-asp-net-core/

• http://www.hanselman.com/blog/ASPNETCoreRESTfulWebAPIVersioningMadeEasy.aspx

• https://github.com/Microsoft/aspnet-api-versioning/wiki

Answer 4

为此将服务 API 版本控制添加到您的 ASP.NET Core 应用程序

  public void ConfigureServices( IServiceCollection services )
    {
        services.AddMvc();
        services.AddApiVersioning();

        // remaining other stuff omitted for brevity
    }

查询字符串参数版本

[ApiVersion( "2.0" )]
[Route( "api/helloworld" )]
public class HelloWorld2Controller : Controller {
    [HttpGet]
    public string Get() => "Hello world!";
}

所以这意味着在另一个具有相同路由的控制器中获得 2.0 超过 1.0，你应该去这里：

/api/helloworld?api-version=2.0

我们可以在不同的命名空间中使用相同的控制器名称

网址路径段版本

 [ApiVersion( "1.0" )]
 [Route( "api/v{version:apiVersion}/[controller]" )]
 public class HelloWorldController : Controller {
    public string Get() => "Hello world!";
 }
[ApiVersion( "2.0" )]
[ApiVersion( "3.0" )]
[Route( "api/v{version:apiVersion}/helloworld" )]
public class HelloWorld2Controller : Controller {
    [HttpGet]
    public string Get() => "Hello world v2!";

    [HttpGet, MapToApiVersion( "3.0" )]
    public string GetV3() => "Hello world v3!";
}

标头版本控制

  public void ConfigureServices( IServiceCollection services )
    {
        services.AddMvc();
        services.AddApiVersioning(o => o.ApiVersionReader = new HeaderApiVersionReader("api-version"));
    }

当您执行 HeaderApiVersioning 时，您将无法仅在浏览器中执行 GET，因此我将使用 Postman 添加标头（或者我可以使用 Curl、WGet、PowerShell 或单元测试） ：

Image

请参考https://www.hanselman.com/blog/ASPNETCoreRESTfulWebAPIVersioningMadeEasy.aspx