Personnaliser les règles de l’analyseur Roslyn

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

Niveaux de gravité

Vous pouvez configurer la gravité des règles d’analyseur dans un fichier EditorConfig et à partir du menu ampoule.

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

Gravité (Explorateur de solutions)	Gravité (fichier de configuration EditorConfig)	Comportement au moment de la génération	comportement Rédacteur
Erreur	`error`	Les violations apparaissent sous l’onglet Erreur dans la fenêtre Liste d’erreurs et dans la sortie de build de ligne de commande et provoquent l’échec des builds.	Le code incriminé est souligné avec une ligne de bascule rouge et marquée par une petite boîte rouge dans la barre de défilement.
Avertissement	`warning`	Les violations apparaissent sous l’onglet Avertissement dans la fenêtre Liste d’erreurs et dans la sortie de build de ligne de commande, mais ne provoquent pas l’échec des builds.	Le code incriminé est souligné avec une ligne de bascule verte et marquée par une petite boîte verte dans la barre de défilement.
Suggestion	`suggestion`	Les violations s’affichent sous l’onglet Message dans la fenêtre Liste d’erreurs , mais pas dans la sortie de build de ligne de commande.	Le code affecté est souligné avec une ligne bascule grise et marquée par une petite zone grise dans la barre de défilement.
Silencieux	`silent`	Invisible à l’utilisateur.	Invisible à l’utilisateur, mais le diagnostic est signalé au moteur de diagnostic IDE.
Aucun	`none`	Supprimé complètement.	Supprimé complètement.
Par défaut	`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ègles

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 de l’analyseur signalées dans la liste d’erreurs correspondent au paramètre de niveau de gravité de la règle :

Les violations de règle d’analyseur s’affichent également dans l’éditeur de code en tant que lignes ondulées sous le code en cause. Par exemple, la capture d’écran suivante montre trois violations : une erreur (ligne ondulée rouge), un avertissement (ligne ondulée verte) et une suggestion (trois points gris) :

Capture d’écran montrant les marques d’erreur, d’avertissement et de suggestion dans l’éditeur de code.

De nombreux diagnostics ont un ou plusieurs correctifs de code associés que vous pouvez appliquer pour corriger la violation de règle. Les correctifs de code sont affichés dans le menu d’icône d’ampoule, ainsi que 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
Explorateur de solutions

Gravité silencieuse contre aucune

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

Si un correctif de code est inscrit pour une Silent règle de gravité, Visual Studio propose le correctif de code en tant qu’action de refactorisation du code d’ampoule, même si le diagnostic masqué n’est pas visible pour l’utilisateur. Si la règle de gravité est désactivée en tant que None, le correctif du code n'est pas proposé.
Les entrées qui définissent la gravité de plusieurs règles d’analyseur à la fois dans un fichier EditorConfig peuvent configurer Silent en bloc des règles de gravité. None Les règles de gravité ne peuvent pas être configurées de cette façon. Au lieu de cela, ils doivent être configurés par le biais d’entrées qui définissent la gravité dans un fichier EditorConfig pour chaque ID de règle.

Définir la gravité de la 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 a priorité sur toute gravité définie dans un ensemble de règles ou dans l'Explorateur de solutions. Vous pouvez configurer la gravité manuellement dans un fichier EditorConfig ou automatiquement via l’ampoule qui apparaît en regard d’une violation.

Configurer manuellement la gravité de la règle dans un fichier EditorConfig

Pour configurer la gravité de la règle, procédez comme suit :

Ajoutez un fichier EditorConfig à votre projet, si vous n’en avez pas déjà un.
Ajoutez une entrée pour chaque règle que vous souhaitez configurer sous l’extension de fichier correspondante.

Par exemple, l’entrée pour définir la gravité pour CA1822error pour les fichiers C# est la suivante :
```
[*.cs]
dotnet_diagnostic.CA1822.severity = error
```
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>
Pour les analyseurs de style de code IDE, vous pouvez également les configurer dans un fichier EditorConfig à l’aide d’une syntaxe différente.

Par exemple : dotnet_style_qualification_for_field = false:suggestion. Toutefois, si vous définissez une gravité à l’aide de la dotnet_diagnostic syntaxe, 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ègles d’analyseur ou pour toutes les règles d’analyseur avec une entrée unique dans un fichier EditorConfig :

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

dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity>
Définissez la gravité de la règle pour toutes les règles d’analyseur :

dotnet_analyzer_diagnostic.severity = <severity>

Les entrées qui configurent plusieurs règles d’analyseur à la fois s’appliquent uniquement 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 d’analyseur doivent être activées via des entrées explicites dotnet_diagnostic.<rule ID>.severity = <severity> .

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

Une entrée de gravité pour une règle individuelle par ID prend le pas sur une entrée de gravité pour une catégorie.
Une entrée de gravité pour une catégorie est prioritaire sur une entrée de gravité pour toutes les règles de l’analyseur.

Prenons l’exemple EditorConfig suivant, où CA1822 est une règle de performances :

[*.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 performances CA1822. Toutefois, à l’aide des règles de précédence spécifiées, la première entrée basée sur l'ID de règle pour la gravité est prioritaire sur les entrées subséquentes. Dans cet exemple, CA1822 a une gravité effective de 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.

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

Après qu'une violation a eu lieu, survolez la ligne de soulignement de violation dans l'éditeur et choisissez Afficher les correctifs potentiels pour ouvrir le menu ampoule. Ou placez votre curseur sur la ligne et appuyez sur Ctrl+. (point).
Dans le menu ampoule, pointez sur un niveau de gravité pour un aperçu de la modification, puis configurez la gravité en fonction des options suivantes :
- Configurez la sévérité de la règle ID. 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é de toutes les catégories de règles d’analyseur.
  
  Dans l'exemple suivant, sélectionnez Supprimer ou configurer les problèmes>Configurer la gravité de l'ID de règle<>.
Choisissez 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 indiqué dans la zone d’aperçu.

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

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

Pour définir la gravité des règles à partir de l’Explorateur de solutions, procédez comme suit :

Dans l'Explorateur de solutions, développez References>Analyseurs (ou Dépendances>Analyseurs pour les projets .NET Core).
Développez l'assemblage qui contient la règle pour laquelle vous souhaitez définir le niveau de gravité.
Cliquez avec le bouton droit sur la règle et 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 de jeu de règles au lieu d’un fichier EditorConfig, l’entrée de gravité est ajoutée au fichier de jeu de règles.

Si vous ne disposez pas déjà d’un fichier EditorConfig ou d’un fichier de jeu de règles dans le projet, Visual Studio crée un fichier EditorConfig pour vous.

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

Vous pouvez effectuer une grande partie de la personnalisation des diagnostics d’analyseur à partir de l’Explorateur de solutions. Si vous installez un analyseur en tant que package NuGet, un nœud Analyzers apparaît sous le nœud Références (ou 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 :

Dans l’Explorateur de solutions, développez votre projet, développez Références ou dépendances, puis développez Analyseurs. Dépliez l’un des assemblages d’analyseurs pour afficher les diagnostics dans l’assemblage.

L’icône en regard de chaque diagnostic indique son niveau de gravité :
- x dans un cercle indique une gravité d’erreur
- ! dans un triangle indique un niveau de gravité Avertissement
- i dans un cercle solide indique une gravité de la 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 None
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.
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, définissez la propriété true sur .
Pour obtenir une documentation en ligne pour un diagnostic, cliquez avec le bouton droit sur le diagnostic, puis sélectionnez Afficher l’aide.

Convertir un fichier de jeu de règles existant en fichier EditorConfig

Dans Visual Studio 2019 version 16.5 et suivantes, les fichiers de jeu de règles sont déconseillés au profit des fichiers EditorConfig pour configurer les analyseurs du code managé. Les fichiers EditorConfig sont plus flexibles et vous permettent de configurer à la fois les gravités des règles d’analyseur et les options d’analyseur, y compris les options de style de code 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 de jeu de règles, vous êtes encouragés à convertir tous les projets existants qui utilisent toujours des fichiers de jeu de règles.

Lorsque vous convertissez votre fichier de jeu 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 de jeu de règles existant en fichier EditorConfig à l’aide de l’éditeur du jeu de règles ou de la ligne de commande.

Remarque

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

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

Double-cliquez sur le fichier de jeu de règles dans l’Explorateur de solutions.

Le fichier de jeu de règles s’ouvre dans l’éditeur du jeu de règles avec une barre d’informations cliquable en haut.
Sélectionnez le lien de la barre d’informations pour migrer le fichier d’éditeur du jeu de règles.
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.

EditorConfig généré s’ouvre dans l’éditeur. En outre, la propriété CodeAnalysisRuleSet MSBuild est mise à jour dans le fichier projet afin qu’elle ne référence plus le fichier d’ensemble de règles d’origine.

Le fichier d’ensemble de règles d’origine peut être supprimé du projet.

Remarque

Dans un projet .NET Framework, le fichier d’ensemble de règles par défaut ne peut pas être migré ou supprimé du projet.

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

Installez le package NuGet Microsoft.CodeAnalysis.RulesetToEditorconfigConverter.
Exécutez RulesetToEditorconfigConverter.exe à partir du package installé, avec des chemins d’accès au fichier jeu de règles et le 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 de jeu 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 des fichiers sources dans un projet et signalent les violations qu’ils trouvent. Toutefois, ces violations ne sont pas utiles pour les fichiers générés par le système. Des exemples sont des fichiers de code générés, tels que des fichiers de code générés par le concepteur, des fichiers sources temporaires générés par le système de génération, etc. Pour ces types de fichiers, les utilisateurs ne peuvent pas modifier manuellement les fichiers et ne sont pas préoccupés par la résolution des violations.

Par conséquent, par défaut, le pilote de l’analyseur examine uniquement les fichiers portant certains noms, extensions de fichier ou en-têtes de fichier générés automatiquement en tant que fichiers de code générés. Par exemple, un nom de fichier se terminant par .designer.cs ou .generated.cs est considéré comme du code généré. Toutefois, ces heuristiques peuvent ne pas être en mesure d’identifier tous les fichiers de code générés personnalisés 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 dossiers spécifiques à traiter comme du code généré dans un fichier EditorConfig.

Pour ajouter une telle configuration, procédez comme suit :

Si vous n’avez pas encore de fichier EditorConfig pour votre projet, ajoutez-en un.
Ajoutez l’entrée generated_code = true | false pour des fichiers et dossiers spécifiques. Par exemple, pour traiter tous les fichiers dont le nom se termine par .MyGenerated.cs le code généré, utilisez cette entrée :
```
[*.MyGenerated.cs]
generated_code = true
```

Supprimer les violations

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

Utilisation de la ligne de commande

Lorsque vous générez votre projet sur la ligne de commande, les violations de règle apparaissent 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 en tant que package NuGet, et non en tant qu’extension .vsix .

Pour les analyseurs installés à l’aide du Kit de développement logiciel (SDK) .NET, vous devrez peut-être activer les analyseurs. Pour les styles de code, vous pouvez également appliquer des styles de code sur des builds en définissant une propriété MSBuild.
Une ou plusieurs règles sont violées dans le code du projet.
Le niveau de gravité d’une règle violée est défini sur avertissement, auquel cas les violations n’entraînent pas l’échec de la construction, ou sur erreur, auquel cas les violations provoquent l’échec de la construction.

Le détail du résultat de la compilation n'affecte pas la présentation des violations de règle. Même avec un niveau de verbosité réduit, les violations de règles apparaissent dans le résultat de la compilation.

Si vous êtes habitué à exécuter l’analyse héritée à partir de la ligne de commande, soit avec FxCopCmd.exe, soit avec msbuild avec le drapeau RunCodeAnalysis, vous pouvez le faire en utilisant des analyseurs de code.

Pour afficher les violations de l’analyseur sur la ligne de commande lorsque 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 build en ligne de commande d’un projet qui contient une violation d'une règle d'analyse :

Capture d’écran montrant la sortie MSBuild avec une violation de règle dans une Invite de commandes pour développeur.

Projets dépendants

Dans un projet .NET Core, si vous ajoutez une référence à un projet doté d’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" />

Rétroaction

Cette page a-t-elle été utile ?

Last updated on 2025-12-12