自定义 Roslyn 分析器规则

每个 Roslyn 分析器规则或诊断都有默认的严重性和抑制状态，可在项目中进行自定义。 本文介绍了如何设置分析器严重性和抑制分析器冲突。

严重性级别

在 Visual Studio 2019 版本 16.3 和更高版本中，可以在灯泡菜单和“错误列表”窗口中配置 EditorConfig 文件中的分析器规则的严重性。

下表显示了可为诊断配置的不同严重性选项：

严重性（解决方案资源管理器）	严重性（EditorConfig 文件）	生成时行为	编辑器行为
错误	error	违规情况显示在“错误列表”窗口的“错误”选项卡中和命令行生成输出中，并导致生成失败。	违规代码用红色波浪下划线表示，并用滚动条中的红色小框标记。
警告	warning	违规情况显示在“错误列表”窗口的“警告”选项卡中和命令行生成输出中，但不会导致生成失败。	违规代码用绿色波浪下划线表示，并用滚动条中的绿色小框标记。
建议	suggestion	违规情况显示在“错误列表”窗口的“信息”选项卡中，但不显示在命令行生成输出中。	受影响的代码用灰色波浪下划线表示，并用滚动条中的灰色小框标记。
无提示	silent	对用户不可见。	对用户不可见，但诊断被报告给 IDE 诊断引擎。
无	none	完全禁止显示。	完全禁止显示。
默认	default	对应于规则的默认严重性。 若要确定规则的默认值，请查看其“属性”窗口。	对应于规则的默认严重性。

查看规则冲突

如果分析器发现任何违反分析器规则的情况，则会在“错误列表”窗口和代码编辑器中报告这些违规情况。

以下屏幕截图显示了“错误列表”窗口中报告的违反规则的情况。 错误列表中报告的分析器违规情况与规则的严重性级别设置相匹配：

违反分析器规则的情况也会在代码编辑器中以波浪线的形式显示在违规代码下。 例如，以下屏幕截图显示了三个违规情况：一个错误（红色波浪线）、一个警告（绿色波浪线）和一个建议（三个灰点）：

许多诊断都有一个或多个相关的代码修复，可以应用它们来纠正违反规则的情况。 代码修复以及其他类型的快速操作显示在灯泡图标菜单中。 有关这些代码修复的详细信息，请参阅常见快速操作。

配置严重性级别

可以使用以下任一方法设置规则严重性：

• 配置
• 灯泡菜单
• “错误列表”窗口
• 解决方案资源管理器

“无提示”与“无”严重性

默认已启用的 Silent 严重性规则与已禁用的或 None 严重性规则有所不同：

• 如果为 Silent 严重性规则注册了代码修复，则 Visual Studio 将该代码修复作为灯泡代码重构操作提供，即使隐藏的诊断对用户不可见。 如果将严重性规则禁用为 None，则不提供代码修复。
• 在 EditorConfig 文件中一次性设置多个分析器规则的严重性的条目，可以批量配置 Silent 严重性规则。 None 严重性规则不能通过此方式进行配置。 而是必须通过条目在 EditorConfig 文件中为每个规则 ID 设置严重性进行配置。

在 EditorConfig 文件中设置规则严重性

Visual Studio 2019 版本 16.3 及更高版本中提供了 EditorConfig 文件。

在 EditorConfig 文件中设置规则的严重性优先于在规则集或解决方案资源管理器中设置的任何严重性。 你可以在 EditorConfig 文件中手动配置严重性，或者通过出现在违规情况旁边的灯泡自动配置。

在 EditorConfig 文件中手动配置规则严重性

要配置规则严重性，请执行以下步骤：

1. 在你的项目中添加一个 EditorConfig 文件（如果还没有该文件）。

2. 在相应的文件扩展名下为要配置的每个规则添加一个条目。

   例如，将 C# 文件的 CA1822 的严重性设置为 error 的条目如下所示：

   [*.cs]
   dotnet_diagnostic.CA1822.severity = error
   

3. 可以使用以下语法设置 EditorConfig 文件中每个诊断规则 ID 的规则严重性：

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

4. 对于 IDE 代码样式分析器，还可以使用不同的语法在 EditorConfig 文件中配置它们。

   例如 dotnet_style_qualification_for_field = false:suggestion。 但是，如果使用 dotnet_diagnostic 语法设置严重性，则优先使用该严重性。 有关详细信息，请参阅 EditorConfig 适用的 .NET 语言约定。

在 EditorConfig 文件中一次性设置多个分析器规则的严重性

Visual Studio 2019 版本 16.5 及更高版本中提供了一次性在 EditorConfig 文件中设置多个分析器规则的功能。

可以使用 EditorConfig 文件中的单个条目为特定类别的分析器规则或所有分析器规则设置严重性：

• 为一个分析器规则类别设置规则严重性：

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

• 为所有分析器规则设置规则严重性：

  dotnet_analyzer_diagnostic.severity = <severity>

一次性配置多个分析器规则的条目仅适用于默认已启用的规则。 在分析器包中默认标记为“已禁用”的分析器规则必须通过显式的 dotnet_diagnostic.<rule ID>.severity = <severity> 条目来启用。

如果有多个适用于特定规则 ID 的条目，则适用条目的优先顺序如下：

• 基于 ID 的单个规则的严重性条目优先于一个类别的严重性条目。
• 一个类别的严重性条目优先于所有分析器规则的严重性条目。

考虑以下 EditorConfig 示例，其中 CA1822 属于性能规则：

[*.cs]
dotnet_diagnostic.CA1822.severity = error
dotnet_analyzer_diagnostic.category-performance.severity = warning
dotnet_analyzer_diagnostic.severity = suggestion

在此示例中，所有三个条目都应用于性能规则 CA1822。 但是，按照指定的优先级规则，第一个基于规则 ID 的严重性条目优先于后续条目。 在此示例中，CA1822 的有效严重性为 error。 其余性能规则的严重性为 warning。 不是性能规则的分析器规则的严重性为 suggestion。

从灯泡菜单设置规则严重性

Visual Studio 提供了一种从快速操作灯泡菜单配置规则严重性的方便方法。 执行以下步骤：

1. 发生违规情况后，将鼠标悬停在编辑器中表示违规情况的波浪线上，然后选择“显示潜在修补程序”以打开灯泡菜单。 或者，将光标放在该行上并按 Ctrl+.（句点）。

2. 在灯泡菜单中，将鼠标悬停在严重性级别上以获取更改预览，然后根据以下选项配置严重性：

   • 配置 <规则 ID> 严重性。 设置特定规则的严重性。

   • 为所有<样式>分析器配置严重性。 为特定规则类别中的所有规则设置严重性。

   • 为所有分析器配置严重性。 为所有分析器规则类别设置严重性。

     在以下示例中，选择“禁止显示或配置问题”>“配置 <规则 ID> 严重性。

     

3. 选择其中一个严重性选项。

   

   Visual Studio 会在 EditorConfig 文件中添加一个条目，以将规则配置为请求的严重性级别，如预览框中所示。

   如果项目中还没有 EditorConfig 文件，Visual Studio 将为你创建一个。

从“错误列表”窗口设置规则严重性

Visual Studio 还提供了一种从“错误列表”上下文菜单配置规则严重性的方便方法。 执行以下步骤：

1. 发生冲突后，右键单击“错误列表”中的诊断条目。

2. 从上下文菜单中选择“设置严重性”，然后选择其中一个严重性选项。

   

   Visual Studio 会在 EditorConfig 文件中添加一个条目，以将规则配置为请求的级别。

   如果项目中还没有 EditorConfig 文件，Visual Studio 将为你创建一个。

从解决方案资源管理器设置规则严重性

若要从解决方案资源管理器设置规则严重性，请执行以下步骤：

1. 在“解决方案资源管理器”中，展开“引用”>“分析器”（如果是 .NET Core 项目，则为“依赖项”>“分析器”） 。

2. 展开包含待设置严重性的规则的程序集。

3. 右键单击规则并选择“设置严重性”。 在上下文菜单中，选择其中一个严重性选项。

   Visual Studio 会在 EditorConfig 文件中添加一个条目，以将规则配置为请求的级别。 如果项目使用的是规则集文件而不是 EditorConfig 文件，则会将严重性条目添加到规则集文件中。

   如果项目中还没有 EditorConfig 文件或规则集文件，Visual Studio 会创建一个新的 EditorConfig 文件。

从解决方案资源管理器查看分析器和诊断

可以在“解决方案资源管理器”中自定义分析器诊断。 如果以 NuGet 包的形式安装分析器，则“解决方案资源管理器”中的“引用”（或 .NET Core 项目的“依赖项”节点）下会出现“分析器”节点。 按照以下步骤查看分析器和诊断：

1. 在解决方案资源管理器中，展开项目，展开“引用”或“依赖项”，然后展开“分析器”。 展开其中一个分析器程序集以查看程序集中的诊断。

   每个诊断旁边的图标指示其严重性级别：

   • 圆圈中的 x 表示严重性为错误
   • 三角形中的 ! 表示严重性为警告
   • 实线圆中的 i 表示严重性为建议
   • 虚线圆中的 i 表示严重性为无提示
   • 实线圆中的向下箭头表示严重性为无

   

2. 若要查看诊断属性，包括其描述和默认严重性，请右键单击诊断，然后选择“属性”。 或者，选择诊断，然后按 Alt+Enter。

   此时将出现“属性”窗口。

   

3. 要在“属性”窗口中查看代码样式规则（IDE 前缀）的属性（如默认严重程度），请将 EnforceCodeStyleInBuild 属性设置为 true。

4. 有关诊断的联机文档，请右键单击诊断，然后选择“查看帮助”。

将现有的规则集文件转换为 EditorConfig 文件

在 Visual Studio 2019 版本 16.5 和更高版本中，不建议使用规则集文件，请改为针对用于托管代码的分析器配置使用 EditorConfig 文件。 EditorConfig 文件更加灵活并且允许你配置分析器规则严重性和分析器选项，包括 Visual Studio IDE 代码样式选项。 由于用于分析器规则严重性配置的 Visual Studio 工具现已优化为使用 EditorConfig 文件而不是规则集文件，因此建议转换任何仍使用规则集文件的现有项目。

将现有规则集文件转换为 EditorConfig 文件时，将其保存在存储库的根目录或解决方案文件夹中。 这样做可确保此文件中的严重性设置分别自动应用于整个存储库或解决方案。

可以使用规则集编辑器或命令行，将现有规则集文件转换为 EditorConfig 文件。

注意

.NET Core 和 .NET Standard 项目不支持“解决方案资源管理器”中规则集的菜单命令，例如“打开活动规则集”。 若要为 .NET Core 或 .NET Standard 项目指定非默认规则集，请在项目文件中手动添加 CodeAnalysisRuleSet 属性。 你仍可以在规则集编辑器中配置规则集内的规则。

若要使用规则集编辑器，请执行以下步骤。 如果项目已将特定规则集文件用作其 CodeAnalysisRuleSet 属性值，则可以通过规则集编辑器将其转换为等效的 EditorConfig 文件：

1. 在“解决方案资源管理器”中双击规则集文件。

   规则集文件在规则集编辑器中打开，顶部有一个可单击的信息栏。

   

2. 选择“信息栏”链接以迁移规则集编辑器文件。

3. 从“另存为”对话框中，选择要在其中生成 EditorConfig 文件的目录，然后选择“保存”。

   生成的 EditorConfig 在编辑器中打开。 此外，MSBuild 属性 CodeAnalysisRuleSet 在项目文件中进行了更新，因此它不再引用原始规则集文件。

若要使用命令行，请执行以下步骤：

1. 安装 NuGet 包 Microsoft.CodeAnalysis.RulesetToEditorconfigConverter。

2. 从已安装的包中执行 RulesetToEditorconfigConverter.exe，并将规则集文件和 EditorConfig 文件的路径作为命令行参数。

   例如：

   Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_editorconfig%>]
   

以下示例显示要转换为 EditorConfig 文件的规则集文件：

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="Rules for ConsoleApp" Description="Code analysis rules for ConsoleApp.csproj." ToolsVersion="16.0">
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1001" Action="Warning" />
    <Rule Id="CA1821" Action="Warning" />
    <Rule Id="CA2213" Action="Warning" />
    <Rule Id="CA2231" Action="Warning" />
  </Rules>
</RuleSet>

以下示例显示转换后生成的 EditorConfig 文件：

# NOTE: Requires **VS2019 16.3** or later

# Rules for ConsoleApp
# Description: Code analysis rules for ConsoleApp.csproj.

# Code files
[*.{cs,vb}]

dotnet_diagnostic.CA1001.severity = warning
dotnet_diagnostic.CA1821.severity = warning
dotnet_diagnostic.CA2213.severity = warning
dotnet_diagnostic.CA2231.severity = warning

配置生成的代码

分析器在项目中的源文件上运行并报告其找到的任何违规情况。 但是，这些违规情况不适用于系统生成的文件。 生成的代码文件的示例包括：设计器生成的代码文件、生成系统生成的临时源文件，等等。 对于这些类型的文件，用户无法手动编辑文件，也无需担心任何违规情况的修复。

因此，默认情况下，分析器驱动程序仅将具有特定名称、文件扩展名或自动生成的文件头的文件视为生成的代码文件。 例如，以 .designer.cs 或 .generated.cs 结尾的文件名被视为生成的代码。 但是，这些启发式方法可能无法识别用户源代码中所有自定义生成的代码文件。

在 Visual Studio 2019 版本 16.5 和更高版本中，最终用户可以将特定文件和文件夹配置为在 EditorConfig 文件中生成的代码。

要添加此类配置，请执行以下步骤：

1. 如果你的项目还没有 EditorConfig 文件，请添加一个。

2. 为特定文件和文件夹添加 generated_code = true | false 条目。 例如，若要将名称以 .MyGenerated.cs 结尾的所有文件视为生成的代码，请使用以下条目：

   [*.MyGenerated.cs]
   generated_code = true
   

禁止显示冲突

可以使用各种方法抑制规则冲突。 相关信息，请参阅禁止显示代码分析违规情况。

命令行用法

在命令行生成项目时，如果满足以下条件，则生成输出中将显示规则冲突：

• 分析器随 .NET SDK 一起安装或作为 NuGet 包（而不是作为 .vsix 扩展）安装。

  对于使用 .NET SDK 安装的分析器，可能需要启用分析器。 对于代码样式，也可通过设置 MSBuild 属性在生成时强制执行代码样式。

• 项目的代码中违反了一个或多个规则。

• 代码所违反规则的严重性级别设置为“警告”（在这种情况下，违规不会导致生成失败）或“错误”（在这种情况下，违规会导致生成失败）。

生成输出的详细程度不影响是否显示规则冲突。 即使有“相当级别”的详细程度，规则冲突也会出现在生成输出中。

如果你习惯于使用 FxCopCmd.exe 或通过带 RunCodeAnalysis 标志的 msbuild 从命令行运行旧版分析，你可以改而使用代码分析器执行该操作。

若要在使用 msbuild 生成项目时在命令行中查看分析器冲突，请运行以下命令：

msbuild myproject.csproj /target:rebuild /verbosity:minimal

以下屏幕截图显示了生成包含分析器规则冲突的项目时的命令行生成输出：

依赖项目

在 .NET Core 项目中，如果添加对具有 NuGet 分析器的项目的引用，Visual Studio 会自动将这些分析器添加到依赖项目中。 若要禁用此行为（例如，当依赖项目是单元测试项目时），请通过在所引用项目的 .csproj 或 .vbproj 文件中设置 PrivateAssets 特性，将 NuGet 包标记为“专用”：

<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="5.0.0" PrivateAssets="all" />

相关内容

• Visual Studio 中的代码分析器概述
• 提交代码分析器 bug
• 使用规则集
• 禁止显示代码分析违规情况
• 代码分析的配置选项