Megosztás a következőn keresztül:

CA1027: Számjelek megjelölése FlagsAttribute használatával

  • Cikk
Tulajdonság Érték
Szabályazonosító CA1027
Cím Számjelek megjelölése a FlagsAttribute használatával
Kategória Design
A javítás kompatibilitástörő vagy nem törik Nem törés
Alapértelmezés szerint engedélyezve a .NET 8-ban Nem

Ok

Az enumerálás értékei két hatványból állnak, vagy az enumerálásban meghatározott egyéb értékek kombinációi, és az System.FlagsAttribute attribútum nincs jelen. A hamis pozitív értékek csökkentése érdekében ez a szabály nem jelenti az egybefüggő értékekkel rendelkező enumerálások megsértését.

Alapértelmezés szerint ez a szabály csak külsőleg látható enumerálásokat tekint meg, de ez konfigurálható.

Szabály leírása

Az enumerálás olyan értéktípus, amely a kapcsolódó elnevezett állandók készletét határozza meg. Akkor alkalmazható FlagsAttribute enumerálásra, ha az elnevezett állandók értelmesen kombinálhatók. Vegyük például a hét napjainak számbavételét egy olyan alkalmazásban, amely nyomon követi, hogy mely napi erőforrások érhetők el. Ha az egyes erőforrások rendelkezésre állása a jelen lévő enumerálással FlagsAttribute van kódolva, a napok bármilyen kombinációja megjeleníthető. Az attribútum nélkül a hétnek csak egy napja jelölhető.

Az kombinálható enumerálásokat tároló mezők esetében az egyes enumerálási értékek bitcsoportokként lesznek kezelve a mezőben. Ezért az ilyen mezőket bitmezőknek is nevezik. Ha egy bitmezőbeli tároló enumerálási értékeit szeretné kombinálni, használja a logikai feltételes operátorokat. Ha egy bitmezőt szeretne tesztelni annak megállapításához, hogy egy adott számbavételi érték van-e jelen, használja a logikai operátorokat. Ahhoz, hogy egy bitmező megfelelően tárolja és lekérje a kombinált enumerálási értékeket, az enumerálásban definiált összes értéknek két hatványnak kell lennie. Ha ez nem így van, a logikai logikai operátorok nem tudják kinyerni a mezőben tárolt egyedi enumerálási értékeket.

Szabálysértések kijavítása

A szabály megsértésének kijavításához adja hozzá FlagsAttribute az enumeráláshoz.

Mikor kell letiltani a figyelmeztetéseket?

Ha nem szeretné, hogy az enumerálási értékek kombinálhatók legyenek, tiltsa le a szabály figyelmeztetését.

Figyelmeztetés mellőzése

Ha csak egyetlen szabálysértést szeretne letiltani, adjon hozzá előfeldolgozási irányelveket a forrásfájlhoz a szabály letiltásához és újbóli engedélyezéséhez.

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

Ha le szeretné tiltani egy fájl, mappa vagy projekt szabályát, állítsa annak súlyosságát none a konfigurációs fájlban.

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

További információ: Kódelemzési figyelmeztetések letiltása.

Kód konfigurálása elemzéshez

A következő beállítással konfigurálhatja, hogy a kódbázis mely részein futtassa ezt a szabályt.

Ezt a beállítást konfigurálhatja csak ehhez a szabályhoz, az összes szabályhoz, vagy az ebben a kategóriában (Tervezés) szereplő összes szabályhoz, amelyekre vonatkozik. További információ: Kódminőségi szabály konfigurációs beállításai.

Adott API-felületek belefoglalása

A kódbázis azon részeit konfigurálhatja, amelyeken futtathatja ezt a szabályt az akadálymentességük alapján. Ha például meg szeretné adni, hogy a szabály csak a nem nyilvános API-felületen fusson, adja hozzá a következő kulcs-érték párot a projekt egyik .editorconfig fájljához:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Példa

Az alábbi példában egy olyan enumerálás látható, amely megfelel a használat FlagsAttribute követelményeinek, DaysEnumNeedsFlags de nem rendelkezik vele. Az ColorEnumShouldNotHaveFlag enumerálás nem rendelkezik olyan értékekkel, amelyek két hatványból állnak, de helytelenül vannak megadva FlagsAttribute. Ez sérti a CA2217 szabályt : Ne jelölje meg a számokat a FlagsAttribute használatával.

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

Kapcsolódó információk