CA1700: Enumerationswerte nicht mit "Reserviert" benennen.

  • Artikel
Eigenschaft Wert
Regel-ID CA1700
Titel Enumerationswerte nicht mit "Reserviert" benennen.
Kategorie Benennung
Fix führt oder führt nicht zur Unterbrechung Breaking
Standardmäßig in .NET 9 aktiviert No

Ursache

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

Regelbeschreibung

Bei dieser Regel wird vorausgesetzt, dass Enumerationsmember mit einem Namen, der "reserved" enthält, derzeit nicht verwendet werden, sondern Platzhalter sind, die in einer künftigen Version umbenannt oder entfernt werden sollen. 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 Member in Objektbrowsern und smarten IDEs (integrierte Entwicklungsumgebung) verwendet werden, kann Verwirrung darüber entstehen, welche Member tatsächlich verwendet werden.

Fügen Sie der Enumeration in der zukünftigen Version einen neuen Member hinzu, anstatt einen reservierten Member 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. Einerseits kann der neue Member nicht aus vorhandenen Codepfaden zurückgegeben werden, ohne Aufrufer zu beschädigen, die eine switch-Anweisung (Select in Visual Basic) für den Rückgabewert verwenden, der die gesamte Memberliste umfasst, und die im Standardfall eine Ausnahme auslösen. Andererseits kann der Clientcode den Behavior Change in Reflexionsmethoden wie System.Enum.IsDefined möglicherweise nicht verarbeiten. Wenn der neue Member von vorhandenen Methoden zurückgegeben werden muss oder eine bekannte Anwendungsinkompatibilität aufgrund von ungeeigneter Reflexionsverwendung auftritt, führt nur diese Lösung nicht zu Breaking Changes:

  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.

Behandeln von Verstößen

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

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 in der Konfigurationsdatei auf none 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.

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 je nach Zugänglichkeit festlegen, für welche Bestandteile Ihrer Codebasis diese Regel ausgeführt wird. 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

CA2217: Enumerationen nicht mit FlagsAttribute markieren.

CA1712: Keine Typnamen als Präfixe für Enumerationswerte verwenden.

CA1028: Der Enumerationsspeicher sollte Int32 sein.

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

CA1027: Enumerationen mit FlagsAttribute markieren.