La propiedad IncludeOpenAPIAnalyzers y los analizadores de API de MVC están en desuso

La IncludeOpenAPIAnalyzers propiedad MSBuild y sus analizadores de API de MVC asociados están en desuso y se quitarán en una versión futura. Cuando IncludeOpenAPIAnalyzers se establece en true, la compilación ahora emite la advertencia ASPDEPR007.

Versión introducida

.NET 10 Preview 7

Comportamiento anterior

Anteriormente, podía establecer <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> en los proyectos del SDK web para habilitar analizadores de API de MVC sin advertencias ni avisos de desuso.

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

Este proyecto se ha compilado correctamente sin advertencias de desuso.

Nuevo comportamiento

A partir de .NET 10, cuando IncludeOpenAPIAnalyzers se establece trueen , la compilación emite la advertencia ASPDEPR007:

advertencia ASPDEPR007: la propiedad IncludeOpenAPIAnalyzers y sus analizadores de API de MVC asociados están en desuso y se quitarán en una versión futura.

Los analizadores siguen funcionando, pero los desarrolladores reciben esta advertencia de desuso durante la compilación.

Tipo de cambio disruptivo

Este cambio puede afectar a la compatibilidad de orígenes.

Motivo del cambio

Los analizadores de API de MVC se introdujeron originalmente para ayudar a mantener sincronizados los tipos de valor devuelto y los atributos para los controladores de API, lo que garantiza la coherencia entre las firmas de método y su documentación correspondiente de OpenAPI. Estos analizadores proporcionaron validación en tiempo de compilación para detectar errores de coincidencia entre los tipos devueltos declarados y los tipos reales devueltos por las acciones del controlador.

Sin embargo, con la introducción de las API mínimas y el TypedResults patrón, el ecosistema de .NET ha evolucionado hacia un enfoque más seguro para el desarrollo de API. TypedResults proporciona garantías en tiempo de compilación sobre los tipos de respuesta sin necesidad de analizadores adicionales, lo que hace que los analizadores de API de MVC sean redundantes para las aplicaciones modernas de .NET. En .NET 10, TypedResults se admiten en las API basadas en el controlador.

Enfoque anterior con analizadores de API de 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)
}

Enfoque moderno con 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);
}

El TypedResults patrón elimina la necesidad de analizadores independientes porque el propio tipo de valor devuelto (Results<Ok<Product>, NotFound>) declara explícitamente todos los tipos de respuesta posibles en tiempo de compilación. Este enfoque es más fácil de mantener, proporciona una mejor compatibilidad con IntelliSense y genera automáticamente documentación precisa de OpenAPI sin herramientas adicionales.

A medida que el ecosistema de .NET sigue adoptando TypedResults como patrón recomendado para el desarrollo de API, los analizadores de API de MVC se han quedado obsoletos y están en desuso para simplificar la experiencia de desarrollo.

Acción recomendada

Los desarrolladores deben:

• Quite la propiedad en desuso: quite <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> de los archivos del proyecto para eliminar la advertencia.
• Migrar a TypedResults: migre al TypedResults patrón para garantizar una mejor coherencia entre el comportamiento de la aplicación y la documentación de OpenAPI.

Si necesita seguir usando temporalmente los analizadores en desuso, puede suprimir la advertencia:

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

Las APIs afectadas

• Propiedad de MSBuild: IncludeOpenAPIAnalyzers.
• Los analizadores de API de MVC asociados se incluyen cuando IncludeOpenAPIAnalyzers es true.