CA1700: Nie należy nadawać wartościom enum oznaczenia „Reserved"
| Właściwości | Wartość |
|---|---|
| Identyfikator reguły | CA1700 |
| Tytuł | Nie nadawaj wartościom wyliczeniowym nazwy „Reserved” |
| Kategoria | Nazewnictwo |
| Poprawka powodująca niezgodność lub niezgodność | Kluczowa |
| Domyślnie włączone na platformie .NET 9 | Nie. |
Przyczyna
Nazwa elementu członkowskiego wyliczenia zawiera słowo "zarezerwowane".
Opis reguły
Ta reguła zakłada, że element członkowski wyliczenia o nazwie, która zawiera „reserved”, nie jest obecnie używany, ale jest symbolem zastępczym do zmiany nazwy lub usunięcia w przyszłej wersji. Zmiana nazwy lub usuwanie członka jest zmianą przerywającą. Nie należy oczekiwać, że użytkownicy będą ignorować członka tylko dlatego, że jego nazwa zawiera wartość "zarezerwowaną", ani nie można polegać na użytkownikach na odczytywaniu lub przestrzeganiu dokumentacji. Ponadto, ponieważ zastrzeżone elementy członkowskie pojawiają się w przeglądarkach obiektów i inteligentnych zintegrowanych środowiskach deweloperskich, mogą powodować zamieszanie dotyczące elementów członkowskich, które są rzeczywiście używane.
Zamiast używać zarezerwowanego elementu członkowskiego, dodaj nowy element członkowski do wyliczenia w przyszłej wersji. W większości przypadków dodanie nowego elementu członkowskiego nie jest zmianą powodującą niezgodność, o ile dodanie nie powoduje zmiany wartości oryginalnych elementów członkowskich.
W ograniczonej liczbie przypadków dodanie elementu członkowskiego jest zmianą powodującą niezgodność nawet wtedy, gdy oryginalne elementy członkowskie zachowują swoje oryginalne wartości. Przede wszystkim nie można zwrócić nowego elementu członkowskiego z istniejących ścieżek kodu bez wywołań powodujących niezgodność, które używają switch instrukcji (Select w Visual Basic) w wartości zwracanej, która obejmuje całą listę elementów członkowskich i zgłasza wyjątek w przypadku domyślnym. Pomocniczym problemem jest to, że kod klienta może nie obsługiwać zmiany zachowania z metod odbicia, takich jak System.Enum.IsDefined. W związku z tym, jeśli nowy element członkowski musi zostać zwrócony z istniejących metod lub znana niezgodność aplikacji występuje z powodu słabego użycia odbicia, jedynym rozwiązaniem niełamającym jest:
Dodaj nowe wyliczenie zawierające oryginalne i nowe elementy członkowskie.
Oznacz oryginalne wyliczenie za pomocą atrybutu System.ObsoleteAttribute .
Wykonaj tę samą procedurę dla wszystkich typów widocznych zewnętrznie lub elementów członkowskich, które uwidaczniają oryginalne wyliczenie.
Jak naprawić naruszenia
Aby naprawić naruszenie tej reguły, usuń lub zmień nazwę elementu członkowskiego.
Kiedy pomijać ostrzeżenia
Można bezpiecznie pominąć ostrzeżenie z tej reguły dla elementu członkowskiego, który jest obecnie używany lub dla bibliotek, które zostały wcześniej wysłane.
Pomijanie ostrzeżenia
Jeśli chcesz po prostu pominąć pojedyncze naruszenie, dodaj dyrektywy preprocesora do pliku źródłowego, aby wyłączyć, a następnie ponownie włączyć regułę.
#pragma warning disable CA1700
// The code that's violating the rule is on this line.
#pragma warning restore CA1700
Aby wyłączyć regułę dla pliku, folderu lub projektu, ustaw jego ważność na none w pliku konfiguracji.
[*.{cs,vb}]
dotnet_diagnostic.CA1700.severity = none
Aby uzyskać więcej informacji, zobacz Jak pominąć ostrzeżenia dotyczące analizy kodu.
Konfigurowanie kodu do analizowania
Użyj następującej opcji, aby skonfigurować, które części bazy kodu mają być uruchamiane w tej regule.
Tę opcję można skonfigurować tylko dla tej reguły, dla wszystkich reguł, do których ma ona zastosowanie, lub dla wszystkich reguł w tej kategorii (nazewnictwo), których dotyczy. Aby uzyskać więcej informacji, zobacz Opcje konfiguracji reguły jakości kodu.
Uwzględnij określone powierzchnie interfejsu API
Możesz skonfigurować, na których częściach bazy kodu ma być uruchamiana ta reguła, na podstawie ich ułatwień dostępu. Aby na przykład określić, że reguła powinna być uruchamiana tylko na powierzchni niepublicznego interfejsu API, dodaj następującą parę klucz-wartość do pliku editorconfig w projekcie:
dotnet_code_quality.CAXXXX.api_surface = private, internal
Powiązane reguły
CA2217: Nie oznaczaj wyliczeń za pomocą atrybutu FlagsAttribute
CA1712: Nie poprzedzaj wartości wyliczenia nazwą typu
CA1028: Magazyn typu wyliczeniowego powinien być typu Int32
