Dela via

CA1027: Markera uppräkningar med FlagsAttribute

  • Artikel
Property Värde
Regel-ID CA1027
Title Markera uppräkningar med FlagsAttribute
Kategori Designa
Korrigeringen är icke-bakåtkompatibel Icke-icke-bryta
Aktiverad som standard i .NET 9 Nej

Orsak

Värdena för en uppräkning är två eller kombinationer av andra värden som definieras i uppräkningen och System.FlagsAttribute attributet finns inte. För att minska falska positiva identifieringar rapporterar den här regeln inte en överträdelse för uppräkningar som har sammanhängande värden.

Som standard tittar den här regeln bara på externt synliga uppräkningar, men det kan konfigureras.

Regelbeskrivning

En uppräkning är en värdetyp som definierar en uppsättning relaterade namngivna konstanter. Tillämpa på FlagsAttribute en uppräkning när dess namngivna konstanter kan kombineras på ett meningsfullt sätt. Överväg till exempel en uppräkning av veckodagarna i ett program som håller reda på vilka dagsresurser som är tillgängliga. Om tillgängligheten för varje resurs kodas med hjälp av den uppräkning som finns FlagsAttribute kan alla kombinationer av dagar representeras. Utan attributet kan endast en dag i veckan representeras.

För fält som lagrar kombinerbara uppräkningar behandlas de enskilda uppräkningsvärdena som grupper av bitar i fältet. Därför kallas sådana fält ibland bitfält. Om du vill kombinera uppräkningsvärden för lagring i ett bitfält använder du de booleska villkorsoperatorerna. Om du vill testa ett bitfält för att avgöra om det finns ett specifikt uppräkningsvärde använder du de booleska logiska operatorerna. För att ett bitfält ska kunna lagra och hämta kombinerade uppräkningsvärden korrekt måste varje värde som definieras i uppräkningen vara en effekt på två. Om så inte är fallet kan de booleska logiska operatorerna inte extrahera de enskilda uppräkningsvärden som lagras i fältet.

Så här åtgärdar du överträdelser

Om du vill åtgärda ett brott mot den här regeln lägger du till FlagsAttribute i uppräkningen.

När du ska ignorera varningar

Ignorera en varning från den här regeln om du inte vill att uppräkningsvärdena ska vara kombinerbara.

Ignorera en varning

Om du bara vill förhindra en enda överträdelse lägger du till förprocessordirektiv i källfilen för att inaktivera och aktiverar sedan regeln igen.

#pragma warning disable CA1027
// The code that's violating the rule is on this line.
#pragma warning restore CA1027

Om du vill inaktivera regeln för en fil, mapp eller ett projekt anger du dess allvarlighetsgrad till none i konfigurationsfilen.

[*.{cs,vb}]
dotnet_diagnostic.CA1027.severity = none

Mer information finns i Så här utelämnar du kodanalysvarningar.

Konfigurera kod för analys

Använd följande alternativ för att konfigurera vilka delar av kodbasen som regeln ska köras på.

Du kan konfigurera det här alternativet för bara den här regeln, för alla regler som gäller för eller för alla regler i den här kategorin (design) som den gäller för. Mer information finns i Konfigurationsalternativ för kodkvalitetsregel.

Inkludera specifika API-ytor

Du kan konfigurera vilka delar av kodbasen som ska köras med den här regeln baserat på deras tillgänglighet. Om du till exempel vill ange att regeln endast ska köras mot den icke-offentliga API-ytan lägger du till följande nyckel/värde-par i en .editorconfig-fil i projektet:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Exempel

I följande exempel DaysEnumNeedsFlags är en uppräkning som uppfyller kraven för att använda FlagsAttribute men inte har den. Uppräkningen ColorEnumShouldNotHaveFlag har inte värden som är två men som felaktigt anger FlagsAttribute. Detta bryter mot regeln CA2217: Markera inte uppräkningar med 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
}

Se även