1. Python技术站首页
  2. 其他
  3. C#

武装你的WEBAPI-OData Versioning

• C#

本文属于OData系列

目录

对外提供WEBAPI时，如果遇上了版本升级，那么控制WEBAPI的版本也是非常必要的。OData官方提供了版本控制以及管理的解决方案，我个人是实践体会是不好用，好在社区提供了对应的nuget包，与.NET主版本同步更新。

介绍

ASP.NET API Versioning是一个提供ASP.NET WEBAPI版本管理的包，支持ASP.NET、ASP.NET CORE、ASP.NET CORE ODATA，作者以前是微软的员工，现在不在微软工作了，因此原先的命名空间不能继续用了。现在这个项目已经加入.NET Foundation，作者也非常活跃。

版本管理

首先对现有的项目安装这个包：

Install-Package Asp.Versioning.OData

在Program.cs文件中修改一下：

var builder = WebApplication.CreateBuilder( args );

builder.Services.AddControllers().AddOData();
builder.Services.AddProblemDetails();
builder.Services.AddApiVersioning().AddOData(
    options =>
    {
        options.AddRouteComponents();
    } );

var app = builder.Build();

app.MapControllers();
app.Run();

然后在需要控制版本的控制器上加上[ApiVersion]修饰就可以了。

[ApiVersion( 1.0 )]
public class PeopleController : ODataController
{
    [EnableQuery]
    public IActionResult Get() => Ok( new[] { new Person() } );
}

注意，默认的版本是1.0，不过最好显式声明一下。

EDM升级

EDM根据版本不同也会有一些区别，需要分别进行配置，原来的GetEdm()模式显得有点麻烦，而EDM配置在这个库中变得非常灵活，使用的是Configuration模式。

示例代码如下：

public class DeviceInfoModelConfiguration : IModelConfiguration
{
	public void Apply(ODataModelBuilder builder, ApiVersion apiVersion, string routePrefix)
	{
		switch (apiVersion.MajorVersion)
		{
			case 1:
				builder.EntitySet<DeviceInfo>("DeviceInfoes").EntityType.HasKey(p => p.DeviceId);
				break;
			case 2:
				builder.EntitySet<DeviceInfo>("DeviceInfos").EntityType.HasKey(p => p.DeviceId).Ignore(w => w.Layout);
				break;
			default:
				break;
		};
	}
}

只需要实现IModelConfiguration接口，并在Apply函数中根据版本对实体或者DTO对象进行配置，不同版本的EDM可以不一样。

一般实践是一个实体对象一个IModelConfiguration，方便后面管理。

配置Swagger

因为有重复配置的模型，直接使用默认的Swagger会报错，这个时候需要使用到Versioned API Explorer，对Swagger拓展版本信息。

Install-Package Asp.Versioning.OData.ApiExplorer

安装Asp.Versioning.OData.ApiExplorer，重新改造一下Program.cs文件：

var builder = WebApplication.CreateBuilder( args );

builder.Services.AddControllers().AddOData();
builder.Services.AddProblemDetails();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddApiVersioning()
                .AddOData( options => options.AddRouteComponents() )
                .AddODataApiExplorer(
                     // format the version as "'v'major[.minor][-status]"
                     options => options.GroupNameFormat = "'v'VVV" );

services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
services.AddSwaggerGen();

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI(
    options =>
    {
        foreach ( var description in app.DescribeApiVersions() )
        {
            var url = $"/swagger/{description.GroupName}/swagger.json";
            var name = description.GroupName.ToUpperInvariant();
            options.SwaggerEndpoint( url, name );
        }
    } );
app.MapControllers();
app.Run();

还需要一个配置的类如下：

public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>
{
  readonly IApiVersionDescriptionProvider provider;

  public ConfigureSwaggerOptions( IApiVersionDescriptionProvider provider ) =>
    this.provider = provider;

  public void Configure( SwaggerGenOptions options )
  {
    foreach ( var description in provider.ApiVersionDescriptions )
    {
      options.SwaggerDoc(
        description.GroupName,
          new OpenApiInfo()
          {
            Title = $"Example API {description.ApiVersion}",
            Version = description.ApiVersion.ToString(),
          } );
    }
  }
}

这样，swagger界面就可以下拉选择不同版本的API了。
武装你的WEBAPI-OData Versioning

旧系统升级

WEBAPI Versioning对这个内容有介绍，其中需要注意的是，基于路径的版本匹配并不支持默认版本的特性，对于以前系统直接使用api/开头的控制器，并不能直接默认转到到api/v1（参考介绍）。为了兼容旧系统，我们只能在ASP.NET CORE的管线上想想办法：插入一个中间件，对路径进行判断，如果是api开头的，就直接转到api/v1；如果是api/v开头的，那么就直接下一步。

    public class RedirectMiddlewareForV1
    {
        private readonly RequestDelegate _next;

        public RedirectMiddlewareForV1(RequestDelegate next)
        {
            _next = next;
        }

        public async Task InvokeAsync(HttpContext context)
        {
            if (context.Request.Path.StartsWithSegments("/api") && !context.Request.Path.Value.StartsWith("/api/v"))
            {
                context.Response.Redirect(context.Request.Path.Value.Replace("/api/", "/api/v1/"));
            }
            else
            {
                await _next(context);
            }
        }


    }

然后在configure函数中注册这个中间件就可以了。

app.UseMiddleware<RedirectMiddlewareForV1>();

请注意，context.Request.Path.StartsWithSegments函数只能匹配完整的路径词汇，/api/v2去匹配/api/v会返回false。

FAQ

  1. 无法正确显示不同版本的Swagger，提示InvalidOperationException: Can't use schemaId "\(B" for type "\)A.B". The same schemaId is already used for type "$A.B"
    这个问题是由多次对同一个类型Schema生成造成的。最常见的情况是你的控制器有方法不属于OData Routing的一部分（比如直接使用HttpGet指定），这样程序在扫描的过程中会重复对对象进行生成。解决办法有两种：
  1. 无法加载Swagger，提示System.MissingMethodException: Method not found: 'Microsoft.OData.ModelBuilder.Config.DefaultQuerySettings Microsoft.AspNetCore.OData.ODataOptions.get_QuerySettings()
    这个是版本问题，本人使用的OData版本在8.1.0，有一些破坏性更改，只要保持引用的OData版本<= 8.0.12就可以了。
    详细分析看这个MissingMethodException with OData v8.1.0 · Issue #980 · dotnet/aspnet-api-versioning (github.com)
  2. 找不到DescribeApiVersions()方法
    app找不到这个方法，大概率是在.NET 6的Minimal API之前的代码升级出现的，之前app是用IWebhostBuilder构建的，而现在的app是直接用过WebApplication构建得到的，含义不同，最简单的方法是改造一下，使用WebApplication重写一下Startup内容。

参考

原文链接：https://www.cnblogs.com/podolski/archive/2023/05/05/17375269.html

本站文章如无特殊说明，均为本站原创，如若转载，请注明出处：武装你的WEBAPI-OData Versioning - Python技术站

赞 (0)
0 0 打赏 微信扫一扫 微信扫一扫 支付宝扫一扫 支付宝扫一扫
上一篇 2023年5月5日
下一篇 2023年5月6日

相关文章

  • C# Linq的Intersect()方法 – 返回两个序列的交集

    C# Linq Intersect()方法详解 Intersect()方法的定义 Intersect()方法是C# Linq方法之一，用于返回两个序列中共同出现的元素。该方法有两个重载版本，一个是无参数版本，返回两个序列中的重复元素，一个是带有另外一个序列作为参数的版本，返回两个序列中相同的元素。 无参数版本 无参数版本的Intersect()方法用于从两个…

    C# 2023年4月19日
    00

  • C# Environment.GetCommandLineArgs()方法： 获取当前应用程序的命令行参数

    Environment.GetCommandLineArgs() 方法简介 Environment.GetCommandLineArgs() 方法返回当前进程的命令行参数。命令行参数是启动进程时指定的字符串数组，例如，从命令行或通过使用Process.Start 方法启动进程时，可以传递命令行参数，这些参数将通过Environment.GetCommandL…

    C# 2023年4月19日
    00

  • C# DateTime.AddDays()方法： 将指定的天数加到指定的日期上

    DateTime.AddDays()是C#中DateTime结构体提供的一个方法，用于将DateTime对象的日期值增加指定的天数。其方法的声明如下： public DateTime AddDays(double value); 其中value参数为需要增加的天数，可以是一个正数，也可以是一个负数。 以下是使用该方法的两个实例： 计算一个日期的前一天 假设有…

    C# 2023年4月19日
    00

  • Asp.NET生成各种网页快捷方式的代码（桌面url快捷方式，收藏夹/开始菜单快捷方式）

    生成桌面和收藏夹/开始菜单快捷方式的代码在ASP.NET中比较简单，只需要使用标准的标签和javascript就行了。以下是两个生成桌面快捷方式和收藏夹/开始菜单快捷方式的完整攻略示例： 生成桌面快捷方式的代码 使用标签生成快捷方式链接 在HTML页面或ASP.NET WebForm中，你需要定义一个链接，用来作为桌面快捷方式。下面是标签的代码示例： &lt…

    C# 2023年5月31日
    00

  • jQuery获取地址栏参数插件(模仿C#)

    jQuery获取地址栏参数插件(模仿C#)是一个可以方便的获取URL参数的工具。下面是详细的攻略： 1. 插件的引入 首先需要在页面中引入jQuery库，然后才能引入该插件。可以使用以下代码： <script src="https://code.jquery.com/jquery-3.5.1.min.js"></scri…

    C# 2023年5月15日
    00

  • C#操作进程的方法介绍

    C# 操作进程的方法介绍 C# 中可以通过 Process 类来实现对进程的操作，包括启动进程、杀死进程、查找进程等。 以下是常用的操作进程的方法： 启动进程 启动新进程可以使用 Process.Start 方法，该方法返回一个 Process 对象，通过该对象可以得到该进程的一些详细信息，比如进程 ID，句柄等。 以下示例代码演示了如何启动计算器程序： u…

    C# 2023年6月7日
    00

  • .net实现ping的实例代码

    首先，我们需要了解一下什么是ping，以及它在网络中的作用。 Ping是什么？ 在网络中，我们可以使用Ping命令来测试网络连通性。Ping命令可以向另一台计算机发送一个数据包，然后等待该计算机返回响应。如果该计算机能够正常响应，表示网络连通正常；如果该计算机未响应，则表示网络可能存在问题。 在.NET中，我们可以使用System.Net.NetworkIn…

    C# 2023年5月31日
    00

  • WPF Slider滑动条的颜色修改方法

    下面是详细讲解“WPF Slider滑动条的颜色修改方法”的完整攻略。 1. 修改Slider的颜色 在WPF中，可以通过修改Slider的控件模板（Template）来自定义滑动条的颜色。具体步骤如下： 在XAML文件中找到要修改的Slider控件。 设置Slider的控件模板。 例如，为Slider设置一个红色的滑动条，可以这样写： <Slider…

    C# 2023年6月6日
    00
合作推广
合作推广
分享本页
返回顶部