代码分析的配置选项

代码分析规则具有多种配置选项。 这些选项是在分析器配置文件中使用 <option key> = <option value> 语法以键值对形式指定的。 其他选项（配置代码分析作为整体）可用作项目文件中的属性。

最常见的配置选项是规则的严重性。 你可以为任意规则（包括代码质量规则和代码样式规则）配置严重性级别。 例如，若要启用某个规则作为警告，可以向分析器配置文件文件添加以下键值对：

dotnet_diagnostic.<rule ID>.severity = warning

你还可以配置其他选项，来自定义规则行为：

代码质量规则具有用于配置行为的选项，例如规则适用的方法名称。

代码样式规则具有自定义代码样式选项。

第三方分析器规则可以使用自定义键名和值格式定义各自的配置选项。

常规选项

这些选项适用于整个代码分析。 它们不能仅应用于特定规则。

分析模式

启用代码分析

排除生成的代码

有关其他选项的信息，请参阅代码分析属性。

启用代码分析

代码分析功能针对面向 .NET 5 及更高版本的项目默认启用。 如果具有 .NET 5+ SDK 但项目面向不同的 .NET 实现，则必须通过将项目文件中的 EnableNETAnalyzers 属性设置为 true 以手动启用代码分析。

<PropertyGroup>

<EnableNETAnalyzers>true</EnableNETAnalyzers>

</PropertyGroup>

分析模式

虽然 .NET SDK 包含所有代码分析规则，但在默认情况下只会启用部分代码分析规则。 分析模式确定要启用的规则集（如果有）。 你可以选择一个更积极的分析模式（其中大多数或全部规则均已启用），或选择一个更保守的模式（其中大多数或全部规则均已禁用），然后根据需要选择特定规则。 通过将 AnalysisMode 属性添加到项目文件来设置分析模式。

<PropertyGroup>

<AnalysisMode>Recommended</AnalysisMode>

</PropertyGroup>

排除生成的代码

.NET 代码分析器警告对生成的代码文件不起作用，比如对于设计器生成的文件，用户无法通过编辑这些文件来修复任何违规行为。 在大多数情况下，代码分析器会跳过生成的代码文件，并且不会报告这些文件上的违规行为。

默认情况下，具有特定文件扩展名或自动生成的文件头的文件会被视为生成的代码文件。 例如，以 .designer.cs 或 .generated.cs 结尾的文件名被视为生成的代码。 使用该配置选项可以指定更多命名模式作为生成的代码。 通过将 generated_code = true | false 条目添加到配置文件，可以配置额外的文件和文件夹。 例如，若要将名称以 .MyGenerated.cs 结尾的所有文件视为生成的代码，请添加以下条目：

[*.MyGenerated.cs]

generated_code = true

特定于规则的选项

特定于规则的选项可应用于一个规则、一组规则或所有规则。 特定于规则的选项包括：

规则严重性级别

特定于代码质量规则的选项

严重性级别

下表显示了可为所有分析器规则（包括代码质量和代码样式规则）配置的各种规则严重性。

严重性配置值

生成时行为

error

违规行为以生成错误形式出现，并会导致生成失败。

warning

违规行为以生成警告形式出现，但不会导致生成失败（除非你已设置将警告视为错误的选项）。

suggestion

违规行为以生成消息形式出现，在 Visual Studio IDE 中以建议形式出现。

silent

违规行为对用户不可见。

none

完全禁止显示规则。

default

使用规则的默认严重性。 Roslyn 分析器存储库列出了每个 .NET 版本的默认严重性。 在该表中，“禁用”与 none 对应，“隐藏”与 silent 对应，“信息”与 suggestion 对应。

提示

若要了解规则严重性在 Visual Studio 中的显示方式，请参阅严重性级别。

范围

单一规则

若要为单个规则设置规则严重性，请使用以下语法。

dotnet_diagnostic.<rule ID>.severity = <severity value>

规则类别

若要为某个规则类别设置默认规则严重性，请使用以下语法。

dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity value>

在规则类别中列出并描述了不同的类别。 此外，可以在其参考页上找到特定规则的类别，例如 CA1000。

所有规则

若要为所有分析器规则设置默认规则严重性，请使用以下语法。

dotnet_analyzer_diagnostic.severity = <severity value>

重要

当你使用一个条目为多个规则配置严重性级别时，无论是为一个规则类别还是为所有规则配置，严重性都只适用于默认情况下启用的规则 。 若要启用默认情况下已禁用的规则，必须执行以下任一操作：

为每个规则添加一个显式 dotnet_diagnostic.<rule ID>.severity = <severity> 配置条目。

在 .NET 6 及更高版本中，通过将 <AnalysisMode<Category>> 设置为 All 启用一种类别的规则。

通过将 <AnalysisMode> 设置为 All 或将 <AnalysisLevel> 设置为 latest-All 来启用所有规则。

优先级

如果你有多个严重性配置条目可应用于同一个规则 ID，将按以下顺序选择优先级：

基于 ID 的单个规则的条目优先于一个类别的条目。

一个类别的条目优先于所有分析器规则的条目。

请考虑以下示例，其中 CA1822 属于“性能”类别：

[*.cs]

dotnet_diagnostic.CA1822.severity = error

dotnet_analyzer_diagnostic.category-performance.severity = warning

dotnet_analyzer_diagnostic.severity = suggestion

在前面的示例中，三个严重性条目都适用于 CA1822。 但是，按照指定的优先级规则，第一个基于规则 ID 的条目优先于后续条目。 在此示例中，CA1822 的有效严重性为 error。 “性能”类别内的所有其他规则的严重性为 warning。

若要了解如何确定文件间的优先级，请参阅“配置文件”一文的“优先级”部分。