CA1027: Oznaczaj wyliczenia za pomocą FlagsAttribute
Właściwości | Wartość |
---|---|
Identyfikator reguły | CA1027 |
Tytuł | Oznacz typy wyliczeniowe atrybutem Flags |
Kategoria | Projekt |
Poprawka powodująca niezgodność lub niezgodność | Niezgodność |
Domyślnie włączone na platformie .NET 9 | Nie. |
Przyczyna
Wartości wyliczenia są uprawnieniami dwóch lub są kombinacjami innych wartości zdefiniowanych w wyliczaniu, a System.FlagsAttribute atrybut nie jest obecny. Aby zmniejszyć liczbę wyników fałszywie dodatnich, ta reguła nie zgłasza naruszenia wyliczenia, które mają ciągłe wartości.
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ć znacząco łą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 wyliczenia dla magazynu w polu bitowym, użyj operatorów warunkowych logicznych. Aby przetestować pole bitowe w celu określenia, czy istnieje określona wartość wyliczenia, użyj operatorów logicznych logicznych. Dla pola bitowego do prawidłowego przechowywania i pobierania połączonych wartości wyliczania każda wartość zdefiniowana w wyliczenie musi być mocą dwóch. Jeśli tak nie jest, operatory logiczne logiczne 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 bazy kodu mają być uruchamiane w tej regule.
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ć, które części bazy kodu mają być uruchamiane na podstawie ich ułatwień 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
Nuta
Zastąp część XXXX
CAXXXX
identyfikatorem odpowiedniej reguły.
Przykład
W poniższym przykładzie DaysEnumNeedsFlags
jest to wyliczenie spełniające wymagania dotyczące używania FlagsAttribute , ale nie ma go. Wyliczenie ColorEnumShouldNotHaveFlag
nie ma wartości, które są uprawnieniami dwóch, ale niepoprawnie określa FlagsAttributewartość . 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
}