A propriedade IncludeOpenAPIAnalyzers e os analisadores da API do MVC estão obsoletos

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

Versão introduzida

.NET 10 Versão Prévia 7

Comportamento anterior

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

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

Esse projeto foi criado com êxito sem avisos de obsolescência.

Novo comportamento

A partir do .NET 10, quando IncludeOpenAPIAnalyzers definido como true, o build emite o 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 funcionando, mas os desenvolvedores recebem esse aviso de descontinuação durante a compilação.

Tipo de mudança disruptiva

Essa alteração pode afetar a compatibilidade da origem.

Motivo da alteração

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

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

Abordagem anterior com analisadores de API do 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 mantenedível, fornece melhor suporte ao IntelliSense e gera automaticamente uma documentação precisa do OpenAPI sem ferramentas adicionais.

À medida que o ecossistema do .NET continua a adotar TypedResults como o padrão recomendado para o desenvolvimento de API, os analisadores de API do 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 do projeto para eliminar o aviso.
• Migre para TypedResults: Migre para o TypedResults padrão para garantir uma melhor consistência entre o comportamento do aplicativo e a documentação do 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.