Delen via

CA1027: Opsommingen markeren met FlagsAttribute

  • Artikel
Eigenschappen Weergegeven als
Regel-id CA1027
Titel Opsommingen markeren met FlagsAttribute
Categorie Ontwerpen
Oplossing is brekend of niet-brekend Niet-brekend
Standaard ingeschakeld in .NET 8 Nee

Oorzaak

De waarden van een opsomming zijn machten van twee of zijn combinaties van andere waarden die zijn gedefinieerd in de opsomming en het System.FlagsAttribute kenmerk is niet aanwezig. Als u fout-positieven wilt verminderen, meldt deze regel geen schending voor opsommingen met aaneengesloten waarden.

Deze regel kijkt standaard alleen naar extern zichtbare opsommingen, maar dit is configureerbaar.

Beschrijving van regel

Een opsomming is een waardetype dat een set gerelateerde benoemde constanten definieert. Pas toe FlagsAttribute op een opsomming wanneer de benoemde constanten zinvol kunnen worden gecombineerd. Denk bijvoorbeeld aan een opsomming van de dagen van de week in een toepassing die bijhoudt welke dagbronnen beschikbaar zijn. Als de beschikbaarheid van elke resource wordt gecodeerd met behulp van de opsomming die aanwezig is FlagsAttribute , kan elke combinatie van dagen worden weergegeven. Zonder het kenmerk kan slechts één dag van de week worden weergegeven.

Voor velden waarin combineerbare opsommingen worden opgeslagen, worden de afzonderlijke opsommingswaarden behandeld als groepen bits in het veld. Daarom worden dergelijke velden soms bitvelden genoemd. Als u opsommingswaarden voor opslag in een bitveld wilt combineren, gebruikt u de booleaanse voorwaardelijke operatoren. Als u een bitveld wilt testen om te bepalen of een specifieke opsommingswaarde aanwezig is, gebruikt u de booleaanse logische operators. Voor een bitveld om gecombineerde opsommingswaarden correct op te slaan en op te halen, moet elke waarde die in de opsomming is gedefinieerd, een macht van twee zijn. Tenzij dit zo is, kunnen de booleaanse logische operators de afzonderlijke opsommingswaarden die zijn opgeslagen in het veld niet extraheren.

Schendingen oplossen

Als u een schending van deze regel wilt oplossen, voegt u deze toe FlagsAttribute aan de opsomming.

Wanneer waarschuwingen onderdrukken

Onderdrukt een waarschuwing van deze regel als u niet wilt dat de opsommingswaarden kunnen worden gecombineerd.

Een waarschuwing onderdrukken

Als u slechts één schending wilt onderdrukken, voegt u preprocessorrichtlijnen toe aan uw bronbestand om de regel uit te schakelen en vervolgens opnieuw in te schakelen.

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

Als u de regel voor een bestand, map of project wilt uitschakelen, stelt u de ernst none ervan in op het configuratiebestand.

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

Zie Codeanalysewaarschuwingen onderdrukken voor meer informatie.

Code configureren om te analyseren

Gebruik de volgende optie om te configureren op welke onderdelen van uw codebase deze regel moet worden uitgevoerd.

U kunt deze optie configureren voor alleen deze regel, voor alle regels waarop deze van toepassing is, of voor alle regels in deze categorie (ontwerp) waarop deze van toepassing is. Zie de configuratieopties voor de codekwaliteitsregel voor meer informatie.

Specifieke API-oppervlakken opnemen

U kunt instellen op welke onderdelen van uw codebase deze regel moet worden uitgevoerd, op basis van hun toegankelijkheid. Als u bijvoorbeeld wilt opgeven dat de regel alleen moet worden uitgevoerd op het niet-openbare API-oppervlak, voegt u het volgende sleutel-waardepaar toe aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Voorbeeld

In het volgende voorbeeld DaysEnumNeedsFlags is een opsomming die voldoet aan de vereisten voor het gebruik FlagsAttribute , maar deze niet heeft. De ColorEnumShouldNotHaveFlag opsomming heeft geen waarden die bevoegdheden van twee zijn, maar onjuist specificeert FlagsAttribute. Dit is in strijd met de regel CA2217: Markeer geen opsommingen met 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
}

Zie ook