CA1700: Nepojmenovávejte výčty hodnot 'Reserved'
| Vlastnost | Hodnota |
|---|---|
| ID pravidla | CA1700 |
| Název | Nepojmenovávejte výčty hodnot 'Reserved' |
| Kategorie | Pojmenování |
| Oprava způsobující chybu nebo chybu způsobující chybu | Narušující |
| Povoleno ve výchozím nastavení v .NET 8 | No |
Příčina
Název člena výčtu obsahuje slovo "reserved".
Popis pravidla
Toto pravidlo předpokládá, že člen výčtu, který má název obsahující výraz „reserved“, není aktuálně používán, ale je zástupným symbolem k přejmenování nebo odstranění v budoucí verzi. Přejmenování nebo odstranění členu je narušující změna. Neměli byste očekávat, že uživatelé budou člena ignorovat jenom proto, že jeho název obsahuje "rezervované", ani se nemůžete spolehnout, že uživatelé budou číst nebo dodržovat dokumentaci. Vzhledem k tomu, že se rezervované členy zobrazují v prohlížečích objektů a inteligentních integrovaných vývojových prostředích, můžou způsobit nejasnosti o tom, které členy se skutečně používají.
Místo použití rezervovaného členu přidejte do výčtu v budoucí verzi nový člen. Ve většině případů není přidání nového člena zásadní změnou, pokud sčítání nezpůsobí změnu hodnot původních členů.
V omezeném počtu případů je přidání člena zásadní změnou, i když si původní členové zachovají původní hodnoty. Primárně nelze nový člen vrátit z existujících cest kódu bez způsobujících volajících, kteří používají switch příkaz (Select v jazyce Visual Basic) na návratové hodnotě, která zahrnuje celý seznam členů a které ve výchozím případě vyvolá výjimku. Sekundárním problémem je, že klientský kód nemusí zvládnout změnu chování z metod reflexe, jako System.Enum.IsDefinedje například . Proto pokud se nový člen musí vrátit z existujících metod nebo známé nekompatibility aplikace kvůli špatnému použití reflexe, je jediným nefunkčním řešením:
Přidejte nový výčet, který obsahuje původní a nové členy.
Označte původní výčet atributem System.ObsoleteAttribute .
Stejný postup použijte pro všechny externě viditelné typy nebo členy, které zveřejňují původní výčet.
Jak opravit porušení
Chcete-li opravit porušení tohoto pravidla, odeberte nebo přejmenujte člena.
Kdy potlačit upozornění
Je bezpečné potlačit upozornění z tohoto pravidla pro člena, který je aktuálně používán nebo pro knihovny, které byly dříve odeslány.
Potlačení upozornění
Pokud chcete pouze potlačit jedno porušení, přidejte do zdrojového souboru direktivy preprocesoru, abyste pravidlo zakázali a znovu povolili.
#pragma warning disable CA1700
// The code that's violating the rule is on this line.
#pragma warning restore CA1700
Pokud chcete pravidlo pro soubor, složku nebo projekt zakázat, nastavte jeho závažnost v none konfiguračním souboru.
[*.{cs,vb}]
dotnet_diagnostic.CA1700.severity = none
Další informace naleznete v tématu Jak potlačit upozornění analýzy kódu.
Konfigurace kódu pro analýzu
Pomocí následující možnosti nakonfigurujte, ve kterých částech základu kódu se má toto pravidlo spouštět.
Tuto možnost můžete nakonfigurovat jenom pro toto pravidlo, pro všechna pravidla, která platí, nebo pro všechna pravidla v této kategorii (pojmenování), na která platí. Další informace naleznete v tématu Možnosti konfigurace pravidla kvality kódu.
Zahrnutí konkrétních povrchů rozhraní API
Na základě přístupnosti můžete nakonfigurovat, na kterých částech základu kódu se má toto pravidlo spouštět. Pokud chcete například určit, že pravidlo by se mělo spouštět jenom na neveřejné ploše rozhraní API, přidejte do souboru .editorconfig v projektu následující pár klíč-hodnota:
dotnet_code_quality.CAXXXX.api_surface = private, internal
Související pravidla
CA2217: Neoznačujte výčty pomocí FlagsAttribute
CA1712: Nezačínejte hodnoty výčtu s názvem typu
CA1028: Úložiště výčtu by měl být Int32
