CA1027:用 FlagsAttribute 标记枚举

项

“值”

RuleId

CA1027

类别

设计

修复是中断修复还是非中断修复

非中断

原因

枚举的值是两个值的幂或枚举中定义的其他值的组合，且不存在 System.FlagsAttribute 属性。 为了减少误报，此规则不对具有连续值的枚举报告冲突。

默认情况下，此规则仅查看外部可见的枚举，但这是可配置的。

规则说明

枚举是一种值类型，它定义一组相关的已命名常数。 如果可以按照有意义的方式组合一个枚举的已命名常数，则对该枚举应用 FlagsAttribute。 例如，考虑应用程序中一周中各天的枚举，该枚举会跟踪可用的日期。 如果使用包含 FlagsAttribute 的枚举对每个资源的可用性进行编码，则可以表示天数的任意组合。 如果没有该属性，则只能表示一周中的某一天。

对于存储可组合枚举的字段，可将单个枚举值视为字段中的位组。 因此，有时称此类字段为“位字段”。 若要组合枚举值，以存储在位字段中，请使用布尔条件运算符。 若要测试位字段，以确定是否存在特定的枚举值，请使用布尔逻辑运算符。 若要正确存储位字段并检索组合枚举值，那么枚举中定义的每个值必须是两个值的幂。 若非如此，布尔逻辑运算符将无法提取存储在字段中的各个枚举值。

如何解决冲突

若要解决此规则的冲突，请向枚举添加 FlagsAttribute。

何时禁止显示警告

如果不希望组合枚举值，请禁止显示此规则发出的警告。

抑制警告

可以通过多种方式来禁止显示代码分析警告，包括禁用项目的规则、使用预处理器指令为特定代码行禁用该规则或应用 SuppressMessageAttribute 特性。 有关详细信息，请参阅如何禁止显示代码分析警告。

配置代码以进行分析

使用下面的选项来配置代码库的哪些部分要运行此规则。

包含特定的 API 图面

你可以仅为此规则、为所有规则或为此类别中的所有规则配置此选项（设计）。 有关详细信息，请参阅代码质量规则配置选项。

包含特定的 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

}

相关规则

CA2217:不要使用 FlagsAttribute 标记枚举

另请参阅

System.FlagsAttribute