Options du compilateur C# pour signaler des erreurs et des avertissements

Article
08/30/2024

Les options suivantes contrôlent la façon dont le compilateur signale des erreurs et des avertissements. La nouvelle syntaxe MSBuild est affichée en gras. La syntaxe csc.exe plus ancienne est indiquée dans code style.

WarningLevel / -warn: définir le niveau d’avertissement.
AnalysisLevel: définir le niveau d’avertissement facultatif.
TreatWarningsAsErrors / -warnaserror: traiter tous les avertissements comme des erreurs
WarningsAsErrors / -warnaserror: traiter un ou plusieurs avertissements comme des erreurs
WarningsNotAsErrors / -warnnotaserror: na pas traiter un ou plusieurs avertissements comme des erreurs
NoWarn / -nowarn: définir une liste d’avertissements désactivés.
CodeAnalysisRuleSet / -ruleset: spécifiez un fichier d’ensemble de règles qui désactive des diagnostics spécifiques.
ErrorLog / -errorlog: spécifiez un fichier pour enregistrer tous les diagnostics du compilateur et de l’analyseur.
ReportAnalyzer / -reportanalyzer: signalez des informations supplémentaires sur l’analyseur, telles que le temps d’exécution.

Remarque

Reportez-vous à la section Options du compilateur pour plus d'informations sur la configuration de ces options pour votre projet.

WarningLevel

L’option WarningLevel spécifie le niveau d’avertissement pour que le compilateur s’affiche.

<WarningLevel>3</WarningLevel>

La valeur de l’élément est le niveau d’avertissement que vous souhaitez afficher pour la compilation : les nombres inférieurs n’affichent que les avertissements de gravité élevée. Les nombres plus élevés affichent plus d’avertissements. La valeur doit être égale à zéro ou à un entier positif :

Niveau d’avertissement	Signification
0	Désactive l’émission de tous les messages d’avertissement.
1	Affiche les messages d’avertissement graves.
2	Affiche les avertissements de niveau 1, ainsi que certains avertissements moins graves, tels que les avertissements concernant le masquage de membres de classe.
3	Affiche les avertissements de niveau 2, ainsi que certains avertissements moins graves, tels que les avertissements concernant les expressions toujours évaluées à `true` ou `false`.
4 (défaut)	Affiche les avertissements de niveau 3, ainsi que les avertissements d’information.

Avertissement

La ligne de commande du compilateur accepte les valeurs supérieures à 4 pour activer les alertes d’onde d’avertissement. Toutefois, le Kit de développement logiciel (SDK) .NET définit WarningLevel pour qu’il corresponde à AnalysisLevel dans votre fichier projet.

Pour obtenir des informations sur une erreur ou un avertissement, vous pouvez rechercher le code d’erreur dans l’index de l’aide. Il existe d’autres façons d’obtenir des informations sur une erreur ou un avertissement, qui sont décrites dans Erreurs du compilateur C#. Utilisez TreatWarningsAsErrors pour traiter tous les avertissements comme des erreurs. Utilisez DisabledWarnings pour désactiver certains avertissements.

Niveau d'analyse

L’optionAnalysisLevel spécifie des ondes d’avertissement et des analyseurs supplémentaires à activer. Les avertissements sont des vérifications supplémentaires qui améliorent votre code ou garantissent sa compatibilité avec les versions à venir. Les analyseurs offrent une capacité similaire à celle d'une ligne de démarcation pour améliorer votre code.

<AnalysisLevel>preview</AnalysisLevel>

Niveau d'analyse	Signification
5	Affiche tous les avertissements facultatifs de la vague d’avertissement 5.
6	Affiche tous les avertissements facultatifs de la vague d’avertissement 6.
7	Affiche tous les avertissements facultatifs de la vague d’avertissement 7.
Dernier (par défaut)	Affiche tous les avertissements d’information jusqu’à la version actuelle incluse.
preview	Affiche tous les avertissements d’information jusqu’à la dernière préversion incluse.
aucun	Désactive tous les avertissements d’information.

Pour plus d’informations sur les avertissements facultatifs, consultez Vagues d’avertissement.

TreatWarningsAsErrors

L’option TreatWarningsAsErrors traite tous les avertissements comme des erreurs. Vous pouvez également utiliser WarningsAsErrors pour définir uniquement certains avertissements en tant qu’erreurs. Si vous activez TreatWarningsAsErrors, vous pouvez utiliser WarningsNotAsErrors pour répertorier les avertissements qui ne doivent pas être traités comme des erreurs.

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>

Tous les messages d’avertissement sont signalés comme des erreurs. Le processus de génération s’arrête (aucun fichier de sortie n’est généré). Par défaut, TreatWarningsAsErrors n’est pas en vigueur, ce qui signifie que les avertissements n’empêchent pas la génération d’un fichier de sortie. Le cas échéant, si vous voulez que seuls certains avertissements spécifiques soient considérés comme des erreurs, vous pouvez spécifier une liste séparée par des virgules qui liste les numéros d’avertissement à considérer comme des erreurs. L’ensemble des avertissements de valeur Null peut être spécifié avec le raccourci Nullable. Utilisez WarningLevel pour spécifier le niveau d’avertissements que vous souhaitez faire afficher par le compilateur. Utilisez NoWarn pour désactiver certains avertissements.

Important

Il existe deux différences subtiles entre l’utilisation de l’élément <TreatWarningsAsErrors> dans votre fichier csproj et l’utilisation du commutateur de ligne de commande MSBuild warnaserror. TreatWarningsAsErrors affecte uniquement le compilateur C#, et pas les autres tâches MSBuild dans votre fichier csproj. Le commutateur de ligne de commande warnaserror affecte toutes les tâches. Deuxièmement, le compilateur ne produit aucune sortie sur des avertissements lorsque TreatWarningsAsErrors est utilisé. Le compilateur produit une sortie lorsque le commutateur de ligne de commande warnaserror est utilisé.

WarningsAsErrors et WarningsNotAsErrors

Les options WarningsAsErrors et WarningsNotAsErrors remplacent l’option TreatWarningsAsErrors pour une liste d’avertissements. Cette option peut être utilisée avec tous les avertissements CS. Le préfixe « CS » est facultatif. Vous pouvez utiliser le nombre ou « CS » suivi du numéro d’erreur ou d’avertissement. Pour les autres éléments qui affectent les avertissements, consultez les propriétés MSBuild courantes. Outre la liste des identifiants d’avertissement, vous pouvez également spécifier la chaîne nullable, qui traite tous les avertissements relatifs à la nullité comme des erreurs.

Activer les avertissements 0219 et 0168, ainsi que tous les avertissements nullables en tant qu’erreurs :

<WarningsAsErrors>0219,CS0168,nullable</WarningsAsErrors>

Désactivez les mêmes avertissements en tant qu’erreurs :

<WarningsNotAsErrors>0219,CS0168,nullable</WarningsNotAsErrors>

Vous utilisez WarningsAsErrors pour configurer un ensemble d’avertissements en tant qu’erreurs. Utilisez WarningsNotAsErrors pour configurer un ensemble d’avertissements qui ne doivent pas être des erreurs lorsque vous avez défini tous les avertissements comme des erreurs.

NoWarn

L’option NoWarn vous permet de supprimer du compilateur l’affichage d’un ou plusieurs avertissements, où warningnumber1 et warningnumber2 sont les numéros d’avertissement que vous souhaitez que le compilateur supprime. Séparez les numéros des avertissements par une virgule. Vous pouvez spécifier nullable pour désactiver tous les avertissements liés à la nullabilité.

<NoWarn>warningnumber1,warningnumber2</NoWarn>

Vous avez besoin de spécifier uniquement la partie numérique de l’identificateur d’avertissement. Par exemple, si vous souhaitez supprimer CS0028, spécifiez <NoWarn>28</NoWarn>. Le compilateur ignore silencieusement les numéros d’avertissement passés en NoWarn qui étaient valides dans les versions précédentes et qui ont été supprimés. Par exemple, CS0679 était valide dans le compilateur dans Visual Studio .NET 2002, mais a été supprimé ultérieurement.

Les avertissements suivants ne peuvent pas être supprimés par l’option NoWarn :

Avertissement du compilateur (niveau 1) CS2002
Avertissement du compilateur (niveau 1) CS2023
Avertissement du compilateur (niveau 1) CS2029

Notez que les avertissements sont destinés à être une indication d’un problème potentiel avec votre code. Vous devez donc comprendre les risques de désactivation d’un avertissement particulier. Utilisez NoWarn uniquement lorsque vous êtes certain qu’un avertissement est un faux positif et ne peut pas être un bogue d’exécution.

Vous pouvez utiliser une approche plus ciblée pour désactiver les avertissements :

La plupart des compilateurs fournissent des moyens de désactiver les avertissements uniquement pour certaines lignes de code, afin que vous puissiez toujours passer en revue les avertissements s’ils se produisent ailleurs dans le même projet. Pour supprimer un avertissement uniquement dans une partie spécifique du code dans C#, utilisez #pragma avertissement.
Si votre objectif est de voir une sortie plus concise et plus ciblée dans votre journal de build, vous pouvez modifier le détail du journal de génération. Pour plus d’informations, consultez Comment : afficher, enregistrer et configurer des fichiers journaux de génération.

Pour ajouter des numéros d’avertissement à toute valeur définie précédemment pour NoWarn sans l’écraser, référencez $(NoWarn) comme indiqué dans l’exemple suivant :

   <NoWarn>$(NoWarn);newwarningnumber3;newwarningnumber4</NoWarn>

CodeAnalysisRuleSet

Spécifiez un fichier d’ensemble de règles qui configure des diagnostics spécifiques.

<CodeAnalysisRuleSet>MyConfiguration.ruleset</CodeAnalysisRuleSet>

Où MyConfiguration.ruleset est le chemin d’accès au fichier d’ensemble de règles. Pour plus d’informations sur l’utilisation des ensembles de règles, consultez l’article de la documentation de Visual Studio sur les ensembles de règles.

ErrorLog

Spécifier un fichier pour journaliser tous les diagnostics du compilateur et de l’analyseur.

<ErrorLog>compiler-diagnostics.sarif</ErrorLog>

L’option ErrorLog entraîne le compilateur à générer un journal SARIF (Static Analysis Results Interchange Format). Les journaux SARIF sont généralement lus par des outils qui analysent les résultats des diagnostics du compilateur et de l’analyseur.

Vous pouvez spécifier le format SARIF à l’aide de l’argument version sur l’élément ErrorLog :

<ErrorLog>logVersion21.json,version=2.1</ErrorLog>

Le séparateur peut être une virgule (,) ou un point-virgule (;). Les valeurs valides pour la version sont : « 1 », « 2 » et « 2.1 ». La valeur par défaut est 1. « 2 » et « 2.1 » signifient tous deux SARIF version 2.1.0.

ReportAnalyzer

Créer un rapport sur les informations supplémentaires de l’analyseur, comme l’heure d’exécution.

<ReportAnalyzer>true</ReportAnalyzer>

L’option ReportAnalyzer entraîne le compilateur à emmètre des informations supplémentaires du journal MSBuild qui détaillent les caractéristiques de performances des analyseurs de la compilation. Elle est généralement utilisée par les auteurs d’analyseurs dans le cadre de la validation de l’analyseur.