代码分析规则的配置文件

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

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

提示

也可以在项目文件中设置代码分析配置属性。 这些属性在批量级别配置代码分析,完全将其打开或关闭到类别级别配置。 有关详细信息,请参阅 EnableNETAnalyzersAnalysisLevelAnalysisLevel<类别>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 版本 16.8 和更高版本中受支持)开始,还可配置包含全局 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,但为了清楚起见,建议使用它。

示例

下面是一个示例全局 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 文件

  • 有关具有不同键的相关严重性选项的优先级规则的信息(例如,为单个规则和为规则所属的类别指定不同的严重性),请参阅代码分析的配置选项

另请参阅