Regeln für den Codestil

In Ihrer .editorconfig-Datei können Sie Benennungsregeln definieren, die angeben und erzwingen, wie Codeelemente der .NET-Programmiersprache(—z. B. Klassen, Eigenschaften und Methoden—) benannt werden sollen. Sie können beispielsweise angeben, dass öffentliche Member groß geschrieben werden oder private Felder mit _ beginnen müssen.

Eine Benennungsregel besteht aus drei Komponenten:

  • 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 für die Erzwingung der Konvention.

Zuerst müssen Sie die Symbolgruppe und den Benennungsstil angeben und jeweils einen Titel zuweisen. Anschließend geben Sie die Benennungsregel an, die alle Elemente miteinander verknüpft.

Allgemeine Syntax

Legen Sie zum Definieren einer Benennungsregel, einer Symbolgruppe oder eines Benennungsstils mindestens eine Eigenschaft mit der folgenden Syntax fest:

<kind>.<title>.<propertyName> = <propertyValue>

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>

<kind> gibt an, welche Art von Element definiert wird (Namensregel, Symbolgruppe oder Benennungsstil), und muss eine der folgenden Angaben sein:

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

Jeder Typ von Definition — Benennungsregel, Symbolgruppe oder Benennungsstil — hat seine eigenen unterstützten Eigenschaften, wie in den folgenden Abschnitten beschrieben.

<title>

<title> ist ein beschreibender Name, den Sie auswählen, der mehrere Eigenschaftseinstellungen 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

Eigenschaften von Benennungsregeln

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

Eigenschaft BESCHREIBUNG
symbols Der Titel einer Symbolgruppe. Die Benennungsregel wird auf die Symbole in dieser Gruppe angewendet.
style Der Titel des Bennenungsstils, der dieser Regel zugeordnet werden soll.
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.

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:

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

Regelreihenfolge

Die Reihenfolge, in der Benennungsregeln in einer EditorConfig-Datei definiert werden, spielt keine Rolle. Die Benennungsregeln werden automatisch nach der Definition der Regeln selbst geordnet. 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 Version 16.2 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.

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

Die folgende EDITORCONFIG-Datei enthält eine Namenskonvention, die angibt, dass öffentliche Eigenschaften, Methoden, Felder, Ereignisse und Delegaten großgeschrieben werden müssen. Beachten Sie, dass diese Namenskonvention mehrere Arten von Symbolen angibt, 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

Siehe auch