De eigenschap IncludeOpenAPIAnalyzers en MVC API Analyzers zijn afgeschaft

De IncludeOpenAPIAnalyzers MSBuild-eigenschap en de bijbehorende MVC API-analyses zijn afgeschaft en worden verwijderd in een toekomstige release. Wanneer IncludeOpenAPIAnalyzers dit is ingesteld true, wordt er nu een waarschuwing ASPDEPR007verzonden in de build.

Geïntroduceerde versie

.NET 10 Preview 7

Vorig gedrag

Eerder kon u in uw Web SDK-projecten <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> instellen om MVC API-analyzers te activeren zonder waarschuwingen of deprecatiewaarschuwingen.

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

Een dergelijk project is gebouwd zonder eventuele afschaffingswaarschuwingen.

Nieuw gedrag

Vanaf .NET 10, wanneer IncludeOpenAPIAnalyzers deze is ingesteld trueop, verzendt de build de waarschuwing ASPDEPR007:

waarschuwing ASPDEPR007: de eigenschap IncludeOpenAPIAnalyzers en de bijbehorende MVC API-analyses zijn afgeschaft en worden verwijderd in een toekomstige release.

De analysefuncties blijven functioneren, maar ontwikkelaars ontvangen deze afschaffingswaarschuwing tijdens de compilatie.

Type van brekende verandering

Deze wijziging kan invloed hebben op broncompatibiliteit.

Reden voor wijziging

De MVC API-analyses zijn oorspronkelijk geïntroduceerd om retourtypen en kenmerken gesynchroniseerd te houden voor API-controllers, waardoor consistentie tussen methodehandtekeningen en de bijbehorende OpenAPI-documentatie wordt gegarandeerd. Deze analysefuncties bieden compileertijdvalidatie om niet-overeenkomende waarden te detecteren tussen gedeclareerde retourtypen en de werkelijke typen die worden geretourneerd door controlleracties.

Met de introductie van minimale API's en het patroon is het TypedResults .NET-ecosysteem echter verder ontwikkeld naar een meer typeveilige benadering voor API-ontwikkeling. TypedResults biedt gecompileerd-tijdgaranties over antwoordtypen zonder extra analyses te vereisen, waardoor de MVC API-analyses redundant zijn voor moderne .NET-toepassingen. In .NET 10 TypedResults worden deze ondersteund in api's op basis van een controller.

Vorige benadering met MVC API-analyse:

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

Moderne benadering met 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);
}

Het TypedResults patroon elimineert de noodzaak van afzonderlijke analysen omdat het retourtype zelf (Results<Ok<Product>, NotFound>) expliciet alle mogelijke antwoordtypen tijdens het compileren declareert. Deze aanpak is beter te onderhouden, biedt betere IntelliSense-ondersteuning en genereert automatisch nauwkeurige OpenAPI-documentatie zonder extra hulpprogramma's.

Naarmate het .NET-ecosysteem zich blijft omarmen TypedResults als het aanbevolen patroon voor API-ontwikkeling, zijn de MVC API-analyses verouderd geworden en worden ze afgeschaft om de ontwikkelervaring te stroomlijnen.

Aanbevolen actie

Ontwikkelaars moeten:

• Verwijder de afgeschafte eigenschap: Verwijder <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> uit uw projectbestanden om de waarschuwing te elimineren.
• Migreren naar: Migreren naar TypedResultshet TypedResults patroon om een betere consistentie tussen toepassingsgedrag en OpenAPI-documentatie te garanderen.

Als u de afgeschafte analyses tijdelijk wilt blijven gebruiken, kunt u de waarschuwing onderdrukken:

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

Betreffende API's

• MSBuild eigenschap: IncludeOpenAPIAnalyzers.
• Gekoppelde MVC API-analysen die zijn opgenomen wanneerIncludeOpenAPIAnalyzers.true