自定义 Roslyn 分析器规则

每个 Roslyn 分析器规则或 诊断都有一个默认的严重性和抑制状态，你可以针对项目进行自定义。 本文介绍如何设置分析器严重性并抑制分析器违规。

严重性级别

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

查看规则冲突

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

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

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

许多诊断具有一个或多个关联的 代码修复 ，可用于更正规则冲突。 代码修复与其他类型的快速操作一起显示在灯泡图标菜单中。 有关代码修复的详细信息，请参阅 常见快速操作。

配置严重性级别

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

静默与无严重性

Silent 默认情况下启用的严重性规则不同于禁用或 None 严重性规则：

• 如果为严重性规则注册 Silent 了代码修复，则 Visual Studio 会以灯泡代码重构作的形式提供代码修复，即使隐藏的诊断对用户不可见也是如此。 如果禁用了严重性规则 None，则不会提供代码修复。
• 在 EditorConfig 文件中一次性设置多个分析器规则严重性的条目可以批量配置Silent严重性规则。 None 无法以这种方式配置严重性规则。 相反，必须通过在 EditorConfig 文件中为每个规则 ID 设置严重性来配置它们。

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

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

在 EditorConfig 文件中设置规则的严重性优先于规则集或解决方案资源管理器中设置的任何严重性。 可以在 EditorConfig 文件中 手动 配置严重性，也可以通过冲突旁边显示的灯泡 自动 配置严重性。

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

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

1. 如果还没有 EditorConfig 文件，请将 EditorConfig 文件添加到项目。

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

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

   [*.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 的语言约定。

在 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> 严重性”。

     

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

     

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

   

   

   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 文件。

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

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

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

   

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

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

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

   可以从项目中删除原始规则集文件。

   注释

   在 .NET Framework 项目中，无法迁移或删除项目的默认规则集文件。

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

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 或通过带有特定标志的 msbuild 运行旧版分析时，可以改用代码分析器来执行。

若要在使用 msbuild 生成项目时查看命令行界面的分析器问题，请运行类似于以下命令：

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

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

依赖项目

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

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

相关内容

• Visual Studio 中的代码分析器概述
• 提交代码分析器问题
• 使用规则集
• 抑制代码分析违规
• 代码分析的配置选项