Właściwość IncludeOpenAPIAnalyzers i analizatory interfejsu API MVC są przestarzałe

Właściwość IncludeOpenAPIAnalyzers MSBuild i skojarzone z nią analizatory interfejsu API MVC są przestarzałe i zostaną usunięte w przyszłej wersji. Gdy IncludeOpenAPIAnalyzers jest ustawiona wartość true, kompilacja emituje teraz ostrzeżenie ASPDEPR007.

Wersja wprowadzona

.NET 10 (wersja zapoznawcza 7)

Poprzednie zachowanie

Wcześniej można było ustawić <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> w projektach zestawu SDK sieci Web, aby włączyć analizatory interfejsu API MVC bez żadnych ostrzeżeń ani powiadomień o wycofaniu.

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

Taki projekt został utworzony pomyślnie bez żadnych ostrzeżeń o wycofaniu.

Nowe zachowanie

Począwszy od platformy .NET 10, gdy IncludeOpenAPIAnalyzers jest ustawiona wartość true, kompilacja emituje ostrzeżenie ASPDEPR007:

ostrzeżenie ASPDEPR007: właściwość IncludeOpenAPIAnalyzers i skojarzone z nią analizatory interfejsu API MVC są przestarzałe i zostaną usunięte w przyszłej wersji.

Analizatory nadal działają, ale deweloperzy otrzymują to ostrzeżenie o wycofaniu podczas kompilacji.

Typ zmiany przełamującej

Ta zmiana może mieć wpływ na zgodność źródła .

Przyczyna zmiany

Analizatory interfejsu API MVC zostały pierwotnie wprowadzone w celu zapewnienia synchronizacji typów zwracanych i atrybutów dla kontrolerów interfejsu API, zapewniając spójność między podpisami metod i odpowiednią dokumentacją interfejsu OpenAPI. Te analizatory dostarczyły weryfikacji czasu kompilacji w celu przechwycenia niezgodności między zadeklarowanych typów zwracanych a rzeczywistymi typami zwracanych przez akcje kontrolera.

Jednak wraz z wprowadzeniem minimalnych interfejsów API i TypedResults wzorca ekosystem platformy .NET ewoluował w kierunku bardziej bezpiecznego podejścia do opracowywania interfejsów API. TypedResults Zapewnia gwarancje czasu kompilacji dotyczące typów odpowiedzi bez konieczności dodatkowych analizatorów, dzięki czemu analizatory interfejsu API MVC są nadmiarowe dla nowoczesnych aplikacji platformy .NET. W programie .NET 10 TypedResults są obsługiwane w interfejsach API opartych na kontrolerach.

Poprzednie podejście z analizatorami interfejsu 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)
}

Nowoczesne podejście z usługą 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);
}

Wzorzec TypedResults eliminuje potrzebę oddzielnych analizatorów, ponieważ sam typ zwracany (Results<Ok<Product>, NotFound>) jawnie deklaruje wszystkie możliwe typy odpowiedzi w czasie kompilacji. Takie podejście jest bardziej konserwowalne, zapewnia lepszą obsługę funkcji IntelliSense i automatycznie generuje dokładną dokumentację interfejsu OpenAPI bez dodatkowych narzędzi.

Ponieważ ekosystem platformy .NET nadal przyjmuje TypedResults się jako zalecany wzorzec tworzenia interfejsu API, analizatory interfejsu API MVC stały się przestarzałe i są przestarzałe, aby usprawnić środowisko programistyczne.

Zalecana akcja

Deweloperzy powinni:

• Usuń przestarzałą właściwość: Usuń <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> z plików projektu, aby wyeliminować ostrzeżenie.
• Migrowanie do : Migrowanie do TypedResultswzorca w celu zapewnienia lepszej spójności między zachowaniem aplikacji a dokumentacją interfejsu TypedResults OpenAPI.

Jeśli musisz tymczasowo korzystać z przestarzałych analizatorów, możesz pominąć ostrzeżenie:

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

Interfejsy API, których dotyczy problem

• Właściwość MSBuild: IncludeOpenAPIAnalyzers.
• Skojarzone analizatory interfejsu API MVC uwzględnione, gdy IncludeOpenAPIAnalyzers ma wartość true.