Regeln für den Codestil

In der .editorconfig-Datei können Sie Namenskonventionen für Codeelemente Ihrer .NET-Programmiersprache (z. B. Klassen, Eigenschaften und Methoden) definieren und festlegen, wie der Compiler oder die IDE diese Konventionen erzwingen soll. Sie können beispielsweise angeben, dass ein öffentlicher, nicht großgeschriebener Member als Compilerfehler behandelt oder dass eine Buildwarnung ausgegeben werden soll, wenn ein privates Feld nicht mit _ beginnt.

Insbesondere können Sie eine Benennungsregel definieren, die aus drei Teilen besteht:

• Der Symbolgruppe, für die die Regel gilt, z. B. öffentliche Member oder private Felder.
• Dem Benennungsstil, der der Regel zugeordnet werden soll, z. B., dass der Name groß geschrieben werden oder mit einem Unterstrich beginnen muss.
• Dem Schweregrad der Nachricht, wenn in der Symbolgruppe enthaltene Codeelemente nicht dem Benennungsstil entsprechen.

Allgemeine Syntax

Legen Sie zum Definieren einer der oben genannten Entitäten (Benennungsregel, Symbolgruppe oder Benennungsstil) mindestens eine Eigenschaft mit der folgenden Syntax fest:

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

Alle Eigenschafteneinstellungen für eine bestimmte kind- und entityName-Eigenschaft bilden zusammen diese spezifische Entitätsdefinition.

Jede Eigenschaft sollte nur ein Mal festgelegt werden, aber einige Einstellungen lassen mehrere durch Trennzeichen getrennte Werte zu.

Die Reihenfolge der Eigenschaften ist ohne Bedeutung.

<kind>-Werte

<kind> gibt an, welche Art von Entität definiert wird (Benennungsregel, Symbolgruppe oder Benennungsstil), und muss einen der folgenden Werte haben:

<Entitätsname>

<entityName> ist ein von Ihnen ausgewählter beschreibender Name, der mehrere Eigenschafteneinstellungen einer einzelnen Definition zuordnet. Die folgenden Eigenschaften ergeben z. B. zwei Symbolgruppendefinitionen (interface und types), für die jeweils zwei Eigenschaften festgelegt sind.

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

Jede Art von Entität (Benennungsregel, Symbolgruppe oder Benennungsstil) hat seine eigenen unterstützten Eigenschaften, wie in den folgenden Abschnitten beschrieben.

Symbolgruppeneigenschaften

Sie können die folgenden Eigenschaften für Symbolgruppen festlegen, um einzuschränken, welche Symbole in der Gruppe enthalten sind. Wenn Sie mehrere Werte für eine einzelne Eigenschaft angeben möchten, trennen Sie die Werte durch ein Komma.

Hinweise:

1. Tupelmember werden derzeit in applicable_kinds nicht unterstützt.
2. Die Symbolgruppe gleicht alle Modifiziererer in der required_modifiers-Eigenschaft ab. Wenn Sie diese Eigenschaft nicht angeben, sind keine bestimmten Modifizierer für eine Übereinstimmung erforderlich. Das bedeutet, dass die Modifizierer eines Symbols keine Auswirkungen darauf haben, ob die Regel angewendet wird oder nicht.
3. Wenn die Gruppe static oder shared in der required_modifiers-Eigenschaft aufweist, enthält die Gruppe auch const-Symbole, da sie implizit static/Shared sind. Wenn Sie jedoch nicht möchten, dass die static-Benennungsregel auf const-Symbole angewendet wird, können Sie eine neue Benennungsregel mit einer Symbolgruppe const erstellen. Die neue Regel hat gemäß der Regelreihenfolge Vorrang.
4. class enthält C#-Datensätze.

Benennungsstileigenschaften

Ein Benennungsstil definiert die Konventionen, die Sie mit der Regel erzwingen möchten. Beispiel:

• Großschreibung mit PascalCase
• Beginnt mit m_
• Endet mit _g
• Wörter trennen mit __

Sie können die folgenden Eigenschaften für einen Benennungsstil festlegen:

Hinweise:

1. Sie müssen im Rahmen Ihres Benennungsstils einen Stil für die Groß-/Kleinschreibung angeben. Andernfalls wird Ihr Benennungsstil möglicherweise ignoriert.

Eigenschaften von Benennungsregeln

Alle Eigenschaften der Benennungsregel sind erforderlich, damit eine Regel wirksam wird.

Hinweise:

1. Die Schweregradspezifikation innerhalb einer Benennungsregel wird nur innerhalb von Entwicklungs-IDEs wie Visual Studio berücksichtigt. Diese Einstellung wird von den C#- oder VB-Compilern nicht verstanden und daher während des Buildvorgangs nicht beachtet. Wenn Sie Benennungsstilregeln für den Build erzwingen möchten, sollten Sie stattdessen den Schweregrad mithilfe der Konfiguration für den Coderegelschweregrad festlegen. Weitere Informationen finden Sie in diesem GitHub-Problem.

Regelreihenfolge

Die Reihenfolge, in der Benennungsregeln in einer EditorConfig-Datei definiert werden, spielt keine Rolle. Die Benennungsregeln werden automatisch nach den Definitionen der Regeln selbst geordnet. Spezifischere Regeln für Zugriffsebenen, Modifizierer und Symbole haben Vorrang vor weniger spezifischen Regeln. Wenn es Überlappungen zwischen Regeln gibt oder wenn die Regelreihenfolge Probleme verursacht, können Sie die Schnittmenge der beiden Regeln in eine neue Regel ausgliedern, die Vorrang vor den allgemeineren Regeln hat, von denen sie abgeleitet wurde. Beispiele finden Sie unter Beispiel: Überlappende Benennungsstrategien und Beispiel: const-Modifizierer enthält static und readonly.

Die Erweiterung EditorConfig Language Service kann eine EditorConfig-Datei analysieren und Fälle melden, in denen sich die Regelreihenfolge in der Datei von der Reihenfolge unterscheidet, die vom Compiler zur Laufzeit verwendet wird.

Beispiel: Überlappende Benennungsstrategien

Betrachten Sie die beiden folgenden Benennungsregeln:

1. Öffentliche Methoden sind PascalCase.
2. Asynchrone Methoden enden mit "Async".

Bei public async-Methoden ist nicht offensichtlich, welche Regel Vorrang hat. Sie können für public async-Methoden eine neue Regel erstellen und die Benennung genau angeben.

Beispiel: const-Modifizierer enthält static und readonly

Betrachten Sie die beiden folgenden Benennungsregeln:

1. Konstantenfelder sind PascalCase.
2. Nicht öffentliche static-Felder sind s_camelCase.

Regel 2 ist spezifischer und hat Vorrang, sodass alle nicht öffentlichen Konstantenfelder s_camelCase sind. Um das Problem zu beheben, können Sie eine Schnittmengenregel definieren: Nicht öffentliche Konstantenfelder sind PascalCase.

Standardbenennungsstile

Wenn Sie keine benutzerdefinierten Benennungsregeln angeben, werden die folgenden Standardstile verwendet:

• Für Klassen, Strukturen, Enumerationen, Eigenschaften, Methoden und Ereignissen mit beliebiger Zugriffsebene ist die Pascal-Schreibweise der standardmäßige Benennungsstil.

• Für Schnittstellen mit beliebiger Zugriffsebene ist der standardmäßige Benennungsstil die Pascal-Schreibweise mit dem erforderlichen Präfix I.

Coderegel-ID: IDE1006 (Naming rule violation)

Alle Benennungsoptionen weisen eine Regel-ID IDE1006 und einen Titel Naming rule violation auf. Sie können den Schweregrad von Benennungsverstößen global in einer EditorConfig-Datei mit der folgenden Syntax konfigurieren:

dotnet_diagnostic.IDE1006.severity = <severity value>

Der Schweregrad muss warning oder error lauten, um beim Build erzwungen zu werden. Alle zulässigen Schweregradwerte finden Sie unter Schweregrad.

Beispiel: Großschreibung für öffentliche Member

Die folgende .editorconfig-Datei enthält eine Namenskonvention, die angibt, dass öffentliche Eigenschaften, Methoden, Felder, Ereignisse und Delegaten, die als readonly gekennzeichnet sind, großgeschrieben werden müssen. Diese Namenskonvention gibt mehrere Arten von Symbolen an, für die die Regel gelten soll, wobei die Werte durch ein Komma getrennt werden.

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

Beispiel: Private Instanzfelder mit Unterstrich

Dieser .editorconfig-Dateiausschnitt erzwingt, dass private Instanzfelder mit _ beginnen sollen. Wenn diese Konvention nicht eingehalten wird, behandelt die IDE dies als Compilerfehler. Private statische Felder werden ignoriert.

Da Sie eine Symbolgruppe nur basierend auf den vorhandenen Bezeichnern definieren können (z. B. static oder readonly) und nicht basierend auf den nicht vorhandenen Bezeichnern (z. B. ein Instanzfeld, da static nicht vorhanden ist), müssen Sie zwei Benennungsregeln definieren:

1. Für alle privaten Felder – static oder nicht – muss der underscored-Benennungsstil als Compilerfehler angewendet werden error.
2. Bei privaten Feldern mit static muss der underscored-Benennungsstil mit dem Schweregrad none angewendet werden. Oder anders ausgedrückt: Ignorieren Sie diesen Fall.

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

In diesem Beispiel wird außerdem veranschaulicht, dass Entitätsdefinitionen wiederverwendet werden können. Der underscored-Benennungsstil wird sowohl von der private_fields_underscored- als auch der private_static_fields_none-Benennungsregel verwendet.

Siehe auch

• Sprachregeln
• Formatierungsregeln
• Roslyn-Benennungsregeln
• Benennungsregeln und -konventionen für C#-Bezeichner