通过

代码样式命名规则

  • 项目

在 .editorconfig 文件中，可以为 .NET 编程语言代码元素（如类、属性和方法）定义命名约定，以及编译器或 IDE 应如何强制执行这些约定。 例如，可以指定，应将非大写的公共成员视为编译器错误，或者在专用字段未以 _ 开头时应发出生成警告。

具体而言，可以定义一个命名规则，该规则由三个部分组成：

  • 规则适用的符号组，例如，公共成员或私有字段。
  • 要与规则关联的命名样式，例如，名称必须采用大写形式或以下划线开头。
  • 当符号组中包含的代码元素未遵循命名样式时消息的严重级别。

一般语法

若要定义上述任何实体（命名规则、符号组或命名样式），请使用以下语法设置一个或多个属性：

<kind>.<entityName>.<propertyName> = <propertyValue>

给定 kind 和 entityName 的所有属性设置构成该特定实体定义。

每个属性只能设置一次，但某些设置允许多个值（以逗号分隔）。

属性的顺序并不重要。

<kind> 值

<kind> 指定所定义的实体种类（命名规则、符号组或命名样式）并且必须是以下值之一：

设置属性 使用 <kind> 值 示例
命名规则 dotnet_naming_rule dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion
符号组 dotnet_naming_symbols dotnet_naming_symbols.interface.applicable_kinds = interface
命名样式 dotnet_naming_style dotnet_naming_style.pascal_case.capitalization = pascal_case

<entityName>

<entityName> 是所选的描述性名称，用于将多个属性设置关联到一个定义中。 例如，以下属性生成两个符号组定义：interface 和 types，并为每一个定义都设置了两个属性。

dotnet_naming_symbols.interface.applicable_kinds = interface
dotnet_naming_symbols.interface.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected

dotnet_naming_symbols.types.applicable_kinds = class, struct, interface, enum, delegate
dotnet_naming_symbols.types.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected

<propertyName> 和 <propertyValue>

每种实体（命名规则、符号组或命名样式）都有各自支持的属性，如以下各节所述。

符号组属性

你可以为符号组设置以下属性，以限制组中包含的符号。 若要为单个属性指定多个值，请用逗号分隔这些值。

属性 说明 允许的值 必选
applicable_kinds 组中符号的种类 1 *（使用此值可指定所有符号）
namespace
class
struct
interface
enum
property
method
field
event
delegate
parameter
type_parameter
local
local_function		 是
applicable_accessibilities 组中符号的可访问性级别 *（使用此值可指定所有可访问性级别）
public
internal 或 friend
private
protected
protected_internal 或 protected_friend
private_protected
local（用于方法内定义的符号）		 是
required_modifiers 仅将符号与所有指定的修饰符 2 进行匹配 abstract 或 must_inherit
async
const
readonly
static 或 shared 3		 否

注意：

  1. 目前 applicable_kinds 不支持元组成员。
  2. 符号组与 required_modifiers 属性中的所有修饰符匹配。 如果你忽略此属性，则无需与任何特定修饰符进行匹配。 这意味着符号的修饰符不会影响是否应用此规则。
  3. 如果组的 required_modifiers 属性包含 static 或 shared，那么组还将包括 const 符号，因为它们是隐式 static/Shared。 不过，如果你不希望将 static 命名规则应用于 const 符号，可以使用 const 符号组创建新的命名规则。 根据规则顺序，新规则的优先级更高。
  4. class 包括 C# 记录。

命名样式属性

命名样式定义要通过规则强制执行的约定。 例如：

  • 采用 PascalCase 大写形式
  • 以 m_ 开头
  • 以 _g 结尾
  • 用 __ 分隔单词

可以为命名样式设置以下属性：

属性 说明 允许的值 必选
capitalization 符号内的单词的大写样式 pascal_case
camel_case
first_word_upper
all_upper
all_lower		 是1
required_prefix 必须以这些字符开头 否
required_suffix 必须以这些字符结尾 否
word_separator 符号内的单词必须用此字符分隔 否

注意：

  1. 必须在命名样式中指定大写样式，否则会忽略命名样式。

命名规则属性

要使规则生效，必须具有所有命名规则属性。

属性 说明
symbols 别处定义的符号组的名称；命名规则将应用于此组中的符号
style 应与此规则关联的命名样式的名称；样式在别处定义
severity 设置用于强制执行命名规则的严重性。 将关联的值设置为任一可用的严重性级别.1

注意：

  1. 只有 Visual Studio 之类的开发 IDE 会遵循命名规则中的严重性规范。 C# 或 VB 编译器无法解读此设置，因此在生成期间不会遵循它。 若要在生成时强制执行命名样式规则，应改为通过使用代码规则严重性配置来设置严重性。 有关详细信息，请参阅此 GitHub 问题。

规则顺序

EditorConfig 文件中定义命名规则的顺序并不重要。 命名规则根据规则本身的定义自动排序。 有关辅助功能、修饰符和符号的更明确的规则优先于不太明确的规则。 如果规则之间存在重叠，或者规则排序会导致问题，则可以将这两个规则的交集分解为优先于从中派生的更广泛规则。 有关示例，请参阅示例：重叠命名策略和示例：const 修饰符包括 static 和 readonly。

EditorConfig 语言服务扩展可以分析 EditorConfig 文件，如果文件中的规则顺序与编译器在运行时使用的规则不同，该扩展还会进行报告。

注意

如果你使用的是 Visual Studio 2019 之前的 Visual Studio 版本，则 EditorConfig 文件中的命名规则应按照从特定性最强到特定性最弱的顺序排序。 遇到的第一个可应用规则是唯一应用的规则。 但是，如果有多个具有相同名称的规则属性 ，则最近找到的具有该名称的属性具有优先权。 有关详细信息，请参阅文件层次结构和优先级。

示例：重叠命名策略

请考虑以下两个命名规则：

  1. 公共方法是 PascalCase。
  2. 异步方法以 "Async" 结尾。

对于 public async 方法，哪个规则优先并不明显。 可以为 public async 方法创建新规则并确切地指定命名。

示例：const 修饰符包括 static 和 readonly

请考虑以下两个命名规则：

  1. 常量字段为 PascalCase。
  2. 非公共 static 字段为 s_camelCase。

规则 2 更明确且优先级最高，因此所有非公共常量字段都是 s_camelCase。 若要解决此问题，可以定义交集规则：非公共常量字段为 PascalCase。

默认命名样式

如果不指定任何自定义命名规则，系统将使用下列默认样式：

  • 对于具有任意辅助功能的类、结构、枚举、属性、方法以及事件，默认的命名样式为帕斯卡拼写法。

  • 对于具有任意辅助功能的接口，默认的命名样式为帕斯卡拼写法并必须附加 l 前缀。

代码规则 ID：IDE1006 (Naming rule violation)

所有命名选项都具有规则 ID IDE1006 和标题 Naming rule violation。 可以使用以下语法在 EditorConfig 文件中以全局方式配置命名违规行为的严重性：

dotnet_diagnostic.IDE1006.severity = <severity value>

严重性值必须是 warning 或 error 才能在生成时强制执行。 要了解所有可能的严重性值，请参阅严重性级别。

示例：公共成员大写

以下 .editorconfig 文件包含命名约定，该约定指定公共属性、方法、字段、事件和标记为 readonly 的委托必须采用大写形式。 此命名约定指定多种要应用规则的符号，使用逗号分隔值。

[*.{cs,vb}]

# Defining the 'public_symbols' symbol group
dotnet_naming_symbols.public_symbols.applicable_kinds           = property,method,field,event,delegate
dotnet_naming_symbols.public_symbols.applicable_accessibilities = public
dotnet_naming_symbols.public_symbols.required_modifiers         = readonly

# Defining the 'first_word_upper_case_style' naming style
dotnet_naming_style.first_word_upper_case_style.capitalization = first_word_upper

# Defining the 'public_members_must_be_capitalized' naming rule, by setting the
# symbol group to the 'public symbols' symbol group,
dotnet_naming_rule.public_members_must_be_capitalized.symbols  = public_symbols
# setting the naming style to the 'first_word_upper_case_style' naming style,
dotnet_naming_rule.public_members_must_be_capitalized.style    = first_word_upper_case_style
# and setting the severity.
dotnet_naming_rule.public_members_must_be_capitalized.severity = suggestion

示例：带下划线的专用实例字段

此 .editorconfig 文件代码片段强制要求专用实例字段应以 _ 开头；如果不遵循该约定，IDE 会将其视为编译器错误。 将忽略专用静态字段。

因为你只能根据其具有的标识符（例如，static 或 readonly）定义符号组，而不是根据它没有的标识符（例如，一个实例字段，因为它没有 static），所以需要定义两条命名规则：

  1. 所有专用字段（无论是否 static）都应当应用 underscored 命名样式作为编译器 error。
  2. 具有 static 的专用字段应当应用 underscored 命名样式，其严重级别为 none；换句话说，忽略此情况。
[*.{cs,vb}]

# Define the 'private_fields' symbol group:
dotnet_naming_symbols.private_fields.applicable_kinds = field
dotnet_naming_symbols.private_fields.applicable_accessibilities = private

# Define the 'private_static_fields' symbol group
dotnet_naming_symbols.private_static_fields.applicable_kinds = field
dotnet_naming_symbols.private_static_fields.applicable_accessibilities = private
dotnet_naming_symbols.private_static_fields.required_modifiers = static

# Define the 'underscored' naming style
dotnet_naming_style.underscored.capitalization = pascal_case
dotnet_naming_style.underscored.required_prefix = _

# Define the 'private_fields_underscored' naming rule
dotnet_naming_rule.private_fields_underscored.symbols = private_fields
dotnet_naming_rule.private_fields_underscored.style = underscored
dotnet_naming_rule.private_fields_underscored.severity = error

# Define the 'private_static_fields_none' naming rule
dotnet_naming_rule.private_static_fields_none.symbols = private_static_fields
dotnet_naming_rule.private_static_fields_none.style = underscored
dotnet_naming_rule.private_static_fields_none.severity = none

此示例还演示了可以重复使用实体定义。 private_fields_underscored 和 private_static_fields_none 命名规则都使用 underscored 命名样式。

请参阅