代码分析规则的配置文件

项目
06/10/2024

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

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

还可以使用全局 AnalyzerConfig 文件配置分析器选项。这些文件用于提供适用于项目中所有源文件的选项，不考虑其文件名和文件路径。

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

Format

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，但为了清楚起见，建议使用它。

条件包含

可以使用全局配置文件在不同的环境中禁用或启用某些代码分析规则。例如，你可能想要禁用单元测试项目的某些代码分析规则。为此，在配置文件中将适用规则的严重性设置为 none，例如：

# CA1861: Prefer 'static readonly' fields over constant array arguments
dotnet_diagnostic.CA1861.severity = none

然后，可以根据特定于生成的条件自定义生成，使其仅在测试项目中包含配置文件。例如：

<ItemGroup Condition="'$(IsShipping)' == 'false'">
  <!-- Include CodeAnalysis.test.globalconfig to override (relax) some rules from the primary configuration. -->
  <GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.test.globalconfig" />
</ItemGroup>

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 设计问题

通过