代码分析的配置选项

  • 项目

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

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

dotnet_diagnostic.<rule ID>.severity = warning

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

  • 代码质量规则具有用行为选项，例如规则适用的方法名称。
  • 代码样式规则具有样式首选项选项，例如需要在何处放置新行。
  • 第三方分析器规则可以使用自定义键名和值格式定义各自的配置选项。

常规选项

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

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

分析模式

虽然 .NET SDK 包含所有代码分析规则，但在默认情况下只会启用部分代码分析规则。 分析模式确定要启用的规则集（如果有）。 可以选择更激进的启用大多数或全部规则的分析模式。 或者，可以选择更保守的分析模式，其中大多数或所有规则都处于禁用状态，然后你可以按需选择加入特定规则。 通过将 <AnalysisMode> MSBuild 属性添加到项目文件来设置分析模式。

<PropertyGroup>
  <AnalysisMode>Recommended</AnalysisMode>
</PropertyGroup>

从 .NET 6 开始，还可以使用 <AnalysisMode<Category>> MSBuild 属性批量启用规则类别。

注意

如果使用 MSBuild 属性（如 AnalysisMode）配置代码分析，则忽略在配置文件中设置的任何批量配置选项。 例如，如果已批量启用 .editorconfig 文件中的所有规则或类别的规则，则会忽略该配置。

启用代码分析

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

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

排除生成的代码

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

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

[*.MyGenerated.cs]
generated_code = true

特定于规则的选项

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

严重性级别

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

严重性配置值 生成时行为
error 违规行为以生成错误形式出现，并会导致生成失败。
warning 违规行为以生成警告形式出现，但不会导致生成失败（除非你已设置将警告视为错误的选项）。
suggestion 违规行为以生成消息形式出现，在 Visual Studio IDE 中以建议形式出现。 （在 Visual Studio 中，建议在前两个字符下显示为三个灰色点。）
silent 违规行为对用户不可见。

但是，对于代码样式规则，Visual Studio 代码生成功能仍生成此样式中的代码。 这些规则还参与清理，并在“快速操作和重构”菜单中显示。
none 完全禁止显示规则。

但是，对于代码样式规则，Visual Studio 代码生成功能仍生成此样式中的代码。
default 使用规则的默认严重性。 Roslyn 分析器存储库列出了每个 .NET 版本的默认严重性。 在该表中，“禁用”与 none 对应，“隐藏”与 silent 对应，“信息”与 suggestion 对应。

范围

  • 单一规则

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

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

  • 规则类别

    若要为某个规则类别设置默认规则严重性，请使用以下语法。 但是，此严重性设置仅影响默认启用的类别中的规则。

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

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

  • 所有规则

    若要为所有分析器规则设置默认规则严重性，请使用以下语法。 但是，此严重性设置仅影响默认启用的规则。

    dotnet_analyzer_diagnostic.severity = <severity value>

重要

当你使用一个条目为多个规则配置严重性级别时，无论是为一个规则类别还是为所有规则配置，严重性都只适用于默认情况下启用的规则 。 如果使用 MSBuild 属性 <AnalysisMode> 或 <AnalysisLevel> 启用所有规则，则会忽略任何批量 dotnet_analyzer_diagnostic 选项。 因此，最好通过将 <AnalysisMode<类别>> 设置为 All 来启用规则类别。

注意

为单个规则设置严重性的前缀 dotnet_diagnostic 与通过类别配置严重性或为所有规则配置严重性的前缀 dotnet_analyzer_diagnostic 略有不同。

优先级

如果你有多个严重性配置条目可应用于同一个规则 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。

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