CA1700: Nie należy nadawać wartościom enum oznaczenia „Reserved"

  • Artykuł
Właściwości Wartość
Identyfikator reguły CA1700
Stanowisko Nie nadawaj wartościom wyliczeniowym nazwy „Reserved”
Kategoria Nazewnictwo
Poprawka powodująca niezgodność lub niezgodność Kluczowa
Domyślnie włączone na platformie .NET 8 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:

  1. Dodaj nowe wyliczenie zawierające oryginalne i nowe elementy członkowskie.

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

CA2217: Nie oznaczaj wyliczeń za pomocą atrybutu FlagsAttribute

CA1712: Nie poprzedzaj wartości wyliczenia nazwą typu

CA1028: Magazyn typu wyliczeniowego powinien być typu Int32

CA1008: Wyliczenia powinny zawierać wartość zero

CA1027: Oznacz typy wyliczeniowe atrybutem Flags