通过

IncludeOpenAPIAnalyzers 属性和 MVC API 分析器已被弃用

IncludeOpenAPIAnalyzers MSBuild 属性及其关联的 MVC API 分析器已弃用，将在将来的版本中删除。 当 IncludeOpenAPIAnalyzers 被设置为 true 时，生成现在会发出警告 ASPDEPR007。

已引入的版本

.NET 10 预览版 7

以前的行为

以前，可以在 Web SDK 项目中设置 <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> ，以便在没有任何警告或弃用通知的情况下启用 MVC API 分析器。

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers>
  </PropertyGroup>
</Project>

此类项目在未出现任何弃用警告的情况下成功构建。

新行为

从 .NET 10 开始，当将IncludeOpenAPIAnalyzers设置为true时，生成会发出警告ASPDEPR007。

警告ASPDEPR007：IncludeOpenAPIAnalyzers 属性及其关联的 MVC API 分析器已弃用，将在将来的版本中删除。

分析器继续正常运行，但开发人员在编译期间收到此弃用警告。

破坏性变更的类型

此更改可能会影响 源兼容性。

更改原因

最初引入了 MVC API 分析器，以帮助保持 API 控制器的返回类型和属性同步，确保方法签名与其相应的 OpenAPI 文档之间的一致性。 这些分析器提供了编译时验证，以捕获声明的返回类型与控制器作返回的实际类型之间的不匹配。

但是，随着引入最小 API 和 TypedResults 模式，.NET 生态系统已朝着更安全的 API 开发方法发展。 TypedResults 提供关于响应类型的编译时保证，而无需其他分析器，使 MVC API 分析器为新式 .NET 应用程序冗余。 在 .NET 10 中，在基于控制器的 API 中支持 TypedResults。

使用 MVC API 分析器之前的方法：

[HttpGet]
[ProducesResponseType<Product>(200)]
[ProducesResponseType(404)]
public async Task<ActionResult> GetProduct(int id)
{
    var product = await _productService.GetByIdAsync(id);
    if (product == null)
        return NotFound(); // Analyzer ensures this matches ProducesResponseType(404)

    return Ok(product); // Analyzer ensures this matches ProducesResponseType<Product>(200)
}

新式方法与 TypedResults：

[HttpGet("{id}")]
public async Task<Results<Ok<Product>, NotFound>> GetProduct(int id)
{
    var product = await _productService.GetByIdAsync(id);
    return product == null
        ? TypedResults.NotFound()
        : TypedResults.Ok(product);
}

该 TypedResults 模式消除了单独分析器的需求，因为返回类型本身（Results<Ok<Product>, NotFound>）在编译时显式声明所有可能的响应类型。 此方法更易于维护，提供更好的 IntelliSense 支持，并自动生成准确的 OpenAPI 文档，而无需其他工具。

随着 .NET 生态系统继续接受 TypedResults 为 API 开发建议的模式，MVC API 分析器已过时，并已被弃用以简化开发体验。

开发人员应：

  • 删除已弃用的属性：从项目文件中删除 <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> 以消除警告。
  • TypedResults迁移到：迁移到TypedResults模式，以确保应用程序行为与 OpenAPI 文档之间的更好一致性。

如果需要暂时继续使用弃用的分析器，可以禁止显示警告：

<PropertyGroup>
  <NoWarn>$(NoWarn);ASPDEPR007</NoWarn>
</PropertyGroup>

受影响的 API

  • MSBuild 属性： IncludeOpenAPIAnalyzers.
  • 关联的 MVC API 分析器在IncludeOpenAPIAnalyzerstrue时包含。
  • Last updated on