Options de configuration pour l’analyse du code

  • Article

Les règles d’analyse du code ont différentes options de configuration. Certaines de ces options sont spécifiées sous forme de paires clé-valeur dans un fichier de configuration d’analyseur à l’aide de la syntaxe <option key> = <option value>. D’autres options, qui configurent l’analyse du code dans son ensemble, sont disponibles en tant que propriétés MSBuild dans votre fichier projet.

L’option la plus courante que vous allez configurer est la gravité d’une règle. Vous pouvez configurer le niveau de gravité de n’importe quelle règle, notamment les règles de qualité du code et les règles de style du code. Par exemple, pour activer une règle en tant qu’avertissement, ajoutez la paire clé-valeur suivante à un fichier de configuration d’analyseur :

dotnet_diagnostic.<rule ID>.severity = warning

Vous pouvez également configurer des options supplémentaires pour personnaliser le comportement d’une règle :

  • Les règles de qualité du code comportent des options de comportement, telles que les noms de méthode auxquels une règle doit s’appliquer.
  • Les règles de style de code comportent des options de préférence de style, telles que l’emplacement où de nouvelles lignes sont souhaitables.
  • Les règles d’analyseur tiers peuvent définir leurs propres options de configuration, avec des noms de clés et des formats de valeur personnalisés.

Options générales

Ces options s’appliquent à l’analyse du code dans son ensemble. Elles ne peuvent pas être appliquées uniquement à une règle spécifique.

Pour obtenir des options supplémentaires, consultez Propriétés de l’analyse du code.

Mode d’analyse

Même si le kit de développement logiciel (SDK) .NET inclut toutes les règles d’analyse du code, seules certaines d’entre elles sont activées par défaut. Le mode d’analyse détermine l’ensemble de règles à activer, le cas échéant. Vous pouvez choisir un mode d’analyse plus agressif où la plupart ou toutes les règles sont activées. Vous pouvez également choisir un mode d’analyse plus conservateur où la plupart ou la totalité des règles sont désactivées, puis vous pouvez opter pour des règles spécifiques en fonction de vos besoins. Définissez votre mode d’analyse en ajoutant la propriété MSBuild <AnalysisMode> à votre fichier projet.

<PropertyGroup>
  <AnalysisMode>Recommended</AnalysisMode>
</PropertyGroup>

À compter de .NET 6, vous pouvez également activer en bloc une catégorie de règles à l’aide de la propriété MSBuild <AnalysisMode<Catégorie>>.

Remarque

Si vous configurez l’analyse du code à l’aide de propriétés MSBuild comme AnalysisMode, toutes les options de configuration en bloc que vous définissez dans votre fichier de configuration sont ignorées. Par exemple, si vous avez activé en bloc toutes les règles ou une catégorie de règles dans un fichier .editorconfig, cette configuration est ignorée.

Activer l’analyse du code

L’analyse du code est activée par défaut pour les projets qui ciblent .NET 5 et des versions ultérieures. Si vous disposez du SDK .NET 5+ mais que votre projet cible une implémentation de .NET différente, vous pouvez activer manuellement l’analyse du code en définissant la propriété EnableNETAnalyzers sur true dans votre fichier projet.

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

Exclure le code généré

Les avertissements de l’analyseur de code .NET ne sont pas utiles sur les fichiers de code générés, tels que les fichiers générés par le concepteur, que les utilisateurs ne peuvent pas modifier pour corriger les éventuelles violations. Dans la plupart des cas, les analyseurs de code ignorent les fichiers de code générés et ne signalent pas les violations que comportent ces fichiers.

Par défaut, les fichiers ayant certaines extensions de fichier ou des en-têtes de fichier générés automatiquement sont traités comme des fichiers de code générés. Par exemple, un fichier dont le nom se termine par .designer.cs ou .generated.cs est considéré comme du code généré. Cette option de configuration vous permet de spécifier des modèles de nommage supplémentaires à traiter comme du code généré. Vous configurez des fichiers et dossiers supplémentaires en ajoutant une entrée generated_code = true | false à votre fichier de configuration. Par exemple, pour traiter tous les fichiers dont le nom se termine par .MyGenerated.cs comme du code généré, ajoutez l’entrée suivante :

[*.MyGenerated.cs]
generated_code = true

Options spécifiques à une règle

Des options spécifiques à une règle peuvent être appliquées à une seule règle, à un ensemble de règles ou à toutes les règles. Les options spécifiques à une règle sont les suivantes :

Niveau de gravité

Le tableau suivant présente les différentes gravités de règle que vous pouvez configurer pour toutes les règles d’analyseur, notamment les règles de qualité du code et de style du code.

Valeur de configuration de la gravité Comportement lors de la création
error Les violations apparaissent sous forme d’erreurs de build et entraînent l’échec des builds.
warning Les violations apparaissent sous forme d’avertissements de build, mais ne provoquent pas l’échec des builds (sauf si une option est définie pour traiter les avertissements comme des erreurs).
suggestion Les violations apparaissent sous forme de messages de build et de suggestions dans l’environnement IDE Visual Studio. (Dans Visual Studio, les suggestions s’affichent sous la forme de trois points gris sous les deux premiers caractères.)
silent Les violations ne sont pas visibles par l’utilisateur.

Toutefois, pour des règles de style de code, les fonctionnalités de génération de code Visual Studio génèrent encore du code dans ce style. Ces règles participent également au nettoyage et apparaissent dans le menu Actions rapides et refactorisations dans Visual Studio.
none La règle est entièrement supprimée.

Toutefois, pour des règles de style de code, les fonctionnalités de génération de code Visual Studio génèrent encore du code dans ce style.
default La gravité par défaut de la règle est utilisée. Les gravités par défaut pour chaque version de .NET sont listées dans le dépôt roslyn-analyzers. Dans ce tableau, « Disabled » (Désactivé) correspond à none, « Hidden » (Masqué) correspond à silent et « Info » (Informations) correspond à suggestion.

Étendue

  • Règle unique

    Pour définir la gravité d’une seule règle, utilisez la syntaxe suivante.

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

  • Catégorie de règles

    Pour définir la gravité de règle par défaut pour une catégorie de règles, utilisez la syntaxe suivante. Toutefois, ce paramètre de gravité affecte uniquement les règles de cette catégorie qui sont activées par défaut.

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

    Les différentes catégories sont listées et décrites dans Catégories de règles. Vous pouvez également trouver la catégorie d’une règle spécifique dans sa page de référence, par exemple CA1000.

  • Toutes les règles

    Pour définir la gravité de règle par défaut pour toutes les règles d’analyseur, utilisez la syntaxe suivante. Toutefois, ce paramètre de gravité affecte uniquement les règles qui sont activées par défaut.

    dotnet_analyzer_diagnostic.severity = <severity value>

Important

Lorsque vous configurez le niveau de gravité pour plusieurs règles avec une seule entrée, soit pour une catégorie de règles, soit pour toutes les règles, la gravité s’applique uniquement aux règles qui sont activées par défaut. Et si vous activez toutes les règles à l’aide des propriétés MSBuild <AnalysisMode> ou <AnalysisLevel>, toutes les options en bloc dotnet_analyzer_diagnostic sont ignorées. Pour cette raison, il est préférable d’activer une catégorie de règles en définissant <AnalysisMode<Catégorie>> sur All.

Remarque

Le préfixe permettant de définir la gravité d’une règle unique, dotnet_diagnostic, est légèrement différent du préfixe permettant de configurer la gravité via la catégorie ou pour toutes les règles, dotnet_analyzer_diagnostic.

Priorité

Si vous avez plusieurs entrées de configuration de la gravité qui peuvent être appliquées au même ID de règle, la priorité est choisie dans l’ordre suivant :

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

Prenons l’exemple suivant, où CA1822 correspond à la catégorie « Performance » :

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

Dans l’exemple précédent, les trois entrées de gravité s’appliquent à CA1822. Toutefois, en raison des règles de priorité spécifiées, la première entrée basée sur l’ID de règle l’emporte sur les entrées suivantes. Dans cet exemple, la gravité réelle de CA1822 sera error. Toutes les autres règles de la catégorie « Performance » auront le niveau de gravité warning.

Pour plus d’informations sur la façon dont la priorité inter-fichiers est déterminée, consultez la section Priorité de l’article Fichiers de configuration.