CA1027: FlagsAttribute で列挙値をマークします

  • [アーティクル]
プロパティ 値
ルール ID CA1027
Title 列挙型を FlagsAttribute に設定します
[カテゴリ] デザイン
修正が中断ありか中断なしか なし
.NET 8 では既定で有効 いいえ

原因

列挙型の値が 2 の累乗であるか、または列挙型で定義されている他の値との組み合わせであり、System.FlagsAttribute 属性がありません。 この規則では、誤検知を減らすために、連続した値の列挙型に対して違反を報告しません。

デフォルトでは、この規則の対象は外部から参照できる列挙型のみですが、これは構成可能です。

規則の説明

列挙型は、関連する名前付き定数が複数定義された値型です。 名前付き定数を有意に結合できる場合、列挙型に FlagsAttribute を適用します。 たとえば、リソースを使用できる曜日を追跡するアプリケーションにおける、週の曜日の列挙型について考えてみます。 各リソースの可用性が、FlagsAttribute が存在する列挙型を使用してエンコードされている場合は、曜日をすべての組み合わせで表すことができます。 この属性を指定しない場合は、週の 1 つの曜日しか表すことができません。

結合可能な列挙型を格納するフィールドの場合、個々の列挙値はそのフィールドでビットのグループとして扱われます。 そのため、このようなフィールドは、"ビット フィールド" と呼ばれることもあります。 ビット フィールドに格納する列挙値の結合には、ブール条件演算子を使用します。 ビット フィールドをテストして特定の列挙値が存在するかどうかを判断するには、ブール型の論理演算子を使用します。 ビット フィールドに結合された列挙値を正しく格納および取得するには、列挙型に定義されている各値が 2 の累乗である必要があります。 そうでないと、ブール型の論理演算子は、フィールドに格納されている個々の列挙値を抽出できません。

違反の修正方法

この規則違反を修正するには、列挙型に 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 サーフェイスでのみ規則を実行するように指定するには、プロジェクトの .editorconfig ファイルに次のキーと値のペアを追加します。

dotnet_code_quality.CAXXXX.api_surface = private, internal

例

次の例で、DaysEnumNeedsFlags は FlagsAttribute を使用する要件を満たしている列挙型ですが、それを含んでいません。 ColorEnumShouldNotHaveFlag 列挙型の値は、2 の累乗ではなく、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
}

関連項目