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:
Festlegen einer Eigenschaft für | Verwenden des <kind>-Werts | Beispiel |
---|---|---|
Benennungsregel | dotnet_naming_rule |
dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion |
Symbolgruppe | dotnet_naming_symbols |
dotnet_naming_symbols.interface.applicable_kinds = interface |
Benennungsstil | dotnet_naming_style |
dotnet_naming_style.pascal_case.capitalization = pascal_case |
<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.
Eigenschaft | BESCHREIBUNG | Zulässige Werte | Erforderlich |
---|---|---|---|
applicable_kinds |
Arten von Symbolen in der Gruppe 1 | * (verwenden Sie diesen Wert, um alle Symbole anzugeben)namespace class struct interface enum property method field event delegate parameter type_parameter local local_function |
Ja |
applicable_accessibilities |
Zugriffsstufen der Symbole in der Gruppe | * (verwenden Sie diesen Wert, um alle Zugriffsebenen anzugeben)public internal oder friend private protected protected_internal oder protected_friend private_protected local (für Symbole, die in einer Methode definiert sind) |
Ja |
required_modifiers |
Symbole nur mit allen angegebenen Modifizierern abgleichen 2 | abstract oder must_inherit async const readonly static oder shared 3 |
Nein |
Hinweise:
- Tupelmember werden derzeit in
applicable_kinds
nicht unterstützt. - 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. - Wenn die Gruppe
static
odershared
in derrequired_modifiers
-Eigenschaft aufweist, enthält die Gruppe auchconst
-Symbole, da sie implizitstatic
/Shared
sind. Wenn Sie jedoch nicht möchten, dass diestatic
-Benennungsregel aufconst
-Symbole angewendet wird, können Sie eine neue Benennungsregel mit einer Symbolgruppeconst
erstellen. Die neue Regel hat gemäß der Regelreihenfolge Vorrang. 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:
Eigenschaft | BESCHREIBUNG | Zulässige Werte | Erforderlich |
---|---|---|---|
capitalization |
Groß-/Kleinschreibung für Wörter innerhalb des Symbols | pascal_case camel_case first_word_upper all_upper all_lower |
Ja1 |
required_prefix |
Muss mit diesen Zeichen beginnen | Nein | |
required_suffix |
Muss mit diesen Zeichen enden | Nein | |
word_separator |
Wörter innerhalb des Symbols müssen durch dieses Zeichen getrennt werden | Nein |
Hinweise:
- 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.
Eigenschaft | Beschreibung |
---|---|
symbols |
Der Name einer an anderer Stelle definierten Symbolgruppe. Die Benennungsregel wird auf die Symbole in dieser Gruppe angewendet. |
style |
Der Name des Benennungsstils, der dieser Regel zugeordnet werden soll. Der Stil ist an anderer Stelle definiert. |
severity |
Legt den Schweregrad fest, mit dem die Benennungsregel erzwungen werden soll. Legen Sie den zugeordneten Wert auf einen der verfügbaren Schweregrade fest.1 |
Hinweise:
- 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.
Hinweis
Wenn Sie eine frühere Version von Visual Studio als Visual Studio 2019 verwenden, sollten Benennungsregeln von der spezifischsten Regel bis zur am wenigsten spezifischen Regel in der EditorConfig-Datei geordnet werden. Die erste Regel, die angewendet werden kann, ist die einzige Regel, die angewendet wird. Wenn es jedoch mehrere Regeleigenschaften mit dem gleichen Namen gibt, hat die zuletzt gefundene Eigenschaft mit diesem Namen Vorrang. Weitere Informationen finden Sie unter Dateihierarchie und Rangfolge.
Beispiel: Überlappende Benennungsstrategien
Betrachten Sie die beiden folgenden Benennungsregeln:
- Öffentliche Methoden sind PascalCase.
- 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:
- Konstantenfelder sind PascalCase.
- 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:
- Für alle privaten Felder –
static
oder nicht – muss derunderscored
-Benennungsstil als Compilerfehler angewendet werdenerror
. - Bei privaten Feldern mit
static
muss derunderscored
-Benennungsstil mit dem Schweregradnone
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
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter:Einreichen und Feedback anzeigen für