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日

相关文章

  • asp.net web大文件上传带进度条实例代码

    以下是详细讲解“asp.net web大文件上传带进度条实例代码”的完整攻略，包括示例说明。 1.前言 在asp.net web应用程序中，文件上传是常见的功能之一。但是，如果需要上传大文件，固定的文件上传方式会带来一些问题，比如上传时间长、上传进度不确定等。 为了解决这些问题，我们可以使用带有进度条的大文件上传方式，以便让用户明确了解文件上传的状态。 2.…

    C# 2023年5月31日
    00

  • C#和lua相互调用的方法教程

    下面是关于C#和Lua相互调用的完整攻略。 1. C#调用Lua （1）安装必要的软件 首先需要安装Lua的解释器和C#与Lua相互调用的库，以下是两个比较常用的库： LuaInterface： https://github.com/nlua/lua NLua：https://github.com/NLua/NLua 这里以NLua为例。 （2）在C#中调用…

    C# 2023年5月15日
    00

  • 扩展 Entity Framework支持复杂的过滤条件(多个关键字模糊匹配)

    要扩展 Entity Framework 的过滤条件以支持复杂的过滤条件（如多个关键字的模糊匹配），需要用到 Lambda 表达式和 LINQ 功能。下面是完整的攻略： 1. 定义扩展方法 我们可以通过在静态类中定义扩展方法来扩展 Entity Framework 的过滤条件。这里我们定义一个名为 FilterByKeywords 的扩展方法： public…

    C# 2023年6月3日
    00

  • 如何通过C#/VB.NET代码将PowerPoint转换为HTML

    利用PowerPoint可以很方便的呈现多媒体信息，且信息形式多媒体化，表现力强。但难免在某些情况下我们会需要将PowerPoint转换为HTML格式。因为HTML文档能独立于各种操作系统平台（如Unix，Windows等）。并且它可以加入图片、声音、动画、影视等内容，还能从一个文件跳转到另一个文件，与世界各地主机的文件连接。通过HTML可以表现出丰富多彩的…

    C# 2023年5月8日
    00

  • 数据库 数据类型float到C#类型decimal, float数据类型转化无效

    问题描述： 在将数据库中的float数据类型转换成C#的decimal类型时，有些数据会发生转化无效的情况。这是由于float数据类型的精度问题所导致的。本文将详细介绍如何解决这个问题，并提供两个演示示例。 解决步骤： 1.使用double类型进行过渡转换 当我们将数据库中的float类型转化成decimal类型时，可以使用double类型作为过渡类型。这是…

    C# 2023年5月15日
    00

  • C#实现中文日历Calendar

    下面是 “C#实现中文日历Calendar”的完整攻略： 1. 前言 C#实现中文日历Calendar，需要使用到System.Globalization命名空间中的Calendar类，具体实现步骤如下。 2. 实现步骤 2.1 创建Calendar对象 首先，我们需要创建一个Calendar对象，代码如下： CultureInfo cultureInfo …

    C# 2023年6月1日
    00

  • C#异步执行任务的方法

    下面是使用C#异步执行任务的完整攻略，包含以下内容： 异步执行任务的基本概念及需要掌握的知识点 使用async/await关键字实现异步执行任务 使用Task.Run方法实现异步执行任务 两个实例来演示如何使用async/await和Task.Run异步执行任务 1. 异步执行任务的基本概念及需要掌握的知识点 在C#中，异步执行是指在程序继续执行其他操作的同…

    C# 2023年5月15日
    00

  • 解析使用enumerator模式简化异步操作的详解

    我很乐意为您讲解“解析使用enumerator模式简化异步操作的详解”的攻略。 什么是enumerator模式？ enumerator是一个可以使多个异步操作变得更加简单和易于管理的模式，也被称为协程模式。Enumerator是一个实现IEnumerator接口的类，它包含了一个异步操作，当这个异步操作完成时，它会返回一个结果。使用enumerator模式可…

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