CA1027：必須以 FlagsAttribute 標記列舉

型別名稱	MarkEnumsWithFlags
CheckId	CA1027
分類	Microsoft.Design
中斷變更	中斷

原因

公用列舉的值是二的次方或在列舉中定義之其他值的組合，而且沒有 System.FlagsAttribute 屬性 (Attribute)。 為了要減少誤報情形，此規則不會針對具有連續值的列舉報告違規。

規則描述

列舉型別是一種實值型別 (Value Type)，用以定義一組相關的具名常數。 當列舉型別的具名常數可以有意義地加以結合時，會將 FlagsAttribute 套用至此列舉型別。 例如，在追蹤哪一天資源可用的應用程式中，考慮星期天數的列舉。 如果每個資源的可用性都是使用具有 FlagsAttribute 的列舉予以編碼，則可以代表任何天數組合。 沒有這個屬性，則只可表示星期的其中一天。

對於儲存可組合列舉的欄位而言，個別的列舉值會被視為欄位中的位元群組。 因此，此種欄位有時候就是指「位元欄位」(Bit Field)。 若要結合儲存在位元欄位中的列舉值，請使用布林 (Boolean) 條件運算子。 若要測試位元欄位，判斷特定列舉值是否存在，請使用布林邏輯運算子。 若要使用位元欄位正確儲存和擷取結合的列舉值，列舉中所定義的每個值都必須為二的次方。 除非情況如此，否則布林邏輯運算子就無法抽取欄位中所儲存的個別列舉值。

如何修正違規

若要修正此規則的違規情形，請將 FlagsAttribute 加入至列舉型別。

隱藏警告的時機

如果您不想讓列舉值結合，請隱藏這項規則的警告。

範例

在下列範例中，DaysEnumNeedsFlags 為符合使用 FlagsAttribute 之需求的列舉型別 (但並不具有此屬性)。 ColorEnumShouldNotHaveFlag 列舉型別沒有為二的次方值，但卻錯誤地指定 FlagsAttribute。 這會違反CA2217：不要以 FlagsAttribute 標記列舉的規則。

using System;

namespace DesignLibrary
{
// 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
   }
}

相關規則

CA2217：不要以 FlagsAttribute 標記列舉

請參閱

參考

System.FlagsAttribute