Opcje kompilatora języka C# do zgłaszania błędów i ostrzeżeń

Artykuł
05/20/2024

Poniższe opcje kontrolują sposób raportowania błędów i ostrzeżeń przez kompilator. Nowa składnia programu MSBuild jest wyświetlana w obszarze Pogrubienie. Starsza składnia csc.exe jest wyświetlana w pliku code style.

WarningLevel / -warn: ustaw poziom ostrzeżenia.
AnalysisLevel: ustaw opcjonalny poziom ostrzeżenia.
TreatWarningsAsErrors / -warnaserror: Traktuj wszystkie ostrzeżenia jako błędy
WarningsAsErrors / -warnaserror: Traktuj co najmniej jedno ostrzeżenie jako błędy
WarningsNotAsErrors / -warnnotaserror: Traktuj jedno lub więcej ostrzeżeń, które nie są błędami
NoWarn / -nowarn: ustaw listę wyłączonych ostrzeżeń.
CodeAnalysisRuleSet / -ruleset: określ plik zestawu reguł, który wyłącza konkretną diagnostykę.
ErrorLog / -errorlog: określ plik do rejestrowania wszystkich diagnostyki kompilatora i analizatora.
ReportAnalyzer / -reportanalyzer: zgłoś dodatkowe informacje dotyczące analizatora, takie jak czas wykonywania.

Uwaga

Aby uzyskać więcej informacji na temat konfigurowania tych opcji dla projektu, zobacz Opcje kompilatora.

OstrzeżeniePoszczel

Opcja WarningLevel określa poziom ostrzeżenia kompilatora do wyświetlenia.

<WarningLevel>3</WarningLevel>

Wartość elementu to poziom ostrzeżenia wyświetlany dla kompilacji: niższe liczby pokazują tylko ostrzeżenia o wysokiej ważności. Wyższe liczby pokazują więcej ostrzeżeń. Wartość musi być równa zero lub dodatnia liczba całkowita:

Poziom ostrzeżenia	Znaczenie
0	Wyłącza emisję wszystkich komunikatów ostrzegawczych.
1	Wyświetla poważne komunikaty ostrzegawcze.
2	Wyświetla ostrzeżenia poziomu 1 oraz pewne, mniej poważne ostrzeżenia, takie jak ostrzeżenia dotyczące ukrywania składowych klasy.
3	Wyświetla ostrzeżenia poziomu 2 oraz pewne, mniej poważne ostrzeżenia, takie jak ostrzeżenia dotyczące wyrażeń, które zawsze oceniają wartość lub `true` `false`.
4 (ustawienie domyślne)	Wyświetla wszystkie ostrzeżenia poziomu 3 oraz ostrzeżenia informacyjne.

Ostrzeżenie

Wiersz polecenia kompilatora akceptuje wartości większe niż 4, aby włączyć ostrzeżenia o fali ostrzegawczej. Jednak zestaw SDK platformy .NET ustawia wartość WarningLevel tak, aby był zgodny z elementem AnalysisLevel w pliku projektu.

Aby uzyskać informacje o błędzie lub ostrzeżeniu, możesz wyszukać kod błędu w indeksie pomocy. Aby uzyskać informacje o błędzie lub ostrzeżeniu, zobacz Błędy kompilatora języka C#. Użyj polecenia TreatWarningsAsErrors , aby traktować wszystkie ostrzeżenia jako błędy. Użyj opcji DisabledWarnings, aby wyłączyć niektóre ostrzeżenia.

Poziom analizy

Opcja AnalysisLevel określa dodatkowe fale ostrzegawcze i analizatory do włączenia. Ostrzeżenia dotyczące fali ostrzegawczej to dodatkowe testy, które usprawniają kod, lub upewnij się, że będą one zgodne z nadchodzącymi wersjami. Analizatory zapewniają funkcję przypominającą lintę, aby ulepszyć kod.

<AnalysisLevel>preview</AnalysisLevel>

Poziom analizy	Znaczenie
5	Wyświetla wszystkie opcjonalne ostrzeżenia o fali 5.
6	Wyświetla wszystkie opcjonalne ostrzeżenia z falą 6.
7	Wyświetla wszystkie opcjonalne ostrzeżenia o fali 7.
latest (wartość domyślna)	Wyświetla wszystkie ostrzeżenia informacyjne do bieżącej wersji i w tym bieżące.
preview	Wyświetla wszystkie ostrzeżenia informacyjne do najnowszej wersji zapoznawczej i dołączane do najnowszej wersji zapoznawczej.
Brak	Wyłącza wszystkie ostrzeżenia informacyjne.

Aby uzyskać więcej informacji na temat opcjonalnych ostrzeżeń, zobacz Fale ostrzegawcze.

Aby uzyskać informacje o błędzie lub ostrzeżeniu, możesz wyszukać kod błędu w indeksie pomocy. Aby uzyskać informacje o błędzie lub ostrzeżeniu, zobacz Błędy kompilatora języka C#. Użyj polecenia TreatWarningsAsErrors , aby traktować wszystkie ostrzeżenia jako błędy. Użyj polecenia NoWarn , aby wyłączyć niektóre ostrzeżenia.

TreatWarningsAsErrors

Opcja TreatWarningsAsErrors traktuje wszystkie ostrzeżenia jako błędy. Możesz również użyć funkcji WarningsAsErrors , aby ustawić tylko niektóre ostrzeżenia jako błędy. Jeśli włączysz funkcję TreatWarningsAsErrors, możesz użyć funkcji WarningsNotAsErrors , aby wyświetlić listę ostrzeżeń, które nie powinny być traktowane jako błędy.

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>

Wszystkie komunikaty ostrzegawcze są zamiast tego zgłaszane jako błędy. Proces kompilacji zostaje zatrzymany (nie są tworzone żadne pliki wyjściowe). Domyślnie funkcja TreatWarningsAsErrors nie działa, co oznacza, że ostrzeżenia nie uniemożliwiają generowania pliku wyjściowego. Opcjonalnie, jeśli chcesz, aby tylko kilka konkretnych ostrzeżeń było traktowanych jako błędy, możesz określić rozdzielaną przecinkami listę numerów ostrzeżeń, które mają być traktowane jako błędy. Zestaw wszystkich ostrzeżeń o wartości null można określić za pomocą skróconej skróconej wartości null . Użyj polecenia WarningLevel , aby określić poziom ostrzeżeń, które mają być wyświetlane przez kompilator. Użyj polecenia NoWarn , aby wyłączyć niektóre ostrzeżenia.

Ważne

Istnieją dwie subtelne różnice między użyciem <TreatWarningsAsErrors> elementu w pliku csproj i użyciem przełącznika warnaserror wiersza polecenia MSBuild. TreatWarningsAsErrors ma wpływ tylko na kompilator języka C#, a nie inne zadania MSBuild w pliku csproj . Przełącznik warnaserror wiersza polecenia ma wpływ na wszystkie zadania. Po drugie, kompilator nie generuje żadnych danych wyjściowych w przypadku użycia funkcji TreatWarningsAsErrors . Kompilator generuje dane wyjściowe, gdy warnaserror jest używany przełącznik wiersza polecenia.

WarningsAsErrors i WarningsNotAsErrors

Opcje WarningsAsErrors i WarningsNotAsErrors zastępują opcję TreatWarningsAsErrors dla listy ostrzeżeń. Tej opcji można używać ze wszystkimi ostrzeżeniami CS . Prefiks "CS" jest opcjonalny. Możesz użyć numeru lub "CS", po którym następuje błąd lub numer ostrzeżenia. Aby zapoznać się z innymi elementami, które mają wpływ na ostrzeżenia, zobacz typowe właściwości programu MSBuild. Oprócz listy identyfikatorów ostrzeżeń można również określić ciąg nullable, który traktuje wszystkie ostrzeżenia związane z wartością null jako błędy.

Włącz ostrzeżenia 0219, 0168 i wszystkie ostrzeżenia dopuszczające wartość null jako błędy:

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

Wyłącz te same ostrzeżenia co błędy:

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

Użyj polecenia WarningsAsErrors , aby skonfigurować zestaw ostrzeżeń jako błędy. Użyj funkcji WarningsNotAsErrors , aby skonfigurować zestaw ostrzeżeń, które nie powinny być błędami po ustawieniu wszystkich ostrzeżeń jako błędów.

NoWarn

Opcja NoWarn umożliwia pomijanie kompilatora wyświetlania co najmniej jednego ostrzeżenia, gdzie warningnumber1warningnumber2 , to numery ostrzegawcze, które mają zostać pominięte przez kompilator. Oddziel wiele numerów ostrzeżeń przecinkami. Można określić nullable , aby wyłączyć wszystkie ostrzeżenia związane z wartością null.

<NoWarn>warningnumber1,warningnumber2</NoWarn>

Należy określić tylko część liczbową identyfikatora ostrzeżenia. Jeśli na przykład chcesz pominąć CS0028, możesz określić wartość <NoWarn>28</NoWarn>. Kompilator dyskretnie ignoruje numery ostrzeżeń przekazane do noWarn , które były prawidłowe w poprzednich wersjach, ale zostały usunięte. Na przykład CS0679 był prawidłowy w kompilatorze w programie Visual Studio .NET 2002, ale został usunięty później.

Następujące ostrzeżenia nie mogą być pomijane przez opcję NoWarn :

Ostrzeżenie kompilatora (poziom 1) CS2002
Ostrzeżenie kompilatora (poziom 1) CS2023
Ostrzeżenie kompilatora (poziom 1) CS2029

Należy pamiętać, że ostrzeżenia mają wskazywać potencjalny problem z kodem, dlatego należy zrozumieć ryzyko wyłączenia dowolnego konkretnego ostrzeżenia. Używaj wartości NoWarn tylko wtedy, gdy masz pewność, że ostrzeżenie jest wynikiem fałszywie dodatnim i nie może być usterką środowiska uruchomieniowego.

Możesz użyć bardziej ukierunkowanego podejścia do wyłączania ostrzeżeń:

Większość kompilatorów udostępnia sposoby wyłączania ostrzeżeń tylko dla niektórych wierszy kodu, dzięki czemu można nadal przeglądać ostrzeżenia, jeśli wystąpią w innym miejscu w tym samym projekcie. Aby pominąć ostrzeżenie tylko w określonej części kodu w języku C#, użyj ostrzeżenia #pragma.
Jeśli twoim celem jest wyświetlanie bardziej zwięzłych i skoncentrowanych danych wyjściowych w dzienniku kompilacji, warto zmienić szczegółowość dziennika kompilacji. Aby uzyskać więcej informacji, zobacz Jak wyświetlać, zapisywać i konfigurować pliki dziennika kompilacji.

Aby dodać numery ostrzegawcze do dowolnej wcześniej ustawionej wartości noWarn bez zastępowania, odwołanie$(NoWarn), jak pokazano w poniższym przykładzie:

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

CodeAnalysisRuleSet

Określ plik zestawu reguł, który konfiguruje określoną diagnostykę.

<CodeAnalysisRuleSet>MyConfiguration.ruleset</CodeAnalysisRuleSet>

Gdzie MyConfiguration.ruleset jest ścieżką do pliku zestawu reguł. Aby uzyskać więcej informacji na temat używania zestawów reguł, zobacz artykuł w dokumentacji programu Visual Studio dotyczącej zestawów reguł.

Dziennik błędów

Określ plik do rejestrowania wszystkich diagnostyki kompilatora i analizatora.

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

Opcja ErrorLog powoduje, że kompilator wyprowadza dziennik SARIF (Static Analysis Results Interchange Format). Dzienniki SARIF są zwykle odczytywane przez narzędzia analizujące wyniki z diagnostyki kompilatora i analizatora.

Format SARIF można określić przy użyciu argumentu version ErrorLog do elementu:

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

Separator może być przecinkiem (,) lub średnikiem (;). Prawidłowe wartości wersji to: "1", "2" i "2.1". Wartość domyślna to "1". Wartości "2" i "2.1" oznaczają wersję SARIF w wersji 2.1.0.

ReportAnalyzer

Zgłaszanie dodatkowych informacji analizatora, takich jak czas wykonywania.

<ReportAnalyzer>true</ReportAnalyzer>

Opcja ReportAnalyzer powoduje, że kompilator emituje dodatkowe informacje dziennika MSBuild, które zawierają szczegółowe informacje o wydajności analizatorów w kompilacji. Jest on zwykle używany przez autorów analizatorów w ramach walidacji analizatora.