次の方法で共有

IncludeOpenAPIAnalyzers プロパティと MVC API アナライザーは非推奨です

IncludeOpenAPIAnalyzers MSBuild プロパティとそれに関連付けられている MVC API アナライザーは非推奨となり、今後のリリースで削除される予定です。 IncludeOpenAPIAnalyzersが true に設定されている場合、ビルドは警告ASPDEPR007を出力するようになりました。

導入されたバージョン

.NET 10 Preview 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 では、追加のアナライザーを必要とせずに応答の種類に関するコンパイル時の保証が提供され、最新の .NET アプリケーションでは MVC API アナライザーが冗長になります。 .NET 10 では、 TypedResults はコントローラー ベースの API でサポートされています。

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 エコシステムでは、API 開発の推奨パターンとして TypedResults が引き続き採用されるため、MVC API アナライザーは廃止され、開発エクスペリエンスを効率化するために非推奨とされています。

開発者は次の手順を実行する必要があります。

  • 非推奨のプロパティを削除する: プロジェクト ファイルから <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> を削除して、警告を排除します。
  • TypedResultsへの移行: アプリケーションの動作と OpenAPI ドキュメントの間の一貫性を高めるために、TypedResults パターンに移行します。

非推奨のアナライザーを一時的に引き続き使用する必要がある場合は、警告を抑制できます。

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

影響を受ける API

  • MSBuild プロパティ: IncludeOpenAPIAnalyzers。
  • IncludeOpenAPIAnalyzersがtrueされたときに含まれる関連する MVC API アナライザー。
  • Last updated on