共用方式為

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檔之間的一致性。 這些分析器提供用於編譯時期的驗證，以偵測宣布的返回型別與控制器動作實際返回的型別不一致之處。

不過，隨著 Minimal 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> 以消除警告。
  • 遷移至 ：移轉至TypedResultsTypedResults模式，以確保應用程式行為與OpenAPI檔案之間的較佳一致性。

如果您需要暫時繼續使用已被取代的分析器，您可以隱藏警告：

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

受影響的 API

  • MSBuild 屬性： IncludeOpenAPIAnalyzers。
  • 當 IncludeOpenAPIAnalyzers 是 true 時，會包含相關的 MVC API 分析器。
  • Last updated on