CA1027:必須以 FlagsAttribute 標記列舉

  • 發行項
屬性 值
規則識別碼 CA1027
標題 必須以 FlagsAttribute 標記列舉
類別 設計
修正程式是中斷或非中斷 不中斷
預設在 .NET 8 中啟用 No

原因

列舉的值是兩個的乘冪，或是列舉中定義之其他值的組合，而且 System.FlagsAttribute 屬性不存在。 為了減少誤判，此規則不會針對具有連續值的列舉報告違規。

根據預設，此規則只會查看外部可見的列舉，但這是可設定的。

檔案描述

列舉類型是一種實值類型 (Value Type)，用以定義一組相關的具名常數。 當具名常數可以有意義地結合時，套 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 介面執行，請將下列機碼/值組新增至 專案中的 .editorconfig 檔案：

dotnet_code_quality.CAXXXX.api_surface = private, internal

範例

在下列範例中， 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
}

另請參閱