Regeln für den Codestil

  • Artikel

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 shared3		 Nein

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:

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:

  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.

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:

  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.

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:

  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