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.

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.

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.

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.

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.

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 (-nowarn ou -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.

Voir aussi

• EditorConfig vs problème de conception d’AnalyzerConfig global