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 łamiąca lub nienaruszająca	Przełomowe
Domyślnie włączone na platformie .NET 10	Nie.
Zastosowane języki	C# i Visual Basic

Przyczyna

Nazwa członka 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, dodaj nowy element 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 jest zmianą przełamującą zgodność nawet wtedy, gdy oryginalne elementy zachowują swoje pierwotne wartości. Przede wszystkim nowego członka nie można zwrócić z istniejących ścieżek kodu bez naruszenia zgodności z wywołującymi, które używają instrukcji switch (Select w Visual Basic) dotyczącej wartości zwracanej, obejmującej całą listę członków, co powoduje zgłoszenie wyjątku w przypadku domyślnym. Dodatkową kwestią jest to, że kod klienta może nie obsługiwać zmiany zachowania metod refleksji, takich jak System.Enum.IsDefined. W związku z tym, jeśli nowy członek musi zostać zwrócony z istniejących metod lub znana niezgodność aplikacji występuje z powodu niewłaściwego użycia refleksji, jedynym rozwiązaniem bez łamania kompatybilności jest:

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

2. Oznacz oryginalne wyliczenie za pomocą atrybutu System.ObsoleteAttribute .

   Wykonaj tę samą procedurę dla wszystkich typów widocznych zewnętrznie lub członków, które eksponują oryginalne wyliczenie.

Jak naprawić naruszenia

Aby naprawić naruszenie tej reguły, usuń lub zmień nazwę członka.

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,
}

Kiedy pomijać ostrzeżenia

Można bezpiecznie pominąć ostrzeżenie z tej reguły dla członka, który jest obecnie używany lub dla bibliotek, które zostały wcześniej wydane.

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 kodu mają być objęte tą regułą.

• Uwzględnij określone powierzchnie interfejsu API

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óre części bazy kodu ma być stosowana ta reguła, na podstawie ich poziomu dostępu, ustawiając opcję api_surface. 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

Notatka

Zastąp część XXXXCAXXXX identyfikatorem odpowiedniej reguły.

Powiązane reguły

CA2217: Nie oznaczaj wyliczeń za pomocą atrybutu FlagsAttribute

CA1712: Nie poprzedzaj wartości wyliczenia nazwą typu

CA1028: Typ bazowy enumeracji powinien być Int32

CA1008: Wyliczenia powinny zawierać wartość zerową

CA1027: Oznacz typy wyliczeniowe atrybutem FlagsAttribute