代码分析规则的配置文件

项目
10/09/2023

代码分析规则具有多种配置选项。可以在下列任一分析器配置文件中将这些选项指定为键值对：

EditorConfig 文件：基于文件或基于文件夹的配置选项。
全局 AnalyzerConfig 文件：项目级别配置选项。当某些项目文件位于项目文件夹外时，它非常有用。

提示

也可以在项目文件中设置代码分析配置属性。这些属性在批量级别配置代码分析，完全将其打开或关闭到类别级别配置。有关详细信息，请参阅 EnableNETAnalyzers、AnalysisLevel、AnalysisLevel<类别> 和 AnalysisMode。

EditorConfig

EditorConfig 文件用于提供适用于特定资源文件或文件夹的选项。选项位于节标头下，用于标识适用的文件和文件夹。为要配置的每个规则添加一个条目，并将其放置在相应的文件扩展名节下，例如 [*.cs]。

[*.cs]
<option_name> = <option_value>

在上面的示例中，[*.cs] 是一个 editorconfig 节标头，用于选择当前文件夹（包括子文件夹）中带有 .cs 文件扩展名的所有 C# 文件。接下来 <option_name> = <option_value> 这一条目是一个分析器选项，将应用于所有 C# 文件。

可将文件放在相应的目录中，将 EditorConfig 文件约定应用于文件夹、项目或整个存储库。可在生成时执行分析时以及在 Visual Studio 中编辑代码时应用这些选项。

注意

EditorConfig 选项仅应用于项目或目录中的源文件。作为 AdditionalFiles 包含在项目中的文件不被视为源文件，EditorConfig 选项不会应用于这些文件。若要将规则选项应用于非源文件，请在全局配置文件中指定该选项。

如果有一个现有的 .editorconfig 文件可用于编辑器设置（如缩进大小或是否剪裁尾随空格），可将代码分析配置选项放在同一文件中。

提示

Visual Studio 提供 .editorconfig 项模板，通过该模板可轻松地将其中一个文件添加到项目中。有关详细信息，请参阅将 EditorConfig 文件添加到项目。

示例

下面是一个示例 EditorConfig 文件，用于配置选项和规则严重性：

# Remove the line below if you want to inherit .editorconfig settings from higher directories
root = true

# C# files
[*.cs]

#### Core EditorConfig Options ####

# Indentation and spacing
indent_size = 4
indent_style = space
tab_width = 4

#### .NET Coding Conventions ####

# this. and Me. preferences
dotnet_style_qualification_for_method = true

#### Diagnostic configuration ####

# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning

全局 AnalyzerConfig

从 .NET 5 SDK（它在 Visual Studio 2019 和更高版本中受支持）开始，还可配置包含全局 AnalyzerConfig 文件的分析器选项。这些文件用于提供适用于项目中所有源文件的选项，不考虑其文件名和文件路径。

与 EditorConfig 文件不同，全局配置文件不能用于为 IDE 配置编辑器样式设置，如缩进大小或是否剪裁尾随空格。而是专用于指定项目级别分析器配置选项。

格式

EditorConfig 文件必须包含节标头（如 [*.cs]），以标识适用的文件和文件夹，但全局 AnalyzerConfig 文件没有节标头。相反，它们需要 is_global = true 格式的顶级条目，以便与常规 EditorConfig 文件区分开来。这表示文件中的所有选项都适用于整个项目。例如：

is_global = true
<option_name> = <option_value>

命名

EditorConfig 文件必须命名为 .editorconfig，而全局配置文件不需要有特定的名称或文件扩展名。但是，如果将这些文件命名为 .globalconfig，它们会隐式应用于当前文件夹（包括子文件夹）中的所有 C# 和 Visual Basic 项目。否则，必须将 GlobalAnalyzerConfigFiles 项显式添加到 MSBuild 项目文件中：

<ItemGroup>
  <GlobalAnalyzerConfigFiles Include="<path_to_global_analyzer_config>" />
</ItemGroup>

考虑以下命名建议：

最终用户应将其全局配置文件命名为 .globalconfig。
NuGet 包创建者应将其全局配置文件命名为 <%Package_Name%>.globalconfig。
MSBuild 生成工具的全局配置文件应命名为 <%Target_Name%>_Generated.globalconfig 或类似的名称。

注意

将文件命名为 .globalconfig 时，不需要顶级条目 is_global = true，但为了清楚起见，建议使用它。

NuGet 包中的分发

可以使用 NuGet 包分发全局 AnalyzerConfig 文件。要实现此操作，可将 .props 文件添加到 NuGet 包中。在 .props 文件中的 Project 节点下添加 GlobalAnalyzerConfigFiles 项：

<Project>
  <ItemGroup>
    <GlobalAnalyzerConfigFiles Include="Relative/Path/to/PackageName.globalconfig" />
  </ItemGroup>
</Project>

示例

下面是一个示例全局 AnalyzerConfig 文件，用于在项目级别配置选项和规则严重性：

# Top level entry required to mark this as a global AnalyzerConfig file
is_global = true

# NOTE: No section headers for configuration entries

#### .NET Coding Conventions ####

# this. and Me. preferences
dotnet_style_qualification_for_method = true:warning

#### Diagnostic configuration ####

# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning

优先级

EditorConfig 文件和全局 AnalyzerConfig 文件都为每个选项指定键值对。如果有多个条目具有相同键但值不同，则会发生冲突。以下优先规则用于解决冲突。

冲突条目位置	优先规则
在相同配置文件中	文件中后出现的条目优先。这适用于在单个 EditorConfig 文件中和单个全局 AnalyzerConfig 文件中的冲突条目。
在两个 EditorConfig 文件中	EditorConfig 文件位于文件系统更深层的条目（因此文件路径较长）优先。
在两个全局 AnalyzerConfig 文件中	.NET 5：系统会报告编译器警告并忽略这两个条目。 .NET 6 及更高版本：具有更高 `global_level` 值的文件中的条目优先。如果 `global_level` 未明确定义并且文件名为 .globalconfig，则 `global_level` 值默认为 `100`；对于所有其他全局 AnalyzerConfig 文件，`global_level` 默认为 `0`。如果具有冲突条目的配置文件的 `global_level` 值相等，则系统会报告编译器警告并忽略这两个条目。
在 EditorConfig 文件和全局 AnalyzerConfig 文件中	EditorConfig 文件中的条目优先。

严重性选项

严重性配置选项适用于下列其他优先规则：

在命令行上作为编译器选项（-nowarn 或 -warnaserror）指定的严重性选项始终会重写 EditorConfig 和全局 AnalyzerConfig 文件中指定的严重性配置选项。
规则集文件和 EditorConfig 或全局 AnalyzerConfig 文件中的严重性冲突条目的优先规则未定义。

规则集文件已弃用，改用 EditorConfig 和全局 AnalyzerConfig 文件。建议将规则集文件转换为等效的 EditorConfig 文件。
有关具有不同键的相关严重性选项的优先级规则的信息（例如，为单个规则和为规则所属的类别指定不同的严重性），请参阅代码分析的配置选项。

另请参阅

EditorConfig 与全局 AnalyzerConfig 设计问题