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