Namngivningsregler i kodformat

I .editorconfig-filen kan du definiera namngivningskonventioner för kodelement för .NET-programmeringsspråk – till exempel klasser, egenskaper och metoder – och hur kompilatorn eller IDE ska tillämpa dessa konventioner. Du kan till exempel ange att en offentlig medlem som inte är versaliserad ska behandlas som ett kompilatorfel, eller att om ett privat fält inte börjar med en _bör en byggvarning utfärdas.

Mer specifikt kan du definiera en namngivningsregel som består av tre delar:

• Den symbolgrupp som regeln gäller för till exempel offentliga medlemmar eller privata fält.
• Namngivningsformatet som ska associeras med regeln, till exempel att namnet måste vara versalt eller börja med ett understreck.
• Allvarlighetsgraden för meddelandet när kodelement som ingår i symbolgruppen inte följer namngivningsformatet.

Allmän syntax

Om du vill definiera någon av ovanstående entiteter – en namngivningsregel, symbolgrupp eller namngivningsformat – anger du en eller flera egenskaper med hjälp av följande syntax:

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

Alla egenskapsinställningar för en viss kind och entityName utgör den specifika entitetsdefinitionen.

Varje egenskap bör bara anges en gång, men vissa inställningar tillåter flera kommaavgränsade värden.

Egenskapernas ordning är inte viktig.

<typvärden>

<typ> anger vilken typ av entitet som definieras – namngivningsregel, symbolgrupp eller namngivningsformat – och måste vara något av följande:

<entityName>

<entityName> är ett beskrivande namn som du väljer som kopplar flera egenskapsinställningar till en enda definition. Följande egenskaper skapar till exempel två symbolgruppsdefinitioner interface och , som var och typesen har två egenskaper inställda på sig.

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> och <propertyValue>

Varje typ av entitet – namngivningsregel, symbolgrupp eller namngivningsformat – har egna egenskaper som stöds enligt beskrivningen i följande avsnitt.

Egenskaper för symbolgrupp

Du kan ange följande egenskaper för symbolgrupper för att begränsa vilka symboler som ingår i gruppen. Om du vill ange flera värden för en enskild egenskap separerar du värdena med kommatecken.

Anteckningar:

1. Tuppelns medlemmar stöds för närvarande inte i applicable_kinds.
2. Symbolgruppen matchar alla modifierare i egenskapen required_modifiers . Om du utelämnar den här egenskapen krävs inga specifika modifierare för en matchning. Det innebär att en symbols modifierare inte har någon effekt på huruvida den här regeln tillämpas eller inte.
3. Om din grupp har eller i egenskapen innehåller static gruppen även symboler eftersom de är implicitasharedrequired_modifiersconst .static/Shared Men om du inte vill static att namngivningsregeln ska gälla för const symboler kan du skapa en ny namngivningsregel med en symbolgrupp med const. Den nya regeln har företräde enligt regelordningen.
4. class innehåller C#-poster.

Egenskaper för namngivningsformat

Ett namngivningsformat definierar de konventioner som du vill tillämpa med regeln. Till exempel:

• Versalisera med PascalCase
• Börjar med m_
• Slutar med _g
• Avgränsa ord med __

Du kan ange följande egenskaper för ett namngivningsformat:

Anteckningar:

1. Du måste ange en versaliseringsstil som en del av namngivningsformatet, annars kan namngivningsstilen ignoreras.

Egenskaper för namngivningsregel

Alla egenskaper för namngivningsregeln krävs för att en regel ska börja gälla.

Anteckningar:

1. Allvarlighetsgradsspecifikationen i en namngivningsregel respekteras endast i utvecklings-ID:er, till exempel Visual Studio. Den här inställningen tolkas inte av C#- eller VB-kompilatorerna, och därför respekteras inte under bygget. Om du vill framtvinga namngivningsformatregler vid kompilering bör du i stället ange allvarlighetsgraden med hjälp av konfiguration av allvarlighetsgrad för kodregeln. Mer information finns i det här GitHub-problemet.

Regelordning

Det spelar ingen roll i vilken ordning namngivningsregler definieras i en EditorConfig-fil. Namngivningsreglerna sorteras automatiskt enligt definitionerna i själva reglerna. Mer specifika regler för åtkomst, modifierare och symboler har företräde framför mindre specifika regler. Om det finns överlappning mellan regler eller om regelordningen orsakar problem kan du bryta ut skärningspunkten mellan de två reglerna i en ny regel som har företräde framför de bredare regler som den härleddes från. Exempel finns i Exempel: Överlappande namngivningsstrategier och Exempel: const modifieraren innehåller static och readonly.

Exempel: Överlappande namngivningsstrategier

Överväg följande två namngivningsregler:

1. Offentliga metoder är PascalCase.
2. Asynkrona metoder slutar med "Async".

För public async metoder är det inte uppenbart vilken regel som har företräde. Du kan skapa en ny regel för public async metoder och ange exakt namngivning.

Exempel: const modifieraren innehåller static och readonly

Överväg följande två namngivningsregler:

1. Konstanta fält är PascalCase.
2. Icke-offentliga static fält är s_camelCase.

Regel 2 är mer specifik och har företräde, så alla icke-offentliga konstanta fält är s_camelCase. För att lösa problemet kan du definiera en skärningspunktsregel: icke-offentliga konstanta fält är PascalCase.

Standardnamnformat

Om du inte anger några anpassade namngivningsregler används följande standardformat:

• För klasser, structs, uppräkningar, egenskaper, metoder och händelser med all tillgänglighet är standardnamnstilen Pascal-skiftläge.

• För gränssnitt med hjälpmedel är standardnamnstilen Pascal-skiftläge med ett obligatoriskt prefix för I.

Kodregel-ID: IDE1006 (Naming rule violation)

Alla namngivningsalternativ har regel-ID IDE1006 och rubrik Naming rule violation. Du kan konfigurera allvarlighetsgraden för namngivningsöverträdelser globalt i en EditorConfig-fil med följande syntax:

dotnet_diagnostic.IDE1006.severity = <severity value>

Allvarlighetsgradsvärdet måste vara warning eller error framtvingas i bygget. Alla möjliga allvarlighetsvärden finns i allvarlighetsgrad.

Exempel: Versaler för offentliga medlemmar

Följande .editorconfig-fil innehåller en namngivningskonvention som anger att offentliga egenskaper, metoder, fält, händelser och ombud som är markerade readonly måste vara versaler. Den här namngivningskonventionen anger flera typer av symboler som regeln ska tillämpas på med hjälp av ett kommatecken för att separera värdena.

[*.{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

Exempel: Privata instansfält med understreck

Det här .editorconfig-filfragmentet framtvingar att fält för privata instanser ska börja med en _. Om den konventionen inte följs behandlar IDE det som ett kompilatorfel. Privata statiska fält ignoreras.

Eftersom du bara kan definiera en symbolgrupp baserat på de identifierare den har (till exempel static eller readonly), och inte av de identifierare som den inte har (till exempel ett instansfält eftersom den inte har static), måste du definiera två namngivningsregler:

1. Alla privata fält– static eller inte – ska ha namngivningsformatet underscored tillämpat på dem som kompilator error.
2. Privata fält med static ska ha namngivningsstilen underscored tillämpad på dem med allvarlighetsgraden none. Det vill säga ignorera det här fallet.

[*.{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

Det här exemplet visar också att entitetsdefinitioner kan återanvändas. Namngivningsformatet underscored används av både private_fields_underscored namngivningsreglerna och private_static_fields_none .

Se även

• Språkregler
• Formateringsregler
• Roslyn-namngivningsregler
• Namngivningsregler och konventioner för C#-identifierare