Personnaliser les règles de l’analyseur Roslyn

Chaque règle d'analyseur Roslyn, ou diagnostic, a une gravité et un état de suppression par défaut que vous pouvez personnaliser pour votre projet. Cet article traite de la définition des niveaux de gravité des règles de l’analyseur, et de la suppression des violations de règles détectées par l’analyseur.

Niveaux de gravité

Dans Visual Studio 2019 version 16.3 et ultérieures, vous pouvez configurer la gravité des règles de l'analyseur dans un fichier EditorConfig, à partir du menu Ampoule et de la fenêtre Liste d'erreurs.

Le tableau suivant présente les différentes options de gravité que vous pouvez configurer pour un diagnostic :

Gravité (Explorateur de solutions)	Gravité (fichier EditorConfig)	Comportement lors de la création	Comportement de l’éditeur
Erreur	error	Les violations apparaissent dans l'onglet Erreur de la fenêtre Liste d'erreurs et dans la sortie de compilation en ligne de commande, et entraînent l'échec de la compilation.	Le code incriminé est souligné par un gribouillis rouge et signalé par un petit cadre rouge dans la barre de défilement.
Avertissement	warning	Les violations apparaissent dans l'onglet Avertissement de la fenêtre Liste d'erreurs et dans la sortie de compilation en ligne de commande, mais n'entraînent pas l'échec de la compilation.	Le code incriminé est souligné par une ligne verte et marqué par un petit cadre vert dans la barre de défilement.
Suggestion	suggestion	Les violations apparaissent dans l'onglet Message de la fenêtre Liste d'erreurs, mais pas dans les résultats de la compilation en ligne de commande.	Le code concerné est souligné par une ligne grise et marqué par une petite boîte grise dans la barre de défilement.
Silencieux	silent	Invisible pour l'utilisateur.	Invisible pour l'utilisateur, mais le diagnostic est signalé au moteur de diagnostic IDE.
Aucun	none	Entièrement supprimé.	Entièrement supprimé.
Default	default	Correspond à la gravité par défaut de la règle. Pour déterminer la valeur par défaut d'une règle, affichez sa fenêtre Propriétés.	Correspond à la gravité par défaut de la règle.

Afficher les violations de règle

Si un analyseur détecte des violations de règle d'analyseur, il les signale dans la fenêtre Liste d'erreurs et dans l'éditeur de code.

La capture d'écran suivante montre les violations de règle signalées dans la fenêtre Liste d'erreurs. Les violations détectées par l'analyseur, et qui sont signalées dans la liste d'erreurs, correspondent au paramètre de niveau de gravité de la règle :

Les violations des règles de l'analyseur apparaissent également dans l'éditeur de code sous la forme de lignes gribouillées sous le code incriminé. Par exemple, la capture d'écran suivante montre trois violations : une erreur (ligne rouge), un avertissement (ligne verte) et une suggestion (trois points gris) :

De nombreux diagnostics sont associées à un ou plusieurs correctifs de code que vous pouvez appliquer pour corriger la violation de règle. Les correctifs de code sont affichés dans l’icône du menu Ampoule, avec d’autres types d’Actions rapides. Pour plus d'informations sur les correctifs de code, consultez Actions rapides courantes.

Configurer les niveaux de gravité

Vous pouvez définir la gravité de la règle à l'aide de l'une des méthodes suivantes :

• EditorConfig
• Menu ampoule
• Fenêtre Liste d’erreurs
• Explorateur de solutions

Sévérité silencieuse ou nulle

Les règles de gravité Silent activées par défaut diffèrent des règles de gravité désactivées ou None :

• Si un correctif de code est inscrit pour une règle de gravité Silent, Visual Studio propose le code correctif sous forme d'action de refactorisation du code symbolisée par une ampoule, même si le diagnostic masqué n'est pas visible pour l'utilisateur. Si la règle de sévérité est désactivée en tant que None, la correction de code n'est pas proposée.
• Les entrées qui définissent la gravité de plusieurs règles d'analyseur à la fois dans un fichier EditorConfig permettent de configurer en bloc des règles de gravité Silent. Les règles de gravité None ne peuvent pas être configurées de cette façon. À la place, vous devez les configurer via des entrées qui définissent la gravité dans un fichier EditorConfig pour chaque ID de règle.

Définir la gravité d’une règle dans un fichier EditorConfig

Les fichiers EditorConfig sont disponibles dans Visual Studio 2019 version 16.3 et ultérieures.

La définition de la gravité d'une règle dans un fichier EditorConfig est prioritaire sur toute autre gravité définie dans un ensemble de règles ou dans l'Explorateur de solutions. Vous pouvez configurer manuellement la gravité dans un fichier EditorConfig, ou automatiquement via l'ampoule qui apparaît en regard d'une violation.

Configurer manuellement la gravité des règles dans un fichier EditorConfig

Pour configurer la gravité des règles, procédez comme suit :

1. Ajoutez un fichier EditorConfig à votre projet, si vous n'en avez pas déjà un.

2. Ajoutez une entrée pour chaque règle à configurer sous l’extension de fichier correspondante.

   Par exemple, l'entrée permettant de définir la gravité de CA1822 sur error pour les fichiers C# est la suivante :

   [*.cs]
   dotnet_diagnostic.CA1822.severity = error
   

3. Vous pouvez définir la gravité de la règle pour chaque ID de règle de diagnostic dans un fichier EditorConfig avec la syntaxe suivante :

   dotnet_diagnostic.<rule ID>.severity = <severity>

4. Pour les analyseurs de code des IDE, vous pouvez également les configurer dans un fichier EditorConfig en utilisant une autre syntaxe.

   Par exemple : dotnet_style_qualification_for_field = false:suggestion. Toutefois, si vous définissez une gravité à l’aide de la syntaxe dotnet_diagnostic, elle est prioritaire. Pour plus d’informations, consultez Conventions de langage pour EditorConfig.

Définir la gravité de plusieurs règles d'analyseur à la fois dans un fichier EditorConfig

La possibilité de définir plusieurs règles d'analyseur à la fois dans un fichier EditorConfig est disponible dans Visual Studio 2019 version 16.5 et ultérieures.

Vous pouvez définir la gravité d'une catégorie spécifique de règle d'analyseur ou de toutes les règles d'analyseur à l'aide d'une seule entrée dans un fichier EditorConfig :

• Définissez la gravité des règles pour une catégorie de règle d'analyseur :

  dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity>

• Définissez la gravité des règles pour toutes les règles de l'analyseur :

  dotnet_analyzer_diagnostic.severity = <severity>

Les entrées qui configurent plusieurs règles d'analyse en même temps ne s'appliquent qu'aux règles activées par défaut. Les règles d’analyseur marquées comme désactivées par défaut dans le package de l’analyseur doivent être activées via des entrées dotnet_diagnostic.<rule ID>.severity = <severity> explicites.

Si plusieurs entrées sont applicables à un ID de règle spécifique, l'ordre de priorité de l'entrée applicable est le suivant :

• L'entrée d'une gravité d'une règle individuelle basée sur l'ID est prioritaire sur l'entrée d'une gravité d'une catégorie.
• L'entrée d'une gravité d'une catégorie est prioritaire sur l'entrée de gravité de toutes les règles de l'analyseur.

Considérez l'exemple EditorConfig suivant, où CA1822 est une règle de performance :

[*.cs]
dotnet_diagnostic.CA1822.severity = error
dotnet_analyzer_diagnostic.category-performance.severity = warning
dotnet_analyzer_diagnostic.severity = suggestion

Dans cet exemple, les trois entrées s'appliquent à la règle de performance CA1822. Toutefois, en raison des règles de priorité spécifiées, la première entrée de gravité basée sur l'ID de règle est prioritaire sur les entrées suivantes. Dans cet exemple, la gravité réelle de CA1822 est error. Les règles de performances restantes ont une gravité de warning. Les règles d'analyseur qui ne sont pas des règles de performances ont une gravité de suggestion.

Définir la gravité des règles à partir du menu Ampoule

Visual Studio offre un moyen pratique de configurer la gravité d’une règle à partir du menu Ampoule Actions rapides. Effectuez les étapes suivantes :

1. Une fois qu'une violation s'est produite, pointez sur le soulignement ondulé représentant la violation dans l'éditeur, puis choisissez Afficher les corrections potentielles pour ouvrir le menu Ampoule. Vous pouvez également placer votre curseur sur la ligne, puis appuyer sur Ctrl+. (point).

2. Dans le menu Ampoule, survolez un niveau de gravité pour obtenir un aperçu des modifications, puis configurez la gravité selon les options suivantes :

   • Configurez la gravité de <l'ID de règle>. Définissez la gravité de la règle spécifique.

   • Configurez la gravité pour tous les analyseurs de <style>. Définissez la gravité de toutes les règles dans la catégorie de règle spécifique.

   • Configurez la gravité pour tous les analyseurs. Définissez la gravité pour toutes les catégories de règles de l'analyseur.

     Dans l'exemple suivant, sélectionnez Configurer ou supprimer des problèmes>Configurer la gravité de <ID> de règle.

     

3. Choisissez ensuite l'une des options de gravité.

   

   Visual Studio ajoute une entrée au fichier EditorConfig pour configurer la règle au niveau de gravité demandé, comme le montre la zone d'aperçu.

   Si vous n’avez pas encore de fichier EditorConfig dans le projet, Visual Studio en crée un à votre place.

Définir la gravité d’une règle à partir de la fenêtre Liste d’erreurs

Visual Studio fournit également un moyen pratique de configurer la gravité d’une règle à partir du menu contextuel de la liste d’erreurs. Effectuez les étapes suivantes :

1. Quand une violation se produit, cliquez avec le bouton droit sur l’entrée de diagnostic dans la liste d’erreurs.

2. Dans le menu contextuel, sélectionnez Définir la gravité, puis sélectionnez l'une des options de gravité.

   

   Visual Studio ajoute une entrée au fichier EditorConfig pour configurer la règle au niveau demandé.

   Si vous n’avez pas encore de fichier EditorConfig dans le projet, Visual Studio en crée un à votre place.

Définir la gravité des règles à partir de l’Explorateur de solutions

Pour définir la gravité de la règle à partir de Explorateur de solutions, procédez comme suit :

1. Dans l’Explorateur de solutions, développez Références>Analyseurs (ou Dépendances>Analyseurs pour les projets .NET Core).

2. Développez l'assembly qui contient la règle dont vous souhaitez définir la gravité.

3. Cliquez avec le bouton droit sur la règle, puis sélectionnez Définir la gravité. Dans le menu contextuel, choisissez l’une des options de gravité.

   Visual Studio ajoute une entrée au fichier EditorConfig pour configurer la règle au niveau demandé. Si votre projet utilise un fichier d'ensemble de règles à la place d'un fichier EditorConfig, l'entrée de gravité est ajoutée au fichier d'ensemble de règles.

   Si vous n'avez pas encore de fichier EditorConfig ou de fichier d'ensemble de règles dans le projet, Visual Studio crée un fichier EditorConfig à votre place.

Afficher les analyseurs et les diagnostics à partir de Explorateur de solutions

Vous pouvez personnaliser la majeure partie des diagnostics de l’analyseur à partir de l’Explorateur de solutions. Si vous installez un analyseur en tant que package NuGet, un nœud Analyseurs apparaît sous le nœud Références (ou le nœud Dépendances pour les projets .NET Core) dans l'explorateur de solutions. Procédez comme suit pour afficher les analyseurs et les diagnostics :

1. Dans Explorateur de solutions, développez votre projet, développez Références ou dépendances, puis développez Analyseurs. Développez l'un des assemblys d'analyseur pour afficher les diagnostics dans l'assembly.

   L'icône en regard de chaque diagnostic indique son niveau de gravité :

   • x dans un cercle indique le niveau de gravité Erreur
   • ! dans un triangle indique le niveau de gravité Avertissement
   • i dans un cercle solide indique une gravité de suggestion
   • i dans un cercle en pointillés indique une gravité de Silencieux
   • La flèche pointant vers le bas dans un cercle solide indique une gravité de Aucun

   

2. Pour afficher les propriétés d'un diagnostic, y compris sa description et sa gravité par défaut, cliquez avec le bouton droit sur le diagnostic, puis sélectionnez Propriétés. Vous pouvez également sélectionner le diagnostic, puis appuyer sur Alt+Entrée.

   La fenêtre Propriétés s'affiche.

   

3. Pour afficher les propriétés des règles de style de code (préfixe IDE) dans la fenêtre Propriétés, telles que la gravité par défaut, réglez la propriété EnforceCodeStyleInBuild sur true.

4. Pour la documentation en ligne d'un diagnostic, cliquez avec le bouton droit sur celui-ci, puis sélectionnez Afficher l'aide.

Convertir un fichier d'ensemble de règles existant en fichier EditorConfig

Dans Visual Studio 2019 version 16.5 et versions ultérieures, les fichiers d'ensemble de règles sont dépréciés au profit des fichiers EditorConfig pour la configuration de l'analyseur du code managé. Les fichiers EditorConfig sont plus flexibles et vous permettent de configurer la gravité des règles de l'analyseur ainsi que les options de l'analyseur, notamment les options du style de code de l'IDE Visual Studio. Étant donné que les outils Visual Studio pour la configuration de gravité des règles d'analyseur sont désormais optimisés pour fonctionner avec les fichiers EditorConfig au lieu des fichiers d'ensemble de règles, vous êtes encouragés à convertir tous les projets existants qui utilisent toujours des fichiers d'ensemble de règles.

Lorsque vous convertissez votre fichier d'ensemble de règles existant en fichier EditorConfig, enregistrez-le à la racine de votre dépôt ou dans le dossier solution. Cela garantit que les paramètres de gravité de ce fichier s'appliquent automatiquement à l'ensemble du dépôt ou de la solution, respectivement.

Vous pouvez convertir un fichier d'ensemble de règles existant en fichier EditorConfig à l'aide de l'éditeur d'ensemble de règles ou de la ligne de commande.

Remarque

Les projets .NET Core et .NET Standard ne prennent pas en charge les commandes de menu des ensembles de règles dans l'Explorateur de solutions, par exemple Ouvrir l'ensemble de règles actif. Pour spécifier un ensemble de règles distinct de l’ensemble de règles par défaut pour un projet .NET Core ou .NET Standard, vous devez ajouter manuellement la propriété CodeAnalysisRuleSet au fichier projet. Vous pouvez toujours configurer les règles dans l'ensemble de règles dans l'éditeur d'ensemble de règles.

Pour utiliser l'éditeur d'ensemble de règles, procédez comme suit. Si votre projet utilise déjà un fichier d'ensemble de règles spécifique pour sa valeur de propriété CodeAnalysisRuleSet, vous pouvez le convertir en un fichier EditorConfig équivalent à partir de l'éditeur d'ensemble de règles :

1. Double-cliquez sur le fichier d'ensemble de règles dans l'Explorateur de solutions.

   Le fichier d'ensemble de règles s'ouvre dans l'éditeur d'ensemble de règles avec une barre d'informations cliquable en haut.

   

2. Sélectionnez le lien de la barre d'informations pour migrer le fichier d'éditeur d'ensemble de règles.

3. Dans la boîte de dialogue Enregistrer sous, sélectionnez le répertoire dans lequel vous souhaitez générer le fichier EditorConfig, puis sélectionnez Enregistrer.

   Le fichier EditorConfig généré s'ouvre dans l'éditeur. De plus, la propriété MSBuild CodeAnalysisRuleSet est mise à jour dans le fichier projet pour ne plus référencer le fichier d'ensemble de règles d'origine.

Pour utiliser la ligne de commande, procédez comme suit :

1. Installer le package NuGet Microsoft.CodeAnalysis.RulesetToEditorconfigConverter.

2. Exécutez RulesetToEditorconfigConverter.exe à partir du package installé, en utilisant les chemins du fichier d'ensemble de règles et du fichier EditorConfig en tant qu'arguments de ligne de commande.

   Par exemple :

   Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_editorconfig%>]
   

L'exemple suivant montre un fichier d'ensemble de règles à convertir en fichier EditorConfig :

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="Rules for ConsoleApp" Description="Code analysis rules for ConsoleApp.csproj." ToolsVersion="16.0">
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1001" Action="Warning" />
    <Rule Id="CA1821" Action="Warning" />
    <Rule Id="CA2213" Action="Warning" />
    <Rule Id="CA2231" Action="Warning" />
  </Rules>
</RuleSet>

L'exemple suivant montre le fichier EditorConfig obtenu après la conversion :

# NOTE: Requires **VS2019 16.3** or later

# Rules for ConsoleApp
# Description: Code analysis rules for ConsoleApp.csproj.

# Code files
[*.{cs,vb}]

dotnet_diagnostic.CA1001.severity = warning
dotnet_diagnostic.CA1821.severity = warning
dotnet_diagnostic.CA2213.severity = warning
dotnet_diagnostic.CA2231.severity = warning

Configurer le code généré

Les analyseurs s'exécutent sur les fichiers sources d'un projet et signalent toutes les violations qu'ils trouvent. Toutefois, ces violations ne sont pas utiles pour les fichiers générés par le système. Les exemples sont les fichiers de code générés, tels que les fichiers de code générés par le concepteur, les fichiers source temporaires générés par le système de génération, etc. Pour ces types de fichiers, les utilisateurs ne peuvent pas les modifier manuellement et n'ont pas à se préoccuper de la correction d'éventuelles violations.

Par conséquent, par défaut, le gestionnaire de l'analyseur n'examine que les fichiers portant certains noms, extensions de fichiers ou en-têtes de fichiers autogénérés en tant que fichiers de code générés. Par exemple, un fichier dont le nom finit par .designer.cs ou .generated.cs est considéré comme du code généré. Toutefois, ces heuristiques ne permettent pas toujours d’identifier tous les fichiers de code généré de manière personnalisée dans le code source de l’utilisateur.

Dans Visual Studio 2019 version 16.5 et ultérieure, les utilisateurs finaux peuvent configurer des fichiers et des dossiers spécifiques à traiter comme du code généré dans un fichier EditorConfig.

Suivez les étapes ci-dessous pour ajouter ce genre de configuration :

1. Si vous n’avez pas encore de fichier EditorConfig pour votre projet, ajoutez-en un.

2. Ajoutez l'entrée generated_code = true | false pour les fichiers et dossiers spécifiques. Par exemple, pour traiter tous les fichiers dont le nom se termine par .MyGenerated.cs comme du code généré, utilisez l'entrée suivante :

   [*.MyGenerated.cs]
   generated_code = true
   

Supprimer les violations

Vous pouvez supprimer les violations de règles à l’aide de diverses méthodes. Pour plus d'informations, consultez Supprimer les violations de l'analyse de code.

Utilisation de la ligne de commande

Quand vous générez votre projet à partir de la ligne de commande, les violations de règles s’affichent dans la sortie de build si les conditions suivantes sont remplies :

• Les analyseurs sont installés avec le Kit de développement logiciel (SDK) .NET ou sous forme de package NuGet, et non en tant qu'extension .vsix.

  Pour les analyseurs installés à l'aide du kit SDK .NET, vous devrez peut-être activer les analyseurs. Pour les styles de code, vous pouvez également appliquer des styles de code sur les générations en définissant une propriété MSBuild.

• Une ou plusieurs règles ont été violées dans le code du projet.

• Le niveau de gravité d'une règle violée est défini soit comme un avertissement, auquel cas les violations n'entraînent pas l'échec de la génération, soit comme une erreur, auquel cas les violations entraînent l'échec de la génération.

La verbosité de la sortie de build n’a aucun impact sur l’affichage ou non des violations de règles. Même avec la verbosité quiet, les violations de règles s’affichent dans la sortie de build.

Si vous avez l'habitude d'exécuter des analyses héritées à partir de la ligne de commande, soit avec FxCopCmd.exe, soit par msbuild avec l'indicateur RunCodeAnalysis, vous pouvez le faire avec des analyseurs de code à la place.

Pour voir les violations de règles de l'analyseur sur la ligne de commande quand vous générez votre projet à l'aide de msbuild, exécutez une commande similaire à :

msbuild myproject.csproj /target:rebuild /verbosity:minimal

La capture d’écran suivante montre la sortie de la génération en ligne de commande à partir de la génération d’un projet qui contient une violation de règle d’analyseur :

Projets dépendants

Dans un projet .NET Core, si vous ajoutez une référence à un projet qui possède des analyseurs NuGet, Visual Studio ajoute automatiquement ces analyseurs au projet dépendant. Pour désactiver ce comportement (par exemple, si le projet dépendant est un projet de test unitaire), marquez le package NuGet comme privé en définissant l'attribut PrivateAssets dans le fichier .csproj ou .vbproj du projet référencé :

<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="5.0.0" PrivateAssets="all" />

Contenu connexe

• Vue d’ensemble des analyseurs de code dans Visual Studio
• Envoyer un bogue de l’analyseur de code
• Utiliser des ensembles de règles
• Supprimer les violations de l'analyse de code
• Options de configuration pour l'analyse de code