CA1027: Označte výčty pomocí FlagsAttribute

  • Článek
Vlastnost Hodnota
ID pravidla CA1027
Název Označte výčty pomocí FlagsAttribute
Kategorie Návrh
Oprava způsobující chybu nebo chybu způsobující chybu Nenarušující
Povoleno ve výchozím nastavení v .NET 8 No

Příčina

Hodnoty výčtu jsou mocniny dvou nebo jsou kombinace jiných hodnot definovaných v výčtu a System.FlagsAttribute atribut není k dispozici. Chcete-li snížit falešně pozitivní výsledky, toto pravidlo neohlásí porušení výčtů, které mají souvislé hodnoty.

Ve výchozím nastavení toto pravidlo sleduje jenom externě viditelné výčty, ale dá se konfigurovat.

Popis pravidla

Výčet je typ hodnoty, který definuje množinu souvisejících pojmenovaných konstant. Použít FlagsAttribute u výčtu, pokud se pojmenované konstanty dají smysluplně zkombinovat. Představte si například výčet dnů v týdnu v aplikaci, která sleduje, které denní prostředky jsou k dispozici. Pokud je dostupnost jednotlivých prostředků kódována pomocí výčtu, který obsahuje FlagsAttribute , může být reprezentována libovolná kombinace dnů. Bez atributu lze reprezentovat pouze jeden den v týdnu.

U polí, která ukládají kombinovatelné výčty, se jednotlivé hodnoty výčtu považují za skupiny bitů v poli. Proto se tato pole někdy označují jako bitová pole. Pokud chcete zkombinovat hodnoty výčtu pro úložiště v bitovém poli, použijte logické podmíněné operátory. Pokud chcete otestovat bitové pole, abyste zjistili, jestli je k dispozici konkrétní hodnota výčtu, použijte logické operátory typu Boolean. Aby bylo možné bitové pole správně uložit a načíst kombinované hodnoty výčtu, musí být každá hodnota definovaná v výčtu mocninami dvou. Pokud tomu tak není, logické operátory logických operátorů nebudou moct extrahovat jednotlivé hodnoty výčtu, které jsou uloženy v poli.

Jak opravit porušení

Chcete-li opravit porušení tohoto pravidla, přidejte FlagsAttribute do výčtu.

Kdy potlačit upozornění

Pokud nechcete, aby hodnoty výčtu byly kombinovatelné, potlačit upozornění z tohoto pravidla.

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 CA1027
// The code that's violating the rule is on this line.
#pragma warning restore CA1027

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.CA1027.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 (Návrh), 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

Příklad

V následujícím příkladu je výčet, který splňuje požadavky na použitíFlagsAttribute, DaysEnumNeedsFlags ale nemá ho. Výčet ColorEnumShouldNotHaveFlag neobsahuje hodnoty, které jsou mocniny dvou, ale nesprávně určuje FlagsAttribute. To porušuje pravidlo CA2217: Neoznačí výčty příznakem FlagsAttribute.

// Violates rule: MarkEnumsWithFlags.
public enum DaysEnumNeedsFlags
{
    None = 0,
    Monday = 1,
    Tuesday = 2,
    Wednesday = 4,
    Thursday = 8,
    Friday = 16,
    All = Monday | Tuesday | Wednesday | Thursday | Friday
}

// Violates rule: DoNotMarkEnumsWithFlags.
[FlagsAttribute]
public enum ColorEnumShouldNotHaveFlag
{
    None = 0,
    Red = 1,
    Orange = 3,
    Yellow = 4
}

Viz také