Vue d’ensemble de l’analyse du code source .NET

  • Article

Les analyseurs .NET Compiler Platform (Roslyn) inspectent la qualité et les problèmes de styles de votre code C# ou Visual Basic. À compter de .NET 5, ces analyseurs sont inclus dans le Kit de développement logiciel (SDK) .NET et vous n’avez pas besoin de les installer séparément. Si votre projet cible .NET 5 ou version ultérieure, l’analyse du code est activée par défaut. Si votre projet cible une autre implémentation .NET, par exemple .NET Core, .NET Standard ou .NET Framework, vous devez activer manuellement l’analyse du code en définissant la propriété EnableNETAnalyzers sur true.

Si vous ne souhaitez pas passer au Kit de développement logiciel (SDK) .NET 5+, disposez d’un projet .NET Framework de style non SDK ou préférez un modèle basé sur un package NuGet, les analyseurs sont également disponibles dans le package NuGet Microsoft.CodeAnalyzers. Vous préférerez peut-être un modèle basé sur un package pour les mises à jour de version à la demande.

Notes

Les analyseurs .NET sont indépendants du framework cible. Autrement dit, votre projet n’a pas besoin de cibler une implémentation .NET spécifique. Les analyseurs fonctionnent pour les projets qui ciblent .NET 5+ ainsi que les versions antérieures de .NET, telles que .NET Core 3.1 et .NET Framework 4.7.2. Toutefois, pour activer l’analyse du code à l’aide de la propriété EnableNETAnalyzers, votre projet doit référencer un SDK de projet.

Si des violations de règle sont détectées par un analyseur, elles sont signalées comme une suggestion, un avertissement ou une erreur, selon la façon dont chaque règle est configurée. Les violations d’analyse du code apparaissent avec le préfixe « CA » ou « IDE » pour les différencier des erreurs du compilateur.

Analyse de la qualité du code

Les règles d’analyse de la qualité du code (« CAxxxx ») inspectent votre code C# ou Visual Basic pour la sécurité, les performances, la conception et d’autres problèmes. L’analyse est activée par défaut pour les projets ciblant .NET 5 ou ultérieur. Vous pouvez activer l’analyse du code sur les projets ciblant des versions antérieures de .NET en affectant à la propriété EnableNETAnalyzers la valeur true. Vous pouvez aussi désactiver l’analyse du code pour votre projet en affectant à EnableNETAnalyzers la valeur false.

Conseil

Si vous utilisez Visual Studio, de nombreuses règles d’analyseur ont des correctifs de code associés que vous pouvez appliquer pour corriger le problème. Les correctifs de code sont affichés dans le menu d’icône de l’ampoule.

Règles activées

Les règles suivantes sont activées par défaut en tant qu’erreurs ou avertissements dans .NET 8. Des règles supplémentaires sont activées sous forme de suggestions.

ID de diagnostic Category Niveau de gravité Version ajoutée Description
CA1416 Interopérabilité Avertissement .NET 5 Valider la compatibilité de la plateforme
CA1417 Interopérabilité Avertissement .NET 5 Ne pas utiliser OutAttribute sur les paramètres de chaîne pour les P/Invokes
CA1418 Interopérabilité Avertissement .NET 6 Utiliser une chaîne de plateforme valide
CA1420 Interopérabilité Avertissement .NET 7 L’utilisation de fonctionnalités qui nécessitent le marshaling du runtime lorsqu’il est désactivé entraîne des exceptions d’exécution
CA1422 Interopérabilité Avertissement .NET 7 Valider la compatibilité de la plateforme
CA1831 Performances Avertissement .NET 5 Utiliser AsSpan à la place d’indexeurs basés sur Range pour une chaîne si approprié
CA1856 Performances Erreur .NET 8 Utilisation incorrecte de l’attribut ConstantExpected
CA1857 Performances Avertissement .NET 8 Une constante est attendue pour le paramètre
CA2013 Fiabilité Avertissement .NET 5 Ne pas utiliser ReferenceEquals avec les types de valeur
CA2014 Fiabilité Avertissement .NET 5 Ne pas utiliser stackalloc dans des boucles
CA2015 Fiabilité Avertissement .NET 5 Ne pas définir de finaliseurs pour les types dérivés de MemoryManager<T>
CA2017 Fiabilité Avertissement .NET 6 Nombre de paramètres incorrects
CA2018 Fiabilité Avertissement .NET 6 L’argument count vers Buffer.BlockCopy doit spécifier le nombre d’octets à copier
CA2021 Fiabilité Avertissement .NET 8 N’appelez pas Enumerable.Cast<T> ou Enumerable.OfType<T> avec des types incompatibles
CA2200 Utilisation Avertissement .NET 5 Levez à nouveau une exception pour conserver les détails de la pile
CA2247 Utilisation Avertissement .NET 5 L’argument transféré au constructeur TaskCompletionSource doit être enum TaskCreationOptions au lieu de TaskContinuationOptions
CA2252 Utilisation Erreur .NET 6 Choisir d’afficher un aperçu des fonctionnalités
CA2255 Utilisation Avertissement .NET 6 L’attribut ModuleInitializer ne doit pas être utilisé dans les bibliothèques
CA2256 Utilisation Avertissement .NET 6 Tous les membres déclarés dans les interfaces parentes doivent avoir une implémentation dans une interface attribuée par DynamicInterfaceCastableImplementation
CA2257 Utilisation Avertissement .NET 6 Les membres définis sur une interface avec DynamicInterfaceCastableImplementationAttribute doivent être static
CA2258 Utilisation Avertissement .NET 6 La fourniture d’une interface DynamicInterfaceCastableImplementation dans Visual Basic n’est pas prise en charge
CA2259 Utilisation Avertissement .NET 7 ThreadStatic affecte uniquement les champs statiques
CA2260 Utilisation Avertissement .NET 7 Utiliser un paramètre de type correct
CA2261 Utilisation Avertissement .NET 8 Ne pas utiliser ConfigureAwaitOptions.SuppressThrowing avec Task<TResult>

Vous pouvez modifier la gravité de ces règles pour les désactiver ou les élever au niveau d’erreur. Vous pouvez également activer d’autres règles.

  • Pour obtenir la liste des règles incluses dans chaque version du Kit de développement logiciel (SDK) .NET, consultez lesversions de l’analyseur.
  • Pour obtenir la liste de toutes les règles de qualité du code, consultez les Règles de qualité du code.

Activer des règles supplémentaires

Le mode d’analyse fait référence à une configuration d’analyse de code prédéfinie, où aucune, certaines ou toutes les règles sont activées. Dans le mode d’analyse par défaut (Default), seul un petit nombre de règles sont activées en tant qu’avertissements de build. Vous pouvez modifier le mode d’analyse de votre projet en définissant la propriété <AnalysisMode> dans le fichier projet. Les valeurs autorisées sont les suivantes :

Valeur Description
None Toutes les règles sont désactivées. Vous pouvez accepter de manière sélective des règles individuelles pour les activer.
Default Mode par défaut, dans lequel certaines règles sont activées en tant qu’avertissements de build, certaines règles sont activées en tant que suggestions d’IDE Visual Studio, et les autres sont désactivées.
Minimum Mode plus agressif que le mode Default. Certaines suggestions fortement recommandées pour l’application de build sont activées en tant qu’avertissements de build. Pour voir quelles règles cela inclut, inspectez le fichier %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig.
Recommended Mode plus agressif que le mode Minimum, dans lequel plus de règles sont activées en tant qu’avertissements de build. Pour voir quelles règles cela inclut, inspectez le fichier %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig.
All Toutes les règles sont activées en tant qu’avertissements de build *. Vous pouvez refuser de manière sélective des règles individuelles pour les désactiver.

* Les règles suivantes ne sont pas activées en définissant AnalysisMode sur All ou en définissant AnalysisLevel sur latest-all : CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 et les règles de l’analyseur de métriques de code (CA1501, CA1502, CA1505, CA1506 et CA1509). Ces règles héritées pourraient être dépréciées dans une version ultérieure. Toutefois, vous pouvez toujours les activer individuellement à l’aide d’une entrée dotnet_diagnostic.CAxxxx.severity = <severity>.

À compter de .NET 6, vous pouvez omettre <AnalysisMode> en faveur d’une valeur composée pour la propriété <AnalysisLevel>. Par exemple, la valeur suivante active l’ensemble de règles recommandé pour la dernière version : <AnalysisLevel>latest-Recommended</AnalysisLevel>. Pour plus d’informations, consultez AnalysisLevel.

Pour rechercher la gravité par défaut de chaque règle disponible et si la règle est activée ou non dans le mode d’analyse de Default, consultez la liste complète des règles.

Considérer les avertissements comme des erreurs

Si vous utilisez l’indicateur -warnaserror lorsque vous générez vos projets, tous les avertissements d’analyse du code sont également traités comme des erreurs. Si vous ne souhaitez pas que les avertissements de qualité du code (CAxxxx) soient traités comme des erreurs en présence de -warnaserror, vous pouvez définir la propriété CodeAnalysisTreatWarningsAsErrors MSBuild sur false dans votre fichier projet.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

Vous verrez toujours des avertissements d’analyse du code, mais ils n’interrompront pas votre build.

Dernières mises à jour

Par défaut, vous obtenez les dernières règles d’analyse du code et les gravités des règles par défaut lorsque vous effectuez une mise à niveau vers des versions plus récentes du Kit de développement logiciel (SDK) .NET. Si vous ne souhaitez pas ce comportement, par exemple, si vous souhaitez vous assurer qu’aucune nouvelle règle n’est activée ou désactivée, vous pouvez la remplacer de l’une des manières suivantes :

  • Définissez la propriété MSBuild AnalysisLevel sur une valeur spécifique pour verrouiller les avertissements sur ce jeu. Lorsque vous effectuez une mise à niveau vers un SDK plus récent, vous obtenez toujours des correctifs de bogues pour ces avertissements, mais aucun nouvel avertissement n’est activé et aucun avertissement existant n’est désactivé. Par exemple, pour verrouiller l’ensemble de règles sur celles fournies avec la version 5.0 du KIT de développement logiciel (SDK) .NET, ajoutez l’entrée suivante à votre fichier projet.

    <PropertyGroup>
  <AnalysisLevel>5.0</AnalysisLevel>
</PropertyGroup>

    Conseil

    La valeur par défaut de la propriété AnalysisLevel est latest, ce qui signifie que vous obtenez toujours les dernières règles d’analyse du code lorsque vous passez à des versions plus récentes du Kit de développement logiciel (SDK) .NET.

    Pour plus d’informations et pour afficher la liste des valeurs possibles, consultez AnalysisLevel.

  • Installez le package Microsoft.CodeAnalysis.NetAnalyzers NuGet pour dissocier les mises à jour des règles à partir des mises à jour du Kit de développement logiciel (SDK) .NET. Pour les projets qui ciblent .NET 5+, l’installation du package désactive les analyseurs intégrés du SDK. Vous recevez un avertissement de build si le SDK contient une version d’assembly d’analyseur plus récente que celle du package NuGet. Pour désactiver l’avertissement, définissez la propriété _SkipUpgradeNetAnalyzersNuGetWarning sur true.

    Notes

    Si vous installez le package Microsoft.CodeAnalysis.NetAnalyzers NuGet, vous ne devez pas ajouter la propriété EnableNETAnalyzers à votre fichier projet ou à un fichier Directory.Build.props. Lorsque le package NuGet est installé et que la propriété EnableNETAnalyzers est définie sur true, un avertissement de build est généré.

Analyse de style de code

Les règles d’analyse de style de code (« IDExxxx ») vous permettent de définir et de maintenir un style de code cohérent dans votre codebase. Les paramètres d’activation par défaut sont les suivants :

  • Build de ligne de commande : l’analyse du style de code est désactivée, par défaut, pour tous les projets .NET sur les builds en ligne de commande.

    À compter de .NET 5, vous pouvez activer l’analyse de style de code sur le build, à la fois sur la ligne de commande et dans Visual Studio. Les violations de style de code apparaissent sous forme d’avertissements ou d’erreurs avec un préfixe « IDE ». Cela vous permet d’appliquer des styles de code cohérents au moment de la génération.

  • Visual Studio : l’analyse de style de code est activée, par défaut, pour tous les projets .NET à l’intérieur de Visual Studio en tant qu’actions rapides de refactorisation du code.

Pour obtenir la liste complète des règles d’analyse de style de code, consultez Règles de style de code.

Activer sur le build

Avec le Kit de développement logiciel (SDK) .NET 5 et les versions ultérieures, vous pouvez activer l’analyse du style du code lors de la génération à partir de la ligne de commande et dans Visual Studio. (Toutefois, pour des raisons de performances, une poignée de règles de style code s’applique toujours uniquement dans l’IDE Visual Studio.)

Suivez ces étapes pour activer l’analyse de style de code sur le build :

  1. Définissez la propriété MSBuild EnforceCodeStyleInBuild sur true.

  2. Dans un fichier .editorconfig, configurez chaque règle de style de code « IDE » que vous souhaitez exécuter sur build en tant qu’avertissement ou erreur. Par exemple :

    [*.{cs,vb}]
# IDE0040: Accessibility modifiers required (escalated to a build warning)
dotnet_diagnostic.IDE0040.severity = warning

    Conseil

    À compter de .NET 9, vous pouvez également utiliser le format d’option pour spécifier une gravité et faire en sorte qu’elle soit respectée au moment de la build. Par exemple :

    [*.{cs,vb}]
# IDE0040: Accessibility modifiers required (escalated to a build warning)
dotnet_style_require_accessibility_modifiers = always:warning

    Vous pouvez également configurer une catégorie entière pour qu’elle soit un avertissement ou une erreur, par défaut, puis désactiver sélectivement les règles de cette catégorie que vous ne souhaitez pas exécuter sur le build. Par exemple :

    [*.{cs,vb}]

# Default severity for analyzer diagnostics with category 'Style' (escalated to build warnings)
dotnet_analyzer_diagnostic.category-Style.severity = warning

# IDE0040: Accessibility modifiers required (disabled on build)
dotnet_diagnostic.IDE0040.severity = silent

Supprimer un avertissement

Une façon de supprimer une violation de règle consiste à définir l’option de gravité de cet ID de règle sur none dans un fichier EditorConfig. Par exemple :

dotnet_diagnostic.CA1822.severity = none

Pour plus d’informations et d’autres façons de supprimer les avertissements, consultez Comment supprimer les avertissements d’analyse du code.

Exécuter l’analyse du code en tant que GitHub Action

La GitHub Action dotnet/code-analysis vous permet d’exécuter des analyseurs de code .NET dans le cadre de l’intégration continue (CI) en mode hors connexion. Pour plus d’informations, consultez GitHub Action Analyse du code .NET.

Analyseurs tiers

Outre les analyseurs .NET officiels, vous pouvez également installer des analyseurs tiers, tels que StyleCop, Roslynator, XUnit Analyzers et Sonar Analyzer.

Voir aussi