CA1700: Enum-Werte nicht mit "Reserviert" benennen.

Eigenschaft	Wert
Regel-ID	CA1700
Titel	Enum-Werte nicht "Reserviert" benennen.
Kategorie	Benennung
Fix führt zu Unterbrechungen oder bleibt funktionsfähig	Eilmeldung
Standardmäßig in .NET 10 aktiviert	Nein
Anwendbare Sprachen	C# und Visual Basic

Ursache

Der Name eines Aufzählungselements enthält das Wort „reserviert“.

Regelbeschreibung

Bei dieser Regel wird vorausgesetzt, dass ein Enumerationsmitglied mit einem Namen, der "reserved" enthält, derzeit nicht verwendet wird, jedoch als Platzhalter dient, um in einer künftigen Version umbenannt oder entfernt zu werden. Das Umbenennen oder Entfernen eines Members ist eine unterbrechende Änderung. Sie können von den Benutzern nicht erwarten, einen Member zu ignorieren, nur weil dessen Namen „reserviert“ enthält. Ebenfalls können Sie sich nicht darauf verlassen, dass Benutzer die Dokumentation lesen und befolgen. Da reservierte Mitglieder in Objektbrowsern und intelligenten IDEs (integrierte Entwicklungsumgebungen) erscheinen, kann es zu Verwirrung darüber kommen, welche Mitglieder tatsächlich verwendet werden.

Fügen Sie in einer zukünftigen Version einen neuen Mitglied zur Aufzählung hinzu, anstatt ein reserviertes Mitglied zu verwenden. In den meisten Fällen handelt es sich beim Hinzufügen des neuen Members nicht um einen Breaking Change, sofern diese Aktion nicht bewirkt, dass die Werte der ursprünglichen Member geändert werden.

Das Hinzufügen eines Member ist nur in wenigen Fällen ein Breaking Change, auch wenn die ursprünglichen Member ihre Werte beibehalten. In erster Linie kann der neue Member nicht aus vorhandenen Codepfaden zurückgegeben werden, ohne Aufrufer zu beeinträchtigen, die eine switch-Anweisung (Select in Visual Basic) für den Rückgabewert verwenden, die die gesamte Memberliste umfasst und im Standardfall eine Ausnahme auslösen. Ein sekundäres Anliegen ist, dass der Clientcode möglicherweise nicht mit der Verhaltensänderung in Reflexionsmethoden wie System.Enum.IsDefined umgehen kann. Wenn das neue Mitglied von vorhandenen Methoden zurückgegeben werden muss oder eine bekannte Anwendungsinkompatibilität aufgrund ungeeigneter Verwendung von Reflexion auftritt, ist die einzige nicht-destruktive Lösung:

1. Fügen Sie eine neue Enumeration hinzu, die die ursprünglichen und neuen Member enthält.

2. Kennzeichnen Sie die ursprüngliche Enumeration mit dem Attribut System.ObsoleteAttribute.

   Führen Sie diese Schritte für sämtliche extern sichtbaren Typen oder Member durch, die die ursprüngliche Enumeration verfügbar machen.

So beheben Sie Verstöße

Sie können einen Verstoß gegen diese Regel korrigieren, indem Sie den Member entfernen oder umbenennen.

Example

// This enum violates the rule.
public enum BadPaymentStatus
{
    Pending = 0,
    Completed = 1,
    ReservedError = 2,
    Reserved = 3,
}

// This enum satisfies the rule.
public enum GoodPaymentStatus
{
    Pending = 0,
    Completed = 1,
    Error = 2,
    Unknown = 3,
}

Wann sollten Warnungen unterdrückt werden?

Eine Warnung für diese Regel kann bedenkenlos unterdrückt werden, wenn ein Member derzeit verwendet wird oder es sich um zuvor bereitgestellte Bibliotheken handelt.

Unterdrücken einer Warnung

Um nur eine einzelne Verletzung zu unterdrücken, fügen Sie der Quelldatei Präprozessoranweisungen hinzu, um die Regel zu deaktivieren und dann wieder zu aktivieren.

#pragma warning disable CA1700
// The code that's violating the rule is on this line.
#pragma warning restore CA1700

Um die Regel für eine Datei, einen Ordner oder ein Projekt zu deaktivieren, legen Sie den Schweregrad auf none in der Konfigurationsdatei fest.

[*.{cs,vb}]
dotnet_diagnostic.CA1700.severity = none

Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken von Codeanalyse-Warnungen.

Konfigurieren des zu analysierenden Codes

Mithilfe der folgenden Option können Sie konfigurieren, für welche Teile Ihrer Codebasis diese Regel ausgeführt werden soll.

• Einschließen bestimmter API-Oberflächen

Sie können diese Option nur für diese Regel, für alle zutreffenden Regeln oder für alle zutreffenden Regeln in dieser Kategorie (Benennung) konfigurieren. Weitere Informationen finden Sie unter Konfigurationsoptionen für die Codequalitätsregel.

Einschließen bestimmter API-Oberflächen

Sie können konfigurieren, auf welchen Teilen Ihrer Codebasis je nach Barrierefreiheit diese Regel ausgeführt werden soll, indem Sie die Option api_surface festlegen. Sie können beispielsweise festlegen, dass die Regel nur für die nicht öffentliche API-Oberfläche ausgeführt werden soll, indem Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzufügen:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Hinweis

Ersetzen Sie den XXXX-Teil von CAXXXX durch die ID der anwendbaren Regel.

Ähnliche Regeln

CA2217: Enums nicht mit FlagsAttribute markieren.

CA1712: Verwenden Sie keine Typnamen als Präfix für Aufzählungswerte.

CA1028: Der Enumerationsspeicher sollte als Int32 definiert sein.

CA1008: Enumerationen müssen einen Wert von 0 (null) aufweisen.

CA1027: Enumerationen mit dem Flag-Attribut markieren.