Бөлісу құралы:

CA1027: помечайте перечисления атрибутом FlagsAttribute

Свойство Значение
Идентификатор правила CA1027
Заголовок Отметьте перечисления атрибутом FlagsAttribute
Категория Проектирование
Исправление является критическим или не критическим неразрывный
Включен по умолчанию в .NET 10 Нет
Применимые языки C# и Visual Basic

Причина

Значения перечисления — это степени двойки или сочетания других значений, определенных в перечислении. Атрибут System.FlagsAttribute отсутствует. Чтобы сократить число ложных срабатываний, это правило не сообщает о нарушениях для перечислений, имеющих непрерывные значения.

По умолчанию это правило проверяет только видимые извне перечисления, но это поведение можно настроить.

Описание правила

Перечисление является типом значения, которое определяет набор связанных именованных констант. FlagsAttribute применяется к перечислению, когда его именованные константы могут быть объединены осмысленным образом. Например, рассмотрим перечисление дней недели в приложении, которое отслеживает доступность ресурсов по дням. Если доступность каждого ресурса кодируется с помощью перечисления, где содержится атрибут FlagsAttribute, им можно представить любое сочетание дней. Без атрибута можно представить только один день недели.

Для полей, в которых хранятся комбинированные перечисления, отдельные значения перечисления обрабатываются как группы битов в поле. Поэтому такие поля иногда называют битовыми полями. Чтобы объединить значения перечисления для хранения в битовом поле, используйте логические условные операторы. Чтобы протестировать битовое поле и определить, присутствует ли определенное значение перечисления, используйте логические операторы Булева. Чтобы битовое поле могло правильно хранить и получать объединенные значения перечисления, каждое значение, определенное в перечислении, должно быть степенью двух. Если это не так, булевские логические операторы не смогут извлекать отдельные значения перечисления, которые хранятся в поле.

Устранение нарушений

Чтобы устранить нарушение этого правила, добавьте FlagsAttribute к перечислению.

Когда лучше отключить предупреждения

Скройте предупреждение о нарушении этого правила, если не нужно, чтобы значения перечисления были комбинированными.

Отключение предупреждений

Если вы просто хотите отключить одно нарушение, добавьте директивы препроцессора в исходный файл, чтобы отключить и повторно включить правило.

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

Чтобы отключить правило для файла, папки или проекта, задайте его серьезность none в файле конфигурации.

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

Дополнительные сведения см. в разделе Практическое руководство. Скрытие предупреждений анализа кода.

Настройка кода для анализа

Используйте следующий параметр, чтобы выбрать части базы кода для применения этого правила.

Этот параметр можно настроить только для этого правила, для всех правил, к которым он применяется, или для всех правил в этой категории (конструкторе), к которым она применяется. Дополнительные сведения см. в статье Параметры конфигурации правила качества кода.

Включите конкретные поверхности API

Вы можете настроить компоненты базы кода для выполнения этого правила на основе их специальных возможностей, задав параметр api_surface. Например, чтобы указать, что правило должно выполняться только для непубличной поверхности API, добавьте следующую пару "ключ-значение" в файл .editorconfig в ваш проект:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Заметка

Замените XXXX частью CAXXXX идентификатором применимого правила.

Пример

В следующем примере DaysEnumNeedsFlags — это перечисление, удовлетворяющее требованиям для использования FlagsAttribute, но не имеющее его. Перечисление ColorEnumShouldNotHaveFlag не имеет значений, которые являются степенями двух, но неправильно указывает FlagsAttribute. Это нарушает правило CA2217: не помечайте перечисляемые типы атрибутом 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
}

См. также

  • Last updated on