La propriété IncludeOpenAPIAnalyzers et les analyseurs d’API MVC sont déconseillés

La IncludeOpenAPIAnalyzers propriété MSBuild et ses analyseurs d’API MVC associés sont déconseillés et seront supprimés dans une prochaine version. Lorsque la valeur de IncludeOpenAPIAnalyzers est définie sur true, la build émet désormais un avertissement ASPDEPR007.

Version introduite

.NET 10 Preview 7

Comportement précédent

Auparavant, vous pouvez définir <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> dans vos projets de SDK Web pour activer les analyseurs d’API MVC sans avertissements ni avis de dépréciation.

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

Un tel projet a été construit avec succès sans avertissements de dépréciation.

Nouveau comportement

À partir de .NET 10, lorsque IncludeOpenAPIAnalyzers est défini sur true, la compilation émet un avertissement ASPDEPR007:

avertissement ASPDEPR007 : la propriété IncludeOpenAPIAnalyzers et ses analyseurs d’API MVC associés sont déconseillés et seront supprimés dans une prochaine version.

Les analyseurs continuent de fonctionner, mais les développeurs reçoivent cet avertissement d'obsolescence pendant la compilation.

Type de changement cassant

Cette modification peut affecter la compatibilité source .

Raison de la modification

Les analyseurs d’API MVC ont été introduits à l’origine pour aider à conserver les types et attributs de retour synchronisés pour les contrôleurs d’API, garantissant ainsi la cohérence entre les signatures de méthode et leur documentation OpenAPI correspondante. Ces analyseurs ont fourni une validation au moment de la compilation pour intercepter les incompatibilités entre les types de retour déclarés et les types réels retournés par les actions du contrôleur.

Toutefois, avec l’introduction d’API minimales et du TypedResults modèle, l’écosystème .NET a évolué vers une approche plus sécurisée pour le développement d’API. TypedResults fournit des garanties au moment de la compilation sur les types de réponse sans nécessiter d’analyseurs supplémentaires, ce qui rend les analyseurs d’API MVC redondants pour les applications .NET modernes. Dans .NET 10, TypedResults sont pris en charge dans les API basées sur le contrôleur.

Approche précédente avec les analyseurs d’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)
}

Approche moderne avec 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);
}

Le TypedResults modèle élimine le besoin d’analyseurs distincts, car le type de retour lui-même (Results<Ok<Product>, NotFound>) déclare explicitement tous les types de réponse possibles au moment de la compilation. Cette approche est plus gérable, offre une meilleure prise en charge d’IntelliSense et génère automatiquement une documentation OpenAPI précise sans outils supplémentaires.

À mesure que l’écosystème .NET continue d’adopter TypedResults le modèle recommandé pour le développement d’API, les analyseurs d’API MVC sont devenus obsolètes et sont déconseillés pour simplifier l’expérience de développement.

Action recommandée

Les développeurs doivent :

• Supprimez la propriété déconseillée : Supprimez <IncludeOpenAPIAnalyzers>true</IncludeOpenAPIAnalyzers> de vos fichiers projet pour éliminer l’avertissement.
• Migrer vers TypedResults: migrer vers le modèle pour garantir une meilleure cohérence entre le TypedResults comportement de l’application et la documentation OpenAPI.

Si vous devez continuer à utiliser temporairement les analyseurs déconseillés, vous pouvez supprimer l’avertissement :

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

API affectées

• Propriété MSBuild : IncludeOpenAPIAnalyzers.
• Analyseurs d'API MVC associés inclus quand IncludeOpenAPIAnalyzers est true.