用於報告錯誤和警告的 C# 編譯器選項

發行項
02/27/2024

下列選項控制編譯器如何報告錯誤和警告。新的 MSBuild 語法會以「粗體」顯示。較舊的 csc.exe 語法會以code style顯示。

WarningLevel / -warn：設定警告層級。
AnalysisLevel：設定選用警告層級。
TreatWarningsAsErrors / -warnaserror：將所有警告視為錯誤
WarningsAsErrors / -warnaserror：將一或多個警告視為錯誤
WarningsNotAsErrors / -warnnotaserror：不將一或多個警告視為錯誤
NoWarn / -nowarn：設定停用警告清單。
CodeAnalysisRuleSet / -ruleset：指定停用特定診斷的規則集檔案。
ErrorLog / -errorlog：指定檔案，記錄所有編譯器和分析器診斷。
ReportAnalyzer / -reportanalyzer：報告如執行時間等額外的分析器資訊。

WarningLevel

WarningLevel 選項會指定編譯器顯示的警告層級。

<WarningLevel>3</WarningLevel>

元素值是您想要針對編譯顯示的警告層級：較低的數字只會顯示高嚴重性警告。較高的數字則顯示更多的警告。其值必須是零或正整數：

警告層級	意義
0	關閉發出所有警告訊息。
1	顯示嚴重警告訊息。
2	顯示層級 1 警告，以及特定較不嚴重的警告，例如隱藏類別成員的警告。
3	顯示層級 2 警告，以及特定較不嚴重的警告，例如一律評估為 `true` 或 `false` 之運算式的警告。
4 (預設)	顯示所有層級 3 警告以及告知性警告。

警告

為了啟用警告波浪紋警告，編譯器命令列接受大於 4 的值。但 .NET SDK 會設定 WarningLevel 以對應至專案檔案中的 AnalysisLevel。

若要取得錯誤或警告資訊，您可以查閱 [說明索引] 中的錯誤碼。如需取得錯誤或警告資訊的其他方式，請參閱 C# 編譯器錯誤。使用 TreatWarningsAsErrors：將所有警告視為錯誤。使用 DisabledWarnings 停用特定警告。

分析層級

AnalysisLevel 選項會指定要啟用的其他警告波浪紋和分析器。警告波浪紋警告是可改善程式碼的其他檢查，或可確保其與即將推出的版本相容。分析器提供類似 lint 的功能，可改善您的程式碼。

<AnalysisLevel>preview</AnalysisLevel>

分析層級	意義
5	顯示所有選用警告波浪紋第 5 波警告。
6	顯示所有選用警告波浪紋第 6 波警告。
7	顯示所有選用警告波浪紋第 7 波警告。
最新 (預設)	顯示所有資訊警告，包含目前的版本。
preview	顯示所有資訊警告，包含最新的預覽版本。
none	關閉所有資訊警告。

如需選擇性警告詳細資訊，請參閱警告波浪。

若要取得錯誤或警告資訊，您可以查閱 [說明索引] 中的錯誤碼。如需取得錯誤或警告資訊的其他方式，請參閱 C# 編譯器錯誤。使用 TreatWarningsAsErrors：將所有警告視為錯誤。使用 NoWarn 停用特定警告。

TreatWarningsAsErrors

TreatWarningsAsErrors 選項會將所有警告視為錯誤。您也可以使用 WarningsAsErrors 僅將部分警告設定為錯誤。如果開啟 TreatWarningsAsErrors，則可以使用 WarningsNotAsErrors 列出不應視為錯誤的警告。

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>

所有警告訊息都會報告為錯誤。組建流程會停止 (不會組建任何輸出檔案)。 TreatWarningsAsErrors 預設為無效，表示警告不會禁止產生輸出檔案。選擇性，如果您只想要將少數特定警告視為錯誤，則可以指定將以逗號分隔的警告編號清單視為錯誤。您可以使用 Nullable 速記指定所有可 NULL 性的警告集合。使用 WarningLevel 指定您想要編譯器顯示的警告等級。使用 NoWarn 停用特定警告。

重要

在 csproj 檔案中使用 <TreatWarningsAsErrors> 元素和使用 warnaserrorMSBuild 命令列參數之間有兩個細微的差異。 TreatWarningsAsErrors 只會影響 C# 編譯器，而不會影響在 csproj 檔案中的任何其他 MSBuild 工作。 warnaserror 命令列參數會影響所有工作。其次，使用 TreatWarningsAsErrors 時，編譯器不會在任何警告上產生任何輸出。使用命令列參數時 warnaserror ，編譯器會產生輸出。

WarningsAsErrors 和 WarningsNotAsErrors

WarningsAsErrors 和 WarningsNotAsErrors 選項會覆寫警告清單的 TreatWarningsAsErrors 選項。此選項可以搭配所有 CS 警告使用。 "CS" 前置詞是選擇性的。您可以使用號碼或後面接著錯誤或警告編號「CS」。如需影響警告的其他元素，請參閱一般 MSBuild 屬性。

啟用警告 0219 和 0168 作為錯誤：

<WarningsAsErrors>0219,CS0168</WarningsAsErrors>

停用與錯誤相同的警告：

<WarningsNotAsErrors>0219,CS0168</WarningsNotAsErrors>

您可以使用 WarningsAsErrors 將一組警告設定為錯誤。使用 WarningsNotAsErrors 設定一組警告，當您將所有警告設定為錯誤時，不應該發生錯誤。

NoWarn

NoWarn 選項可讓編譯器隱藏一個或多個警告，其中 warningnumber1、warningnumber2 是您希望編譯器隱藏的警告編號。請以逗點分隔多個警告編號。

<NoWarn>warningnumber1,warningnumber2</NoWarn>

您只需要指定警告識別項的數值部分。例如，如果您想要隱藏 CS0028，您可以指定 <NoWarn>28</NoWarn>。編譯器以無訊息方式略過傳遞給 NoWarn 的警告編號，它在舊版中有效但已移除。例如，CS0679 在 Visual Studio .NET 2002 的編譯器中有效，但稍後已移除。

NoWarn 選項無法隱藏下列警告︰

編譯器警告 (層級 1) CS2002
編譯器警告 (層級 1) CS2023
編譯器警告 (層級 1) CS2029

請注意，警告是要指出程式碼的潛在問題，因此您應該了解停用任何特定警告的風險。請只在確定警告是誤判，且不可能是執行階段錯誤時，再使用 NoWarn。

您可能會想要使用更有針對性的方法，來停用警告：

大部分的編譯器都提供方法，只針對特定程式碼停用警告，因此，如果警告發生在相同專案中的其他地方，您仍然可以檢閱這些警告。若是只在 C# 中特定部分程式碼隱藏警告，請使用 #pragma warning。
如果您的目標是在組建記錄檔中看到更簡潔且聚焦的輸出，您可能會想要變更組建記錄檔詳細程度。如需詳細資訊，請參閱如何：檢閱、儲存和設定組建記錄檔。

若要在不覆寫的情況下，將警告編號新增至先前為 NoWarn 設定的任何值，請參考 $(NoWarn)，如下列範例所示：

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

CodeAnalysisRuleSet

指定設定特定診斷的規則集檔案。

<CodeAnalysisRuleSet>MyConfiguration.ruleset</CodeAnalysisRuleSet>

其中 MyConfiguration.ruleset 是規則集檔案的路徑。如需使用規則集的詳細資訊，請參閱規則集中 Visual Studio 文件的文章。

ErrorLog

指定檔案，記錄所有編譯器和分析器的診斷資料。

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

ErrorLog 選項會使編譯器輸出靜態分析結果交換格式 (SARIF) 記錄(英文)。 SARIF 記錄通常由分析編譯器和分析器診斷結果的工具讀取。

您可以使用 ErrorLog 元素的 version 引數指定 SARIF 格式：

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

分隔符號可以是逗號 (,) 或分號 (;)。版本的有效值為：「1」、「2」和「2.1」。預設值為「1」。「2」和「2.1」均表示 SARIF 2.1.0 版本。

ReportAnalyzer

回報其他分析器資訊，例如執行時間。

<ReportAnalyzer>true</ReportAnalyzer>

ReportAnalyzer 選項會讓編譯器發出額外的 MSBuild 記錄資訊，詳細說明組建中分析器的效能特性。分析器建立者通常會將其作為驗證分析器的組件使用。

重要

僅在使用 -verbosity:detailed 命令列選項時，被產生的此旗標才會產生額外的記錄資訊。如需詳細資訊，請參閱 MSBuild 文件中的參數一文。