Udostępnij za pośrednictwem

CA1027: Oznaczaj wyliczenia za pomocą FlagsAttribute

Właściwości Wartość
Identyfikator reguły CA1027
Tytuł Oznacz typy wyliczeniowe atrybutem Flags
Kategoria Projektowanie
Poprawka łamiąca lub nienaruszająca Niezgodność
Domyślnie włączone na platformie .NET 10 Nie.
Zastosowane języki C# i Visual Basic

Przyczyna

Wartości wyliczenia są potęgami liczby dwa lub są kombinacjami innych wartości zdefiniowanych w wyliczeniu, atrybut System.FlagsAttribute nie jest obecny. Aby zmniejszyć liczbę wyników fałszywie dodatnich, ta reguła nie zgłasza naruszeń dla wyliczeń, które mają wartości ciągłe.

Domyślnie ta reguła analizuje tylko widoczne zewnętrznie wyliczenia, ale można to skonfigurować.

Opis reguły

Wyliczenie to typ wartości, który definiuje zestaw powiązanych, nazwanych stałych. Zastosuj FlagsAttribute do wyliczenia, gdy jego nazwane stałe mogą być sensownie łączone. Rozważmy na przykład wyliczenie dni tygodnia w aplikacji, która śledzi dostępne zasoby dnia. Jeśli dostępność każdego zasobu jest kodowana przy użyciu wyliczenia, które ma FlagsAttribute obecne, można przedstawić dowolną kombinację dni. Bez atrybutu można przedstawić tylko jeden dzień tygodnia.

W przypadku pól, które przechowują połączone wyliczenia, poszczególne wartości wyliczenia są traktowane jako grupy bitów w polu. W związku z tym takie pola są czasami nazywane polami bitowymi. Aby połączyć wartości wyliczeniowe do przechowywania w polu bitowym, użyj operatorów logicznych. Aby przetestować pole bitowe i określić, czy istnieje określona wartość wyliczenia, użyj operatorów logicznych. Dla pola bitowego, aby prawidłowo przechowywać i pobierać połączone wartości wyliczenia, każda wartość zdefiniowana w wyliczeniu musi być potęgą dwójki. Jeśli tak nie jest, logiczne operatory nie będą mogły wyodrębnić pojedynczych wartości wyliczenia przechowywanych w polu.

Jak naprawić naruszenia

Aby naprawić naruszenie tej reguły, dodaj FlagsAttribute element do wyliczenia.

Kiedy pomijać ostrzeżenia

Pomiń ostrzeżenie z tej reguły, jeśli nie chcesz, aby wartości wyliczenia można było połączyć.

Pomijanie ostrzeżenia

Jeśli chcesz po prostu pominąć pojedyncze naruszenie, dodaj dyrektywy preprocesora do pliku źródłowego, aby wyłączyć, a następnie ponownie włączyć regułę.

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

Aby wyłączyć regułę dla pliku, folderu lub projektu, ustaw jego ważność na none w pliku konfiguracji.

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

Aby uzyskać więcej informacji, zobacz Jak pominąć ostrzeżenia dotyczące analizy kodu.

Konfigurowanie kodu do analizowania

Użyj następującej opcji, aby skonfigurować, które części kodu mają być objęte tą regułą.

Tę opcję można skonfigurować tylko dla tej reguły, dla wszystkich reguł, do których ma ona zastosowanie, lub dla wszystkich reguł w tej kategorii (Projekt), których dotyczy. Aby uzyskać więcej informacji, zobacz Opcje konfiguracji reguły jakości kodu.

Uwzględnij określone powierzchnie interfejsu API

Możesz skonfigurować, na które części bazy kodu ma być stosowana ta reguła, na podstawie ich poziomu dostępu, ustawiając opcję api_surface. Aby na przykład określić, że reguła powinna być uruchamiana tylko na powierzchni niepublicznego interfejsu API, dodaj następującą parę klucz-wartość do pliku editorconfig w projekcie:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Notatka

Zastąp część XXXXCAXXXX identyfikatorem odpowiedniej reguły.

Przykład

W poniższym przykładzie DaysEnumNeedsFlags jest wyliczeniem spełniającym wymagania do użycia FlagsAttribute, ale nie posiada go. Wyliczenie ColorEnumShouldNotHaveFlag nie ma wartości, które są potęgami dwójki, ale mimo to niepoprawnie określa FlagsAttribute. Narusza to regułę CA2217: nie oznaczaj wyliczenia za pomocą atrybutu 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
}

Zobacz też

  • Last updated on