用于报告错误和警告的 C# 编译器选项

项目
11/30/2023

以下选项控制编译器如何报告错误和警告。新的 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 警告。
最新（默认值）	显示所有信息性警告，包括当前版本在内。
预览	显示所有信息性警告，包括最新的预览版本在内。
无	关闭所有信息性警告。

有关可选警告的详细信息，请参阅警告波。

若要获取有关错误或警告的信息，可以在帮助索引中查找错误代码。有关获取错误或警告信息的其他方法，请参阅 C# 编译器错误。使用 TreatWarningsAsErrors 将所有警告视为错误。使用 NoWarn 禁用某些警告。

TreatWarningsAsErrors

TreatWarningsAsErrors 选项将所有警告视为错误。你还可以使用 WarningsAsErrors 仅将部分警告设置为错误。如果启用 TreatWarningsAsErrors，则可以使用 WarningsNotAsErrors 列出不应被视为错误的警告。

<TreatWarningsAsErrors>true</TreatWarningsAsErrors>

而是将所有警告消息报告为错误。生成过程会停止（不生成输出文件）。默认情况下，TreatWarningsAsErrors 不生效，这意味着警告不会阻止生成输出文件。（可选）如果希望仅将一些特定警告视为错误，则可以指定视为错误的警告编号的逗号分隔列表。可以使用 Nullable 的简写形式指定所有为 Null 性警告的集合。使用 WarningLevel 指定你希望编译器显示的警告等级。使用 NoWarn 禁用某些警告。

重要

使用 csproj 文件中的 <TreatWarningsAsErrors> 元素与使用 warnaserror MSBuild 命令行开关之间存在两个细微的差异。 TreatWarningsAsErrors 仅影响 C# 编译器，不会影响 csproj 文件中的任何其他 MSBuild 任务。 warnaserror 命令行开关会影响所有任务。其次，在使用 TreatWarningsAsErrors 时，编译器不会对任何警告生成任何输出。使用 warnaserror 命令行开关时，编译器将生成输出。

WarningsAsErrors 和 WarningsNotAsErrors

WarningsAsErrors 和 WarningsNotAsErrors 选项会覆盖警告列表的 TreatWarningsAsErrors 选项。此选项可用于所有 CS 警告。 “CS”前缀是可选的。可以使用数字或“CS”，后跟错误或警告编号。有关影响警告的其他元素，请参阅 Common 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

请注意，警告旨在表明代码存在潜在问题，因此应了解禁用任何特定警告的风险。仅当确定警告为误报且不可能是运行时 bug 时，才使用 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 文档中的开关一文。