Fichiers de configuration pour les règles d’analyse du code
Les règles d’analyse du code ont différentes options de configuration. Vous spécifiez ces options sous forme de paires clé-valeur dans l’un des fichiers de configuration de l’analyseur suivants :
- Fichier EditorConfig : options de configuration basées sur des fichiers ou des dossiers.
- Fichier Global AnalyzerConfig : options de configuration au niveau du projet. Utile lorsque certains fichiers projet se trouvent en dehors du dossier du projet.
Conseil
Vous pouvez également définir les propriétés de configuration de l’analyse du code dans votre fichier projet. Ces propriétés configurent l’analyse du code au niveau du bloc, de son activation ou sa désactivation complète jusqu’à la configuration de règle au niveau de la catégorie. Pour plus d’informations, consultez EnableNETAnalyzers, AnalysisLevel, AnalysisLevel<Category> et AnalysisMode.
EditorConfig
Les fichiers EditorConfig sont utilisés pour fournir des options qui s’appliquent à des fichiers ou dossiers sources spécifiques. Les options sont placées sous les en-têtes de section pour identifier les fichiers et dossiers applicables. Ajoutez une entrée pour chaque règle que vous souhaitez configurer et placez-la sous la section d’extension de fichier correspondante, par exemple [*.cs].
[*.cs]
<option_name> = <option_value>
Dans l’exemple ci-dessus, [*.cs] est un en-tête de section editorconfig permettant de sélectionner tous les fichiers C# avec l’extension de fichier .cs dans le dossier actif, y compris les sous-dossiers. L’entrée suivante, <option_name> = <option_value>, est une option d’analyseur qui sera appliquée à tous les fichiers C#.
Vous pouvez appliquer des conventions de fichier EditorConfig à un dossier, à un projet ou à un référentiel entier en plaçant le fichier dans le répertoire correspondant. Ces options sont appliquées lors de l’exécution de l’analyse au moment de la génération et pendant que vous modifiez du code dans Visual Studio.
Notes
Les options EditorConfig s’appliquent uniquement aux fichiers sources d’un projet ou d’un répertoire. Les fichiers inclus dans un projet en tant que AdditionalFiles ne sont pas considérés comme des fichiers sources et les options EditorConfig ne sont pas appliquées à ces fichiers. Pour appliquer une option de règle aux fichiers non sources, spécifiez l’option dans un fichier de configuration globale.
Si vous disposez d’un fichier .editorconfig existant pour les paramètres de l’éditeur tels que la taille du retrait ou si vous souhaitez réduire l’espace de fin, vous pouvez placer vos options de configuration d’analyse du code dans le même fichier.
Conseil
Visual Studio fournit un modèle d’élément .editorconfig qui facilite l’ajout d’un de ces fichiers à votre projet. Pour plus d’informations, consultez Ajouter un fichier EditorConfig à un projet.
Exemple
Voici un exemple de fichier EditorConfig pour configurer les options et la gravité des règles :
# Remove the line below if you want to inherit .editorconfig settings from higher directories
root = true
# C# files
[*.cs]
#### Core EditorConfig Options ####
# Indentation and spacing
indent_size = 4
indent_style = space
tab_width = 4
#### .NET Coding Conventions ####
# this. and Me. preferences
dotnet_style_qualification_for_method = true
#### Diagnostic configuration ####
# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning
Global AnalyzerConfig
Vous pouvez également configurer des options d’analyseur avec des fichiers AnalyzerConfig globaux. Ces fichiers sont utilisés pour fournir des options qui s’appliquent à tous les fichiers sources d’un projet, quels que soient leurs noms de fichiers ou leurs chemins d’accès.
Contrairement aux fichiers EditorConfig, les fichiers de configuration globale ne peuvent pas être utilisés pour configurer les paramètres de style de l’éditeur pour les IDE, tels que la taille du retrait ou la suppression de l’espace de fin. Au lieu de cela, ils sont conçus uniquement pour spécifier les options de configuration de l’analyseur au niveau du projet.
Format
Contrairement aux fichiers EditorConfig, qui doivent avoir des en-têtes de section, tels que [*.cs], pour identifier les fichiers et dossiers applicables, les fichiers AnalyzerConfig globaux n’ont pas d’en-têtes de section. Au lieu de cela, ils ont besoin d’une entrée de niveau supérieur du formulaire is_global = true pour les différencier des fichiers standard EditorConfig. Cela indique que toutes les options du fichier s’appliquent à l’ensemble du projet. Par exemple :
is_global = true
<option_name> = <option_value>
Dénomination
Contrairement aux fichiers EditorConfig, qui doivent être nommés .editorconfig, les fichiers de configuration globaux n’ont pas besoin d’un nom ou d’une extension spécifique. Toutefois, si vous nommez ces fichiers .globalconfig, ils sont appliqués implicitement à tous les projets C# et Visual Basic dans le dossier actif, y compris les sous-dossiers. Sinon, vous devez ajouter explicitement l’élément GlobalAnalyzerConfigFiles à votre fichier projet MSBuild :
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="<path_to_global_analyzer_config>" />
</ItemGroup>
Tenez compte des recommandations de dénomination suivantes :
- Les utilisateurs finaux doivent nommer leurs fichiers de configuration globale .globalconfig.
- Les créateurs de packages NuGet doivent nommer leurs fichiers de configuration globaux <%Package_Name%>.globalconfig.
- Les fichiers de configuration globaux générés par les outils MSBuild doivent être nommés <%Target_Name%>_Generated.globalconfig ou similaires.
Remarque
L’entrée is_global = true de niveau supérieur n’est pas obligatoire lorsque le fichier est nommé .globalconfig, mais elle est recommandée pour davantage de clarté.
Inclusion conditionnelle
Vous pouvez utiliser un fichier de configuration global pour désactiver ou activer certaines règles d’analyse du code dans différents environnements. Par exemple, vous pouvez désactiver certaines règles d’analyse du code pour les projets de test unitaire. Pour ce faire, vous pouvez définir la gravité des règles applicables à none dans le fichier de configuration, par exemple :
# CA1861: Prefer 'static readonly' fields over constant array arguments
dotnet_diagnostic.CA1861.severity = none
Vous pouvez ensuite personnaliser votre build pour n’inclure que le fichier de configuration dans les projets de test en fonction des conditions spécifiques à votre build. Par exemple :
<ItemGroup Condition="'$(IsShipping)' == 'false'">
<!-- Include CodeAnalysis.test.globalconfig to override (relax) some rules from the primary configuration. -->
<GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.test.globalconfig" />
</ItemGroup>
Distribution dans les packages NuGet
Les fichiers Global AnalyzerConfig peuvent être distribués avec des packages NuGet. Pour ce faire, ajoutez un fichier .props au package NuGet. Dans le fichier .props, ajoutez un élément GlobalAnalyzerConfigFiles sous le nœud Project :
<Project>
<ItemGroup>
<GlobalAnalyzerConfigFiles Include="Relative/Path/to/PackageName.globalconfig" />
</ItemGroup>
</Project>
Exemple
Voici un exemple de fichier AnalyzerConfig global pour configurer les options et la gravité des règles au niveau du projet :
# Top level entry required to mark this as a global AnalyzerConfig file
is_global = true
# NOTE: No section headers for configuration entries
#### .NET Coding Conventions ####
# this. and Me. preferences
dotnet_style_qualification_for_method = true:warning
#### Diagnostic configuration ####
# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning
Priorité
Les fichiers EditorConfig et les fichiers AnalyzerConfig globaux spécifient une paire clé-valeur pour chaque option. Des conflits surviennent lorsqu’il existe plusieurs entrées avec la même clé, mais des valeurs différentes. Les règles de priorité suivantes sont utilisées pour résoudre les conflits.
| Emplacements d’entrée en conflit | Règles de priorité |
|---|---|
| Dans le même fichier de configuration | L’entrée qui apparaît plus tard dans le fichier gagne. Cela s’applique aux entrées en conflit au sein d’un fichier EditorConfig unique et d’un seul fichier AnalyzerConfig global. |
| Dans deux fichiers EditorConfig | L’entrée dans le fichier EditorConfig qui est plus profonde dans le système de fichiers et qui a donc un chemin de fichier plus long, gagne. |
| Dans deux fichiers AnalyzerConfig globaux | .NET 5 : un avertissement du compilateur est signalé et les deux entrées sont ignorées. .NET 6 et versions ultérieures : l’entrée du fichier avec une valeur supérieure pour global_level est prioritaire. Si global_level n’est pas défini explicitement et que le fichier est nommé .globalconfig, la valeur global_level par défaut est 100 ; pour tous les autres fichiers AnalyzerConfig globaux, la valeur global_level par défaut est 0. Si les valeurs global_level des fichiers de configuration avec des entrées en conflit sont égales, un avertissement du compilateur est signalé et les deux entrées sont ignorées. |
| Dans un fichier EditorConfig et un fichier Global AnalyzerConfig | L’entrée dans le fichier EditorConfig gagne. |
Options de gravité
Pour les options de configuration de gravité, les règles de priorité supplémentaires suivantes s’appliquent :
Les options de gravité spécifiées sur la ligne de commande en tant qu’options du compilateur (
-nowarnou-warnaserror) remplacent toujours les options de configuration de gravité spécifiées dans EditorConfig et les fichiers AnalyzerConfig globaux.Les règles de priorité pour les entrées de gravité en conflit à partir d’un fichier d’ensemble de règles et d’un fichier EditorConfig ou d’un fichier AnalyzerConfig global ne sont pas définies.
Les fichiers d’ensemble de règles sont déconseillés en faveur des fichiers EditorConfig et des fichiers AnalyzerConfig globaux. Nous vous recommandons de convertir les fichiers d’ensemble de règles en fichier EditorConfig équivalent.
Pour plus d’informations sur les règles de priorité pour les options de gravité associées avec différentes clés, par exemple, lorsque des gravités différentes sont spécifiées pour une seule règle et pour la catégorie sous laquelle cette règle se trouve, consultez Options de configuration pour l’analyse du code.
