Vue d’ensemble de l’analyse du code source .NET

Les analyseurs .NET Compiler Platform (Roslyn) inspectent la qualité et les problèmes de styles de votre code C# ou Visual Basic. À compter de .NET 5, ces analyseurs sont inclus dans le Kit de développement logiciel (SDK) .NET et vous n’avez pas besoin de les installer séparément. Si votre projet cible .NET 5 ou version ultérieure, l’analyse du code est activée par défaut. Si votre projet cible une autre implémentation .NET, par exemple .NET Core, .NET Standard ou .NET Framework, vous devez activer manuellement l’analyse du code en définissant la propriété EnableNETAnalyzers sur true.

Si vous ne souhaitez pas passer au Kit de développement logiciel (SDK) .NET 5+, disposez d’un projet .NET Framework de style non SDK ou préférez un modèle basé sur un package NuGet, les analyseurs sont également disponibles dans le package NuGet Microsoft.CodeAnalyzers. Vous préférerez peut-être un modèle basé sur un package pour les mises à jour de version à la demande.

Si des violations de règle sont détectées par un analyseur, elles sont signalées comme une suggestion, un avertissement ou une erreur, selon la façon dont chaque règle est configurée. Les violations d’analyse du code apparaissent avec le préfixe « CA » ou « IDE » pour les différencier des erreurs du compilateur.

Analyse de la qualité du code

Les règles d’analyse de la qualité du code (« CAxxxx ») inspectent votre code C# ou Visual Basic pour la sécurité, les performances, la conception et d’autres problèmes. L’analyse est activée par défaut pour les projets ciblant .NET 5 ou ultérieur. Vous pouvez activer l’analyse du code sur les projets ciblant des versions antérieures de .NET en affectant à la propriété EnableNETAnalyzers la valeur true. Vous pouvez aussi désactiver l’analyse du code pour votre projet en affectant à EnableNETAnalyzers la valeur false.

Règles activées

Vous pouvez modifier la gravité de ces règles pour les désactiver ou les élever au niveau d’erreur. Vous pouvez également activer d’autres règles.

• Pour obtenir la liste des règles incluses dans chaque version du Kit de développement logiciel (SDK) .NET, consultez lesversions de l’analyseur.
• Pour obtenir la liste de toutes les règles de qualité du code, consultez les Règles de qualité du code.

Activer des règles supplémentaires

Le mode d’analyse fait référence à une configuration d’analyse de code prédéfinie, où aucune, certaines ou toutes les règles sont activées. Dans le mode d’analyse par défaut (Default), seul un petit nombre de règles sont activées en tant qu’avertissements de build. Vous pouvez modifier le mode d’analyse de votre projet en définissant la propriété <AnalysisMode> dans le fichier projet. Les valeurs autorisées sont les suivantes :

À compter de .NET 6, vous pouvez omettre <AnalysisMode> en faveur d’une valeur composée pour la propriété <AnalysisLevel>. Par exemple, la valeur suivante active l’ensemble de règles recommandé pour la dernière version : <AnalysisLevel>latest-Recommended</AnalysisLevel>. Pour plus d’informations, consultez AnalysisLevel.

Pour rechercher la gravité par défaut de chaque règle disponible et si la règle est activée ou non dans le mode d’analyse de Default, consultez la liste complète des règles.

Considérer les avertissements comme des erreurs

Si vous utilisez l’indicateur -warnaserror lorsque vous générez vos projets, tous les avertissements d’analyse du code sont également traités comme des erreurs. Si vous ne souhaitez pas que les avertissements de qualité du code (CAxxxx) soient traités comme des erreurs en présence de -warnaserror, vous pouvez définir la propriété CodeAnalysisTreatWarningsAsErrors MSBuild sur false dans votre fichier projet.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

Vous verrez toujours des avertissements d’analyse du code, mais ils n’interrompront pas votre build.

Dernières mises à jour

Par défaut, vous obtenez les dernières règles d’analyse du code et les gravités des règles par défaut lorsque vous effectuez une mise à niveau vers des versions plus récentes du Kit de développement logiciel (SDK) .NET. Si vous ne souhaitez pas ce comportement, par exemple, si vous souhaitez vous assurer qu’aucune nouvelle règle n’est activée ou désactivée, vous pouvez la remplacer de l’une des manières suivantes :

• Définissez la propriété MSBuild AnalysisLevel sur une valeur spécifique pour verrouiller les avertissements sur ce jeu. Lorsque vous effectuez une mise à niveau vers un SDK plus récent, vous obtenez toujours des correctifs de bogues pour ces avertissements, mais aucun nouvel avertissement n’est activé et aucun avertissement existant n’est désactivé. Par exemple, pour verrouiller l’ensemble de règles sur celles fournies avec la version 5.0 du KIT de développement logiciel (SDK) .NET, ajoutez l’entrée suivante à votre fichier projet.

  <PropertyGroup>
    <AnalysisLevel>5.0</AnalysisLevel>
  </PropertyGroup>
  

  Conseil

  La valeur par défaut de la propriété AnalysisLevel est latest, ce qui signifie que vous obtenez toujours les dernières règles d’analyse du code lorsque vous passez à des versions plus récentes du Kit de développement logiciel (SDK) .NET.

  Pour plus d’informations et pour afficher la liste des valeurs possibles, consultez AnalysisLevel.

• Installez le package Microsoft.CodeAnalysis.NetAnalyzers NuGet pour dissocier les mises à jour des règles à partir des mises à jour du Kit de développement logiciel (SDK) .NET. Pour les projets qui ciblent .NET 5+, l’installation du package désactive les analyseurs intégrés du SDK. Vous recevez un avertissement de build si le SDK contient une version d’assembly d’analyseur plus récente que celle du package NuGet. Pour désactiver l’avertissement, définissez la propriété _SkipUpgradeNetAnalyzersNuGetWarning sur true.

  Notes

  Si vous installez le package Microsoft.CodeAnalysis.NetAnalyzers NuGet, vous ne devez pas ajouter la propriété EnableNETAnalyzers à votre fichier projet ou à un fichier Directory.Build.props. Lorsque le package NuGet est installé et que la propriété EnableNETAnalyzers est définie sur true, un avertissement de build est généré.

Analyse de style de code

Les règles d’analyse de style de code (« IDExxxx ») vous permettent de définir et de maintenir un style de code cohérent dans votre codebase. Les paramètres d’activation par défaut sont les suivants :

• Build de ligne de commande : l’analyse du style de code est désactivée, par défaut, pour tous les projets .NET sur les builds en ligne de commande.

  À compter de .NET 5, vous pouvez activer l’analyse de style de code sur le build, à la fois sur la ligne de commande et dans Visual Studio. Les violations de style de code apparaissent sous forme d’avertissements ou d’erreurs avec un préfixe « IDE ». Cela vous permet d’appliquer des styles de code cohérents au moment de la génération.

• Visual Studio : l’analyse de style de code est activée, par défaut, pour tous les projets .NET à l’intérieur de Visual Studio en tant qu’actions rapides de refactorisation du code.

Pour obtenir la liste complète des règles d’analyse de style de code, consultez Règles de style de code.

Activer sur le build

Avec le Kit de développement logiciel (SDK) .NET 5 et les versions ultérieures, vous pouvez activer l’analyse du style du code lors de la génération à partir de la ligne de commande et dans Visual Studio. (Toutefois, pour des raisons de performances, une poignée de règles de style code s’applique toujours uniquement dans l’IDE Visual Studio.)

Suivez ces étapes pour activer l’analyse de style de code sur le build :

1. Définissez la propriété MSBuild EnforceCodeStyleInBuild sur true.

2. Dans un fichier .editorconfig, configurez chaque règle de style de code « IDE » que vous souhaitez exécuter sur build en tant qu’avertissement ou erreur. Par exemple :

   [*.{cs,vb}]
   # IDE0040: Accessibility modifiers required (escalated to a build warning)
   dotnet_diagnostic.IDE0040.severity = warning
   

   Conseil

   À compter de .NET 9, vous pouvez également utiliser le format d’option pour spécifier une gravité et faire en sorte qu’elle soit respectée au moment de la build. Par exemple :

   [*.{cs,vb}]
   # IDE0040: Accessibility modifiers required (escalated to a build warning)
   dotnet_style_require_accessibility_modifiers = always:warning
   

   Vous pouvez également configurer une catégorie entière pour qu’elle soit un avertissement ou une erreur, par défaut, puis désactiver sélectivement les règles de cette catégorie que vous ne souhaitez pas exécuter sur le build. Par exemple :

   [*.{cs,vb}]
   
   # Default severity for analyzer diagnostics with category 'Style' (escalated to build warnings)
   dotnet_analyzer_diagnostic.category-Style.severity = warning
   
   # IDE0040: Accessibility modifiers required (disabled on build)
   dotnet_diagnostic.IDE0040.severity = silent
   

Supprimer un avertissement

Une façon de supprimer une violation de règle consiste à définir l’option de gravité de cet ID de règle sur none dans un fichier EditorConfig. Par exemple :

dotnet_diagnostic.CA1822.severity = none

Pour plus d’informations et d’autres façons de supprimer les avertissements, consultez Comment supprimer les avertissements d’analyse du code.

Analyseurs tiers

Outre les analyseurs .NET officiels, vous pouvez également installer des analyseurs tiers, tels que StyleCop, Roslynator, XUnit Analyzers et Sonar Analyzer.

Voir aussi

• Référence de règle d’analyse de la qualité du code
• Référence de règle d’analyse du style de code
• Analyse du code dans Visual Studio
• SDK .NET Compiler Platform
• Tutoriel : Écrire votre premier analyseur et correctif de code
• Analyse du code dans les applications ASP.NET Core