关于使用 Roslyn 分析器在 Visual Studio 中分析 .NET 源代码

.NET Compiler Platform (Roslyn) 分析器检查 C# 或 Visual Basic 代码的样式、质量、可维护性、设计及其他问题。 此检查或分析是在设计期间在所有打开的文件中发生的。

分析器分为以下几组:

分析器的严重性级别

每个分析器都具有以下严重性级别之一:

严重性(解决方案资源管理器) 严重性(EditorConfig 文件) 生成时行为 编辑器行为
错误 error 此类冲突在错误列表和命令行生成输出中显示为“错误”,并导致生成失败。 违规代码用红色波浪下划线表示,并用滚动条中的红色小框标记。
警告 warning 此类冲突在错误列表和命令行生成输出中显示为“警告”,但不会导致生成失败。 违规代码用绿色波浪下划线表示,并用滚动条中的绿色小框标记。
信息 suggestion 此类冲突在错误列表中显示为“消息”,而不会在命令行生成输出中显示。 违规代码用灰色波浪下划线表示,并用滚动条中的灰色小框标记。
Hidden silent 对用户不可见。 对用户不可见。 但是,诊断会报告给 IDE 诊断引擎。
none 完全禁止显示。 完全禁止显示。
默认 default 对应于规则的默认严重性。 若要确定规则的默认值,请查看“属性”窗口 对应于规则的默认严重性。

如果分析器发现规则冲突,将在代码编辑器(违规代码下方有波浪线)和“错误列表”窗口中报告。

Analyzer violation in Error List window

错误列表中报告的分析器冲突与规则的严重性级别设置相匹配。 分析器冲突也会在代码编辑器中以波浪线的形式显示在违规代码下。 下图显示了三个冲突:一个错误(红色波浪线)、一个警告(绿色波浪线)和一个建议(三个灰点):

Squiggles in the code editor in Visual Studio

许多分析器规则或诊断都有一个或多个相关的代码修复程序,可以应用它们来纠正规则冲突。 代码修复以及其他类型的快速操作显示在灯泡图标菜单中。 有关这些代码修复的信息,请参阅常见快速操作

Analyzer violation and Quick Action code fix

配置分析器严重性级别

可以在 EditorConfig 文件中或从灯泡菜单中配置分析器规则的严重性或诊断。

分析器还可以配置为在生成时检查代码,并在键入时保持运行状态。 你可配置实时代码分析的范围,以仅对当前文档执行、对所有打开的文档执行或对整个解决方案执行。 请参阅如何:配置实时代码分析范围

提示

仅当分析器作为 NuGet 包安装时,才会显示来自代码分析器的生成时错误和警告。 内置分析器(例如 IDE0067 和 IDE0068)不会在生成期间运行。

NuGet 包与 VSIX 扩展

可以通过 NuGet 包为每个项目安装外部分析器。 有些分析器还可用作 Visual Studio 扩展,在这种情况下,它们适用于在 Visual Studio 中打开的任何解决方案。 这两种安装分析器方法之间存在一些关键行为差异。

范围

如果将分析器安装为 Visual Studio 扩展,则它们将在解决方案级别应用于 Visual Studio 的所有实例。 如果将分析器安装为 NuGet 包(这是首选方法),它们仅适用于安装了 NuGet 软件包的项目。 在团队环境中,作为 NuGet 包安装的分析器适用于处理该项目的所有开发人员

注意

第一方分析器也随附在 .NET SDK 中。 建议从 .NET SDK 启用这些分析器,而不是安装 Microsoft.CodeAnalysis.NetAnalyzersNuGet 包(如果可能)。 从 .NET SDK 启用分析器可以确保在更新 SDK 后,立即自动获取分析器 bug 修复和新分析器。 有关更多详细信息,请参阅启用或安装第一方 .NET 分析器

生成错误

要在生成时强制执行规则,包括通过命令行执行或作为持续集成 (CI) 生成的一部分来执行,可以选择以下选项之一:

  • 创建 .NET 5.0 或更高版本项目,其中默认在 .NET SDK 中包含分析器。 代码分析功能针对面向 .NET 5.0 或更高版本的项目默认启用。 可通过将 EnableNETAnalyzers 属性设置为 true,在面向 .NET 早期版本的项目上启用代码分析。

  • 将分析器安装为 NuGet 包。 如果将分析器作为扩展安装,则分析器警告和错误不会显示在生成报告中。

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

MSBuild output with rule violation

规则严重性

无法配置作为 Visual Studio 扩展安装的分析器的规则严重性。 若要配置规则严重性,则应将分析器安装为 NuGet 包。

后续步骤