A propriedade IncludeOpenAPIAnalyzers e os analisadores de API MVC foram preteridos

A IncludeOpenAPIAnalyzers propriedade MSBuild e seus analisadores de API MVC associados foram preteridos e serão removidos em uma versão futura. Quando IncludeOpenAPIAnalyzers está definido como true, a compilação agora emite um aviso ASPDEPR007.

Versão introduzida

.NET 10 Prévia 7

Comportamento anterior

Anteriormente, você podia definir <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> em seus projetos de SDK da Web para habilitar analisadores de API MVC sem avisos ou avisos de descontinuação.

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

Tal projeto construído com sucesso sem quaisquer avisos de depreciação.

Novo comportamento

A partir do .NET 10, quando IncludeOpenAPIAnalyzers definido como true, a compilação emite um aviso ASPDEPR007:

aviso ASPDEPR007: A propriedade IncludeOpenAPIAnalyzers e seus analisadores de API MVC associados foram preteridos e serão removidos em uma versão futura.

Os analisadores continuam a funcionar, mas os desenvolvedores recebem esse aviso de descontinuação durante a compilação.

Tipo de mudança disruptiva

Essa alteração pode afetar compatibilidade da fonte.

Motivo da mudança

Os analisadores de API MVC foram originalmente introduzidos para ajudar a manter os tipos e atributos de retorno sincronizados para controladores de API, garantindo a consistência entre as assinaturas de método e sua documentação OpenAPI correspondente. Esses analisadores forneceram validação em tempo de compilação para detetar incompatibilidades entre os tipos de retorno declarados e os tipos reais retornados por ações do controlador.

No entanto, com a introdução de APIs mínimas e o TypedResults padrão, o ecossistema .NET evoluiu para uma abordagem mais segura para o desenvolvimento de APIs. TypedResults fornece garantias em tempo de compilação sobre tipos de resposta sem exigir analisadores adicionais, tornando os analisadores de API MVC redundantes para aplicativos .NET modernos. No .NET 10, TypedResults há suporte em APIs baseadas em controlador.

Abordagem anterior com analisadores de 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)
}

Abordagem moderna com 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);
}

O TypedResults padrão elimina a necessidade de analisadores separados porque o próprio tipo de retorno (Results<Ok<Product>, NotFound>) declara explicitamente todos os tipos de resposta possíveis em tempo de compilação. Essa abordagem é mais fácil de manter, fornece melhor suporte ao IntelliSense e gera automaticamente documentação precisa da OpenAPI sem ferramentas adicionais.

À medida que o ecossistema .NET continua a adotar TypedResults como o padrão recomendado para o desenvolvimento de APIs, os analisadores de API MVC tornaram-se obsoletos e estão sendo preteridos para simplificar a experiência de desenvolvimento.

Ação recomendada

Os desenvolvedores devem:

• Remova a propriedade preterida: remova <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> dos arquivos de projeto para eliminar o aviso.
• Migrar para TypedResults: Migre para o padrão para garantir uma melhor consistência entre o comportamento do aplicativo e a TypedResults documentação da OpenAPI.

Se você precisar continuar usando os analisadores preteridos temporariamente, poderá suprimir o aviso:

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

APIs afetadas

• Propriedade MSBuild: IncludeOpenAPIAnalyzers.
• Analisadores de API MVC associados incluídos quando IncludeOpenAPIAnalyzers é true.