C#-Compileroptionen zum Melden von Fehlern und Warnungen

Artikel
11/09/2023

Mit den folgenden Optionen wird gesteuert, wie der Compiler Fehler und Warnungen meldet. Die neue MSBuild-Syntax wird fett formatiert dargestellt. Die ältere csc.exe-Syntax wird in code style dargestellt.

WarningLevel / -warn: Legt die Warnstufe fest.
AnalysisLevel: legt die optionale Warnstufe fest.
TreatWarningsAsErrors / -warnaserror: Behandelt alle Warnungen als Fehler.
WarningsAsErrors / -warnaserror: Behandelt mindestens eine Warnung als Fehler.
WarningsNotAsErrors / -warnnotaserror: Behandelt mindestens eine Warnung nicht als Fehler.
NoWarn / -nowarn: legt eine Liste deaktivierter Warnungen fest.
CodeAnalysisRuleSet / -ruleset: Gibt eine Regelsatzdatei an, die bestimmte Diagnosefunktionen deaktiviert.
ErrorLog / -errorlog: Gibt eine Datei für das Protokollieren der gesamten Compiler- und Analysetooldiagnose an.
ReportAnalyzer / -reportanalyzer: meldet zusätzliche Analysetoolinformationen, z. B. Ausführungszeitpunkt.

Hinweis

Weitere Informationen zum Konfigurieren dieser Optionen für Ihr Projekt finden Sie unter Compileroptionen.

WarningLevel

Die Option WarningLevel gibt die vom Compiler anzuzeigende Warnstufe an.

<WarningLevel>3</WarningLevel>

Der Elementwert ist die Warnstufe, die Sie für die Kompilierung anzeigen möchten: Niedrigere Zahlen zeigen nur Warnungen mit hohem Schweregrad an. Höhere Werte zeigen mehr Warnungen an. Der Wert muss 0 (null) oder eine positive ganze Zahl sein:

Warnstufe	Bedeutung
0	Deaktiviert die Ausgabe aller Warnungmeldungen
1	Zeigt schwerwiegende Warnmeldungen an
2	Zeigt Warnungen der Stufe 1 sowie bestimmte, weniger schwerwiegende Warnungen an, z.B. Warnungen zum Ausblenden von Klassenmembern
3	Zeigt Warnungen der Stufe 2 sowie bestimmte, weniger schwerwiegende Warnungen an, z.B. Warnungen zu Ausdrücken, immer nach `true` oder `false` ausgewertet werden
4 (Standard)	Zeigt die Warnungen aller drei Stufen sowie informative Warnungen an

Warnung

Die Compilerbefehlszeile akzeptiert Werte, die größer als 4 sind, um Warnungen in Warnungswellen zu aktivieren. Das .NET SDK legt in Ihrer Projektdatei WarningLevel jedoch auf den Wert von AnalysisLevel fest.

Um Informationen zu einem Fehler oder einer Warnung zu erhalten, schlagen Sie den Fehlercode im Hilfeindex nach. Andere Möglichkeiten zum Abrufen von Informationen zu einem Fehler oder einer Warnung finden Sie unter C#-Compilerfehler. Verwenden Sie TreatWarningsAsErrors, um alle Warnungen als Fehler zu behandeln. Verwenden Sie DisabledWarnings, um bestimmte Warnungen zu deaktivieren.

Analyseebene

Die Option AnalysisLevel gibt zusätzliche Warnwellen und Analysetools an, die aktiviert werden können. Warnungen in Warnwellen sind zusätzliche Überprüfungen, die Ihren Code verbessern oder sicherstellen, dass er mit zukünftigen Releases kompatibel ist. Analysetools bieten lint-ähnliche Funktionen, um Ihren Code zu verbessern.

<AnalysisLevel>preview</AnalysisLevel>

Analyseebene	Bedeutung
5	Zeigt alle optionalen Warnungen in Warnungswelle 5 an.
6	Zeigt alle optionalen Warnungen in Warnungswelle 6 an.
7	Zeigt alle optionalen Warnungen in Warnungswelle 7 an.
Neueste (Standardeinstellung)	Zeigt alle Informationswarnungen bis einschließlich des aktuellen Release an.
preview	Zeigt alle Informationswarnungen bis einschließlich des aktuellen Vorschaurelease an.
Keine	Deaktiviert alle Informationswarnungen.

Weitere Informationen zu optionalen Warnungen finden Sie unter Warnungswellen.

Um Informationen zu einem Fehler oder einer Warnung zu erhalten, schlagen Sie den Fehlercode im Hilfeindex nach. Andere Möglichkeiten zum Abrufen von Informationen zu einem Fehler oder einer Warnung finden Sie unter C#-Compilerfehler. Verwenden Sie TreatWarningsAsErrors, um alle Warnungen als Fehler zu behandeln. Wählen Sie NoWarn aus, um bestimmte Warnungen zu deaktivieren.

TreatWarningsAsErrors

Mit der Option TreatWarningsAsErrors werden alle Warnungen als Fehler behandelt. Sie können WarningsAsErrors auch verwenden, um nur einige Warnungen als Fehler festzulegen. Wenn Sie TreatWarningsAsErrors aktivieren, können Sie mithilfe von WarningsNotAsErrors Warnungen auflisten, die nicht als Fehler behandelt werden sollen.

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>

Alle Warnmeldungen werden stattdessen als Fehler gemeldet. Der Buildprozess wird angehalten (es werden keine Ausgabedateien erstellt). Standardmäßig ist TreatWarningsAsErrors nicht aktiviert, was bedeutet, dass Warnungen die Generierung einer Ausgabedatei nicht verhindern. Wenn nur bestimmte Warnungen als Fehler behandelt werden sollen, können Sie optional eine durch Trennzeichen getrennte Liste mit Warnungsnummern angeben, die als Fehler behandelt werden sollen. Die Gruppe aller Warnungen zur Zulassung von Nullwerten können mithilfe der Kurzform Nullable angegeben werden. Verwenden Sie WarningLevel, um die Warnstufe anzugeben, die vom Compiler angezeigt werden soll. Wählen Sie NoWarn aus, um bestimmte Warnungen zu deaktivieren.

Wichtig

Es gibt zwei geringfügige Unterschiede zwischen der Verwendung des Elements <TreatWarningsAsErrors> in Ihrer CSPROJ-Datei und der Verwendung des MSBuild-Befehlszeilenschalters warnaserror. TreatWarningsAsErrors wirkt sich nur auf den C#-Compiler, nicht auf andere MSBuild-Aufgaben in Ihrer CSPROJ-Datei aus. Der Befehlszeilenschalter warnaserror wirkt sich auf alle Aufgaben aus. Zweitens erzeugt der Compiler keine Ausgabe von Warnungen, wenn TreatWarningsAsErrors verwendet wird. Der Compiler erzeugt eine Ausgabe, wenn der Befehlszeilenschalter warnaserror verwendet wird.

WarningsAsErrors und WarningsNotAsErrors

Die Optionen WarningsAsErrors und WarningsNotAsErrors setzen die Option TreatWarningsAsErrors für eine Liste von Warnungen außer Kraft. Diese Option kann mit allen CS-Warnungen verwendet werden. Das Präfix „CS“ ist optional. Sie können entweder die Nummer oder „CS“ gefolgt von der Fehler- oder Warnungsnummer verwenden. Weitere Elemente, die sich auf Warnungen auswirken, finden Sie unter Allgemeine MSBuild-Eigenschaften. Zusätzlich zur Liste der Warnungs-IDs können Sie außerdem die Zeichenfolge nullable angeben, die alle Warnungen im Zusammenhang mit der NULL-Zulässigkeit als Fehler behandelt.

Aktivieren Sie die Warnungen 0219 und 0168 sowie alle Nullwerte zulassenden Warnungen als Fehler:

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

Deaktivieren derselben Warnungen als Fehler:

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

Sie verwenden WarningsAsErrors, um einen Satz von Warnungen als Fehler zu konfigurieren. Verwenden Sie WarningsNotAsErrors, um einen Satz von Warnungen zu konfigurieren, die keine Fehler sein sollen, wenn Sie alle Warnungen als Fehler festgelegt haben.

NoWarn

Mit der Option NoWarn können Sie verhindern, dass der Compiler Warnungen anzeigt. warningnumber1 und warningnumber2 sind Warnungsnummern, die der Compiler unterdrücken soll. Trennen Sie mehrere Warnnummern durch ein Komma. Sie können nullable angeben, um alle Warnungen im Zusammenhang mit der NULL-Zulässigkeit zu deaktivieren.

<NoWarn>warningnumber1,warningnumber2</NoWarn>

Sie müssen lediglich den numerischen Teil des Warnungsbezeichners angeben. Wenn Sie z. B. CS0028 unterdrücken möchten, könnten Sie <NoWarn>28</NoWarn> angeben. Der Compiler ignoriert automatisch die Warnungsnummern, die an NoWarn übergeben werden und in einer früheren Version gültig waren, jedoch entfernt wurden. CS0679 war z. B. im Compiler in Visual Studio .NET 2002 gültig, wurde aber später entfernt.

Die folgenden Warnungen können nicht durch die Option NoWarn unterdrückt werden:

Compilerwarnung (Stufe 1) CS2002
Compilerwarnung (Stufe 1) CS2023
Compilerwarnung (Stufe 1) CS2029

Beachten Sie, dass Warnungen als Hinweis auf ein potenzielles Problem mit Ihrem Code dienen sollen. Daher sollten Sie die Risiken beim Deaktivieren einer bestimmten Warnung verstehen. Verwenden Sie NoWarn nur, wenn Sie sicher sind, dass eine Warnung ein False Positive ist und kein Laufzeitfehler sein kann.

Möglicherweise möchten Sie einen gezielteren Ansatz zum Deaktivieren von Warnungen verwenden:

Die meisten Compiler bieten Möglichkeiten, Warnungen nur für bestimmte Codezeilen zu deaktivieren, sodass Sie die Warnungen weiterhin überprüfen können, wenn sie an anderen Stellen im selben Projekt auftreten. Wenn Sie eine Warnung nur in einem bestimmten Teil des Codes in C# unterdrücken möchten, verwenden Sie #pragma-Warnungen.
Wenn Sie eine präzisere und zielgerichtetere Ausgabe in Ihrem Buildprotokoll sehen möchten, sollten Sie die Ausführlichkeit des Buildprotokolls ändern. Weitere Informationen finden Sie unter Vorgehensweise: Anzeigen, Speichern und Konfigurieren von Buildprotokolldateien.

Wenn Sie Warnungsnummern zu einem zuvor festgelegten Wert für NoWarn hinzufügen möchten, ohne ihn zu überschreiben, verweisen Sie wie im folgenden Beispiel gezeigt auf $(NoWarn):

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

CodeAnalysisRuleSet

Gibt eine Regelsatzdatei an, die bestimmte Diagnosefunktionen deaktiviert.

<CodeAnalysisRuleSet>MyConfiguration.ruleset</CodeAnalysisRuleSet>

Dabei stellt MyConfiguration.ruleset den Pfad zur Regelsatzdatei dar. Weitere Informationen zur Verwendung von Regelsätzen finden Sie im Artikel in der Visual Studio-Dokumentation zu Regelsätzen.

ErrorLog

Angeben einer Datei für das Protokollieren der gesamten Compiler- und Analysetooldiagnose.

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

Die Option ErrorLog bewirkt, dass der Compiler ein SARIF-Protokoll (Static Analysis Results Interchange Format) ausgibt. SARIF-Protokolle werden in der Regel von Tools gelesen, die die Ergebnisse des Compilers und der Analysetooldiagnose analysieren.

Sie können das SARIF-Format mithilfe des Arguments version für das Element ErrorLog angeben:

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

Das Trennzeichen kann entweder ein Komma (,) oder Semikolon (;) sein. Gültige Werte für „version“ sind : „1“, „2“ und „2.1“. Der Standardwert ist „1“. „2“ und „2.1“ bedeuten SARIF-Version 2.1.0.

ReportAnalyzer

Berichten zusätzlicher Analysetoolinformationen, z.B. der Zeitpunkt der Ausführung.

<ReportAnalyzer>true</ReportAnalyzer>

Die Option ReportAnalyzer veranlasst den Compiler, zusätzliche MSBuild-Protokollinformationen auszugeben, die die Leistungsmerkmale der Analysetools im Build detailliert darstellen. Sie wird in der Regel von Autoren von Analysetools im Rahmen der Überprüfung der Analysetools verwendet.