Fichiers de configuration pour les règles d’analyse du code

  • Article

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 l’activation ou de la désactivation complète à la configuration 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

À partir du kit de développement logiciel (SDK) .NET 5 (pris en charge dans Visual Studio 2019 et les versions ultérieures), vous pouvez également configurer des options de l’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’avoir un nom ou une extension spécifique. Toutefois, si vous nommez ces fichiers comme .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.

Notes

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 des fins de clarté.

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 (-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