Vlastnost IncludeOpenAPIAnalyzers a analyzátory rozhraní API MVC jsou zastaralé

Vlastnost IncludeOpenAPIAnalyzers MSBuild a jeho přidružené analyzátory rozhraní API MVC jsou zastaralé a budou odebrány v budoucí verzi. Pokud IncludeOpenAPIAnalyzers je nastaveno na true, sestavení nyní generuje upozornění ASPDEPR007.

Verze byla představena

.NET 10 Preview 7

Předchozí chování

Dříve jste mohli ve svých Web SDK projektech nastavit <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> a povolit analyzátory API MVC bez varování nebo oznámení o vyřazení.

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

Takový projekt byl úspěšně sestaven bez výstrah ohledně zastaralosti.

Nové chování

Počínaje rozhraním .NET 10, když je IncludeOpenAPIAnalyzers nastaveno na true, sestavení vygeneruje upozornění ASPDEPR007:

upozornění ASPDEPR007: Vlastnost IncludeOpenAPIAnalyzers a jeho přidružené analyzátory rozhraní API MVC jsou zastaralé a budou odebrány v budoucí verzi.

Analyzátory nadále fungují, ale vývojáři obdrží toto upozornění na vyřazení během kompilace.

Typ zásadní změny

Tato změna může ovlivnit kompatibilitu zdroje.

Důvod změny

Analyzátory API MVC byly původně zavedeny, aby se udržovala synchronizace typů návratových hodnot a atributů u API kontrolérů, čímž se zajišťuje konzistence mezi podpisy metod a odpovídající dokumentací OpenAPI. Tyto analyzátory poskytly kontrolu během kompilace, aby zachytily nesoulad mezi deklarovanými návratovými typy a skutečnými typy, které vrací akce kontroleru.

S zavedením minimálních rozhraní API a vzorem TypedResults se ale ekosystém .NET vyvinul směrem k bezpečnějšímu přístupu pro vývoj rozhraní API. TypedResults poskytuje záruky doby kompilace o typech odpovědí bez nutnosti dalších analyzátorů, což zajišťuje redundantní analyzátory rozhraní API MVC pro moderní aplikace .NET. V .NET 10 TypedResults se podporují v rozhraních API založených na kontroleru.

Předchozí přístup s analyzátory rozhraní API MVC:

[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)
}

Moderní přístup s 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);
}

Vzor TypedResults eliminuje potřebu samostatných analyzátorů, protože samotný návratový typ (Results<Ok<Product>, NotFound>) explicitně deklaruje všechny možné typy odpovědí v době kompilace. Tento přístup je lépe udržovatelný, poskytuje lepší podporu technologie IntelliSense a automaticky generuje přesnou dokumentaci OpenAPI bez dalších nástrojů.

Vzhledem k tomu, že ekosystém .NET dále přijímá TypedResults jako doporučený vzor pro vývoj rozhraní API, jsou analyzátory rozhraní API MVC zastaralé a jsou vyřazovány, aby se zjednodušila vývojářská zkušenost.

Doporučená akce

Vývojáři by měli:

• Odeberte zastaralou vlastnost: Odstraňte <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> ze souborů projektu, abyste eliminovali varování.
• Migrujte na TypedResults: Migrace na TypedResults vzor, který zajistí lepší konzistenci mezi chováním aplikace a dokumentací OpenAPI.

Pokud potřebujete dál dočasně používat zastaralé analyzátory, můžete upozornění potlačit:

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

Ovlivněná rozhraní API

• Vlastnost MSBuild: IncludeOpenAPIAnalyzers.
• Když jsou přidružené analyzátory rozhraní API MVC zahrnuty v IncludeOpenAPIAnalyzerstrue.