Egenskapen IncludeOpenAPIAnalyzers och MVC API-analysverktyg är inaktuella

MSBuild-egenskapen IncludeOpenAPIAnalyzers och dess associerade MVC API-analysverktyg är inaktuella och tas bort i en framtida version. När IncludeOpenAPIAnalyzers är inställt på truegenererar bygget nu en varning ASPDEPR007.

Version lanserad

.NET 10 Förhandsversion 7

Tidigare beteende

Tidigare kunde du ställa in <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> i dina Web SDK-projekt för att aktivera MVC API-analysatorer utan några varningar eller utfasningsmeddelanden.

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

Ett sådant projekt har skapats utan utfasningsvarningar.

Nytt beteende

Från och med .NET 10, när IncludeOpenAPIAnalyzers är inställt på true, genererar bygget varning ASPDEPR007:

varning ASPDEPR007: Egenskapen IncludeOpenAPIAnalyzers och dess associerade MVC API-analysverktyg är inaktuella och tas bort i en framtida version.

Analysverktygen fortsätter att fungera, men utvecklare får den här utfasningsvarningen under kompileringen.

Typ av brytande ändring

Den här ändringen kan påverka källkompatibilitet.

Orsak till ändring

MVC API-analysverktygen introducerades ursprungligen för att hålla returtyper och attribut synkroniserade för API-kontrollanter, vilket säkerställer konsekvens mellan metodsignaturer och motsvarande OpenAPI-dokumentation. Dessa analysverktyg tillhandahöll kompileringstidsverifiering för att fånga felmatchningar mellan deklarerade returtyper och de faktiska typer som returneras av kontrollantåtgärder.

Men med införandet av minimala API:er och TypedResults mönstret har .NET-ekosystemet utvecklats till en mer typsäker metod för API-utveckling. TypedResults ger kompileringstidsgarantier om svarstyper utan att kräva ytterligare analysverktyg, vilket gör MVC API-analysverktygen redundanta för moderna .NET-program. I .NET 10 TypedResults stöds i kontrollantbaserade API:er.

Tidigare metod med MVC API-analysverktyg:

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

Modernt tillvägagångssätt med 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);
}

Mönstret TypedResults eliminerar behovet av separata analysverktyg eftersom själva returtypen (Results<Ok<Product>, NotFound>) uttryckligen deklarerar alla möjliga svarstyper vid kompileringstiden. Den här metoden är mer underhållsbar, ger bättre IntelliSense-stöd och genererar automatiskt korrekt OpenAPI-dokumentation utan ytterligare verktyg.

Eftersom .NET-ekosystemet fortsätter att omfatta TypedResults det rekommenderade mönstret för API-utveckling har MVC API-analysverktygen blivit föråldrade och håller på att bli inaktuella för att effektivisera utvecklingsupplevelsen.

Rekommenderad åtgärd

Utvecklare bör:

• Ta bort den inaktuella egenskapen: Ta bort <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> från projektfilerna för att eliminera varningen.
• Migrera till TypedResults: Migrera till TypedResults mönstret för att säkerställa bättre konsekvens mellan programbeteende och OpenAPI-dokumentation.

Om du behöver fortsätta att använda de inaktuella analysverktygen tillfälligt kan du ignorera varningen:

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

Berörda API:er

• MSBuild-egenskap: IncludeOpenAPIAnalyzers.
• Associerade MVC API-analysverktyg som ingår när IncludeOpenAPIAnalyzers är true.