CA1700: Enumerationswerte nicht mit "Reserviert" benennen
TypeName |
DoNotNameEnumValuesReserved |
CheckId |
CA1700 |
Kategorie |
Microsoft.Naming |
Unterbrechende Änderung |
Breaking |
Ursache
Der Name eines Enumerationsmembers enthält das Wort "reserved".
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 sollten nicht erwarten, dass die Benutzer einen Member ignorieren, nur weil sein Name "reserved" enthält, und Sie können auch nicht davon ausgehen, dass die Benutzer die Dokumentation lesen oder sich danach richten. Da reservierte Member in Objektkatalogen und in intelligenten integrierten Entwicklungsumgebungen angezeigt werden, können sie zudem Unklarheiten in Bezug darauf hervorrufen, welche Member tatsächlich verwendet werden.
Statt einen reserved-Member zu verwenden, fügen Sie der Enumeration in der künftigen Version einen neuen Member hinzu. In den meisten Fällen stellt das Hinzufügen des neuen Members keine unterbrechende Änderung dar, solange hierdurch die Werte der ursprünglichen Member nicht geändert werden.
In bestimmten Fällen stellt das Hinzufügen eines Members eine unterbrechende Änderung dar, auch wenn die ursprünglichen Werte der ursprünglichen Member erhalten bleiben. Vor allem kann der neue Member von vorhandenen Codepfaden nicht ohne unterbrechende Aufrufer zurückgegeben werden, 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. Ein weiteres Problem ist, dass der Clientcode die Änderung im Verhalten von Reflektionsmethoden wie Enum.IsDefined eventuell nicht behandeln kann. Entsprechend, wenn der neue Member von vorhandenen Methoden zurückgegeben werden muss oder eine bekannte Anwendungsinkompatibilität wegen schlechter Reflektionsverwendung auftritt, ist die einzige Lösung ohne Unterbrechung:
Hinzufügen einer neuen Enumeration, die die ursprünglichen und neuen Member enthält.
Markieren Sie die ursprüngliche Enumeration mit dem System.ObsoleteAttribute-Attribut.
Gehen Sie bei extern sichtbaren Typen oder Membern, die die ursprüngliche Enumeration verfügbar machen, auf die gleiche Weise vor.
Behandeln von Verstößen
Um einen Verstoß gegen diese Regel zu beheben, müssen Sie den Member entfernen oder umbenennen.
Wann sollten Warnungen unterdrückt werden?
Eine Warnung dieser Regel kann gefahrlos für einen Member unterdrückt werden, der derzeit für zuvor veröffentlichte Bibliotheken verwendet wird.
Verwandte Regeln
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