源代码分析概述Overview of source code analysis

.NET Compiler Platform (Roslyn) 分析器检查 C# 或 Visual Basic 代码的样式、质量、可维护性、设计及其他问题。.NET Compiler Platform (Roslyn) Analyzers inspect your C# or Visual Basic code for style, quality, maintainability, design, and other issues. 此检查或分析是在设计时在所有打开的文件中完成的。This inspection or analysis is done during design time in all open files.

分析器可以分为以下几组:Analyzers can be divided into the following groups:

  • 代码样式分析器内置于 Visual Studio 中。Code style analyzers are built in to Visual Studio. 对于这些分析器,诊断 ID 或代码的格式为 IDExxxx,如 IDE0067。The diagnostic ID, or code, for these analyzers is of the format IDExxxx, for example, IDE0067. 可以在文本编辑器选项页上或在 EditorConfig 文件中配置首选项。You can configure preferences in the text editor options page or in an EditorConfig file. 从 .NET 5.0 开始,代码样式分析器包含在 .NET SDK 中,并且可以作为生成警告或错误严格地强制实施。Starting in .NET 5.0, code style analyzers are included with the .NET SDK and can be strictly enforced as build warnings or errors. 有关详细信息,请参阅此文For more information, see here.

  • 现在,代码质量分析器包含在 .NET 5 SDK 中并且在默认情况下已启用。Code quality analyzers are now included with the .NET 5 SDK and enabled by default. 对于这些分析器,诊断 ID 或代码的格式为 CAxxxx,如 CA1822。The diagnostic ID, or code, for these analyzers is of the format CAxxxx, for example, CA1822. 有关详细信息,请参阅 .NET 代码质量分析概述For more information, see Overview of .NET code quality analysis.

  • 可以将第三方分析器作为 NuGet 包或 Visual Studio 扩展进行安装。Third party analyzers can be installed as a NuGet package or a Visual Studio extension. 第三方分析器,例如 StyleCopRoslynatorXUnit AnalyzersSonar AnalyzerThird party analyzers, such as StyleCop, Roslynator, XUnit Analyzers, and Sonar Analyzer.

分析器的严重性级别Severity levels of analyzers

每个分析器都具有以下严重性级别之一:Each analyzer has one of the following severity levels:

严重性(解决方案资源管理器)Severity (Solution Explorer) 严重性(EditorConfig 文件)Severity (EditorConfig file) 生成时行为Build-time behavior 编辑器行为Editor behavior
错误Error error 此类冲突在错误列表和命令行生成输出中显示为“错误”,并导致生成失败。Violations appear as Errors in the Error List and in command-line build output, and cause builds to fail. 违规代码用红色波浪下划线表示,并用滚动条中的红色小框标记。Offending code is underlined with a red squiggle and marked by a small red box in the scroll bar.
警告Warning warning 此类冲突在错误列表和命令行生成输出中显示为“警告”,但不会导致生成失败。Violations appear as Warnings in the Error List and in command-line build output, but do not cause builds to fail. 违规代码用绿色波浪下划线表示,并用滚动条中的绿色小框标记。Offending code is underlined with a green squiggle and marked by a small green box in the scroll bar.
信息Info suggestion 此类冲突在错误列表中显示为“消息”,而不会在命令行生成输出中显示。Violations appear as Messages in the Error List, and not at all in command-line build output. 违规代码用灰色波浪下划线表示,并用滚动条中的灰色小框标记。Offending code is underlined with a gray squiggle and marked by a small gray box in the scroll bar.
HiddenHidden silent 对用户不可见。Non-visible to user. 对用户不可见。Non-visible to user. 但是,诊断会报告给 IDE 诊断引擎。The diagnostic is reported to the IDE diagnostic engine, however.
None none 完全禁止显示。Suppressed completely. 完全禁止显示。Suppressed completely.
默认Default default 对应于规则的默认严重性。Corresponds to the default severity of the rule. 若要确定规则的默认值,请查看“属性”窗口。To determine what the default value for a rule is, look in the Properties window. 对应于规则的默认严重性。Corresponds to the default severity of the rule.

如果分析器发现规则冲突,将在代码编辑器(违规代码下方有波浪线)和“错误列表”窗口中报告**。If rule violations are found by an analyzer, they're reported in the code editor (as a squiggle under the offending code) and in the Error List window.

“错误列表”窗口中的分析器冲突

错误列表中报告的分析器冲突与规则的严重性级别设置相匹配。The analyzer violations reported in the error list match the severity level setting of the rule. 分析器冲突也会在代码编辑器中以波浪线的形式显示在违规代码下。Analyzer violations also show up in the code editor as squiggles under the offending code. 下图显示了三个冲突—一个错误(红色波浪线)、一个警告(绿色波浪线)和一个建议(三个灰点):The following image shows three violations—one error (red squiggle), one warning (green squiggle), and one suggestion (three grey dots):

Visual Studio 中代码编辑器中的波浪线

许多分析器规则或诊断都有一个或多个相关的代码修复程序,可以应用它们来纠正规则冲突。Many analyzer rules, or diagnostics, have one or more associated code fixes that you can apply to correct the rule violation. 代码修复以及其他类型的快速操作显示在灯泡图标菜单中。Code fixes are shown in the light bulb icon menu along with other types of Quick Actions. 有关这些代码修复的信息,请参阅常见快速操作For information about these code fixes, see Common Quick Actions.

分析器冲突和快速操作代码修复

配置分析器严重性级别Configure analyzer severity levels

可以在 EditorConfig 文件中或从灯泡菜单中配置分析器规则的严重性或诊断。You can configure the severity of analyzer rules, or diagnostics, in an EditorConfig file or from the light bulb menu.

分析器还可以配置为在生成时检查代码,并在键入时保持运行状态。Analyzers can also be configured to inspect code at build time and live as you type. 你可配置实时代码分析的范围,以仅对当前文档执行、对所有打开的文档执行或对整个解决方案执行。You can configure the scope of live code analysis to execute for the current document only, all open documents, or the entire solution. 请参阅如何:配置实时代码分析范围See How to: Configure the scope of live code analysis.

提示

仅当分析器作为 NuGet 包安装时,才会显示来自代码分析器的生成时错误和警告。Build-time errors and warnings from code analyzers are shown only if the analyzers are installed as a NuGet package. 内置分析器(例如 IDE0067 和 IDE0068)不会在生成期间运行。The built-in analyzers (for example, IDE0067 and IDE0068) never run during build.

NuGet 包与 VSIX 扩展NuGet package versus VSIX extension

可以通过 NuGet 包为每个项目安装第三方分析器。Third party analyzers can be installed per-project via a NuGet package. 有些分析器还可用作 Visual Studio 扩展,在这种情况下,它们适用于在 Visual Studio 中打开的任何解决方案。Some are also available as a Visual Studio extension, in which case they apply to any solution you open in Visual Studio. 这两种安装分析器方法之间存在一些关键行为差异。There are some key behavior differences between these two methods of installing analyzers.

范围Scope

如果将分析器安装为 Visual Studio 扩展,则它们将在解决方案级别应用于 Visual Studio 的所有实例。If you install analyzers as a Visual Studio extension, they apply at the solution level and to all instances of Visual Studio. 如果将分析器安装为 NuGet 包(这是首选方法),它们仅适用于安装了 NuGet 软件包的项目。If you install the analyzers as a NuGet package, which is the preferred method, they apply only to the project where the NuGet package was installed. 在团队环境中,作为 NuGet 包安装的分析器适用于处理该项目的所有开发人员**。In team environments, analyzers installed as NuGet packages are in scope for all developers that work on that project.

生成错误Build errors

要在生成时强制执行规则,包括通过命令行执行或作为持续集成 (CI) 生成的一部分来执行,可以从以下选项中进行选择:To have rules enforced at build time, including through the command line or as part of a continuous integration (CI) build you can choose from one of the following options:

  • 创建 .NET 5.0 项目,其中默认在 .NET SDK 中包含分析器。Create a .NET 5.0 project which includes analyzers by default in the .NET SDK. 代码分析功能针对面向 .NET 5.0 或更高版本的项目默认启用。Code analysis is enabled, by default, for projects that target .NET 5.0 or later. 可通过将 EnableNETAnalyzers 属性设置为 true,在面向 .NET 早期版本的项目上启用代码分析。You can enable code analysis on projects that target earlier .NET versions by setting the EnableNETAnalyzers property to true.

  • 将分析器安装为 NuGet 包。Install analyzers as a NuGet package. 如果将分析器作为扩展安装,则分析器警告和错误不会显示在生成报告中。Analyzer warnings and errors don't show up in the build report if you install the analyzers as an extension.

以下图像显示了生成包含分析器规则冲突的项目时的命令行生成输出:The following image shows the command-line build output from building a project that contains an analyzer rule violation:

带规则冲突的 MSBuild 输出

规则严重性Rule severity

无法配置作为 Visual Studio 扩展安装的分析器的规则严重性。You cannot configure the severity of rules from analyzers that were installed as a Visual Studio extension. 若要配置规则严重性,则应将分析器安装为 NuGet 包。To configure rule severity, install the analyzers as a NuGet package.

后续步骤Next steps

请参阅See also