Dela via

Namngivningsregler i kodformat

  • Artikel

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:

Så här anger du en egenskap för <Använd typvärdet> Exempel
Namngivningsregel dotnet_naming_rule dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion
Symbolgrupp dotnet_naming_symbols dotnet_naming_symbols.interface.applicable_kinds = interface
Namngivningsformat dotnet_naming_style dotnet_naming_style.pascal_case.capitalization = pascal_case

<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.

Property beskrivning Tillåtna värden Obligatoriskt
applicable_kinds Typer av symboler i grupp 1 * (använd det här värdet för att ange alla symboler)
namespace
class
struct
interface
enum
property
method
field
event
delegate
parameter
type_parameter
local
local_function		 Ja
applicable_accessibilities Hjälpmedelsnivåer för symbolerna i gruppen * (använd det här värdet för att ange alla hjälpmedelsnivåer)
public
internal eller friend
private
protected
protected_internal eller protected_friend
private_protected
local (för symboler som definierats inom en metod)		 Ja
required_modifiers Matcha endast symboler med alla angivna modifierare 2 abstract eller must_inherit
async
const
readonly
static eller shared 3		 Nej

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 const gruppen även symboler eftersom de är implicita/staticShared .required_modifiers shared static 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:

Property beskrivning Tillåtna värden Obligatoriskt
capitalization Versaliseringsformat för ord i symbolen pascal_case
camel_case
first_word_upper
all_upper
all_lower		 Ja1
required_prefix Måste börja med dessa tecken Nej
required_suffix Måste sluta med dessa tecken Nej
word_separator Ord i symbolen måste avgränsas med det här tecknet Nej

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.

Property beskrivning
symbols Namnet på en symbolgrupp som definierats någon annanstans. namngivningsregeln tillämpas på symbolerna i den här gruppen
style Namnet på namngivningsformatet som ska associeras med den här regeln. formatmallen definieras någon annanstans
severity Anger allvarlighetsgraden för att framtvinga namngivningsregeln. Ange det associerade värdet till en av de tillgängliga allvarlighetsgraderna.1

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.

Tillägget EditorConfig Language Service kan analysera en EditorConfig-fil och rapportfall där regelordningen i filen skiljer sig från vad kompilatorn kommer att använda vid körning.

Kommentar

Om du använder en version av Visual Studio tidigare än Visual Studio 2019 bör namngivningsregler sorteras från de mest specifika till minst specifika i EditorConfig-filen. Den första regel som kan tillämpas är den enda regel som tillämpas. Men om det finns flera regelegenskaper med samma namn har den senast hittade egenskapen med det namnet företräde. Mer information finns i Filhierarki och prioritet.

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