Code-style naming rules
In your .editorconfig file, you can define naming conventions for your .NET programming language code elements—such as classes, properties, and methods—and how the compiler or IDE should enforce those conventions. For example, you could specify that a public member that isn't capitalized should be treated as a compiler error, or that if a private field doesn't begin with an _
, a build warning should be issued.
Specifically, you can define a naming rule, which consists of three parts:
- The symbol group that the rule applies to, for example, public members or private fields.
- The naming style to associate with the rule, for example, that the name must be capitalized or start with an underscore.
- The severity level of the message when code elements included in the symbol group don't follow the naming style.
To define any of the above entities—a naming rule, symbol group, or naming style—set one or more properties using the following syntax:
<kind>.<entityName>.<propertyName> = <propertyValue>
All the property settings for a given kind
and entityName
make up that specific entity definition.
Each property should only be set once, but some settings allow multiple, comma-separated values.
The order of the properties is not important.
<kind> specifies which kind of entity is being defined—naming rule, symbol group, or naming style—and must be one of the following:
To set a property for | Use the <kind> value | Example |
---|---|---|
Naming rule | dotnet_naming_rule |
dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion |
Symbol group | dotnet_naming_symbols |
dotnet_naming_symbols.interface.applicable_kinds = interface |
Naming style | dotnet_naming_style |
dotnet_naming_style.pascal_case.capitalization = pascal_case |
<entityName> is a descriptive name you choose that associates multiple property settings into a single definition. For example, the following properties produce two symbol group definitions, interface
and types
, each of which has two properties set on it.
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
Each kind of entity—naming rule, symbol group, or naming style—has its own supported properties, as described in the following sections.
You can set the following properties for symbol groups, to limit which symbols are included in the group. To specify multiple values for a single property, separate the values with a comma.
Property | Description | Allowed values | Required |
---|---|---|---|
applicable_kinds |
Kinds of symbols in the group 1 | * (use this value to specify all symbols)namespace class struct interface enum property method field event delegate parameter type_parameter local local_function |
Yes |
applicable_accessibilities |
Accessibility levels of the symbols in the group | * (use this value to specify all accessibility levels)public internal or friend private protected protected_internal or protected_friend private_protected local (for symbols defined within a method) |
Yes |
required_modifiers |
Only match symbols with all the specified modifiers 2 | abstract or must_inherit async const readonly static or shared 3 |
No |
Notes:
- Tuple members aren't currently supported in
applicable_kinds
. - The symbol group matches all the modifiers in the
required_modifiers
property. If you omit this property, no specific modifiers are required for a match. This means a symbol's modifiers have no effect on whether or not this rule is applied. - If your group has
static
orshared
in therequired_modifiers
property, the group will also includeconst
symbols because they are implicitlystatic
/Shared
. However, if you don't want thestatic
naming rule to apply toconst
symbols, you can create a new naming rule with a symbol group ofconst
. The new rule will take precedence according to the rule order. class
includes C# records.
A naming style defines the conventions you want to enforce with the rule. For example:
- Capitalize with
PascalCase
- Starts with
m_
- Ends with
_g
- Separate words with
__
You can set the following properties for a naming style:
Property | Description | Allowed values | Required |
---|---|---|---|
capitalization |
Capitalization style for words within the symbol | pascal_case camel_case first_word_upper all_upper all_lower |
Yes1 |
required_prefix |
Must begin with these characters | No | |
required_suffix |
Must end with these characters | No | |
word_separator |
Words within the symbol need to be separated with this character | No |
Notes:
- You must specify a capitalization style as part of your naming style, otherwise your naming style might be ignored.
All naming rule properties are required for a rule to take effect.
Property | Description |
---|---|
symbols |
The name of a symbol group defined elsewhere; the naming rule will be applied to the symbols in this group |
style |
The name of the naming style which should be associated with this rule; the style is defined elsewhere |
severity |
Sets the severity with which to enforce the naming rule. Set the associated value to one of the available severity levels.1 |
Notes:
- Severity specification within a naming rule is only respected inside development IDEs, such as Visual Studio. This setting is not understood by the C# or VB compilers, hence not respected during build. To enforce naming style rules on build, you should instead set the severity by using code rule severity configuration. For more information, see this GitHub issue.
The order in which naming rules are defined in an EditorConfig file doesn't matter. The naming rules are automatically ordered according to the definitions of the rules themselves. More specific rules regarding accessibilities, modifiers, and symbols take precedence over less specific rules. If there's overlap between rules or if the rule ordering causes problems, you can break out the intersection of the two rules into a new rule that takes precedence over the broader rules from which it was derived. For examples, see Example: Overlapping naming strategies and Example: const
modifier includes static
and readonly
.
The EditorConfig Language Service extension can analyze an EditorConfig file and report cases where the rule ordering in the file is different to what the compiler will use at run time.
Note
If you're using a version of Visual Studio earlier than Visual Studio 2019, naming rules should be ordered from most-specific to least-specific in the EditorConfig file. The first rule encountered that can be applied is the only rule that is applied. However, if there are multiple rule properties with the same name, the most recently found property with that name takes precedence. For more information, see File hierarchy and precedence.
Consider the following two naming rules:
- Public methods are PascalCase.
- Asynchronous methods end with
"Async"
.
For public async
methods, it's not obvious which rule takes precedence. You can create a new rule for public async
methods and specify the naming exactly.
Consider the following two naming rules:
- Constant fields are PascalCase.
- Non-public
static
fields are s_camelCase.
Rule 2 is more specific and takes precedence, so all non-public constant fields are s_camelCase. To resolve the issue, you can define an intersection rule: non-public constant fields are PascalCase.
If you don't specify any custom naming rules, the following default styles are used:
For classes, structs, enumerations, properties, methods, and events with any accessibility, the default naming style is Pascal case.
For interfaces with any accessibility, the default naming style is Pascal case with a required prefix of I.
All naming options have rule ID IDE1006
and title Naming rule violation
. You can configure the severity of naming violations globally in an EditorConfig file with the following syntax:
dotnet_diagnostic.IDE1006.severity = <severity value>
The severity value must be warning
or error
to be enforced on build. For all possible severity values, see severity level.
The following .editorconfig file contains a naming convention that specifies that public properties, methods, fields, events, and delegates that are marked readonly
must be capitalized. This naming convention specifies multiple kinds of symbol to apply the rule to, using a comma to separate the values.
[*.{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
This .editorconfig file snippet enforces that private instance fields should start with an _
; if that convention is not followed, the IDE will treat it as a compiler error. Private static fields are ignored.
Because you can only define a symbol group based on the identifiers it has (for example, static
or readonly
), and not by the identifiers it doesn't have (for example, an instance field because it doesn't have static
), you need to define two naming rules:
- All private fields—
static
or not—should have theunderscored
naming style applied to them as a compilererror
. - Private fields with
static
should have theunderscored
naming style applied to them with a severity level ofnone
; in other words, ignore this case.
[*.{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
This example also demonstrates that entity definitions can be reused. The underscored
naming style is used by both the private_fields_underscored
and private_static_fields_none
naming rules.
.NET feedback
.NET is an open source project. Select a link to provide feedback: