CA1700:不要命名“Reserved”枚举值

  • 项目
属性 值
规则 ID CA1700
标题 不要命名“Reserved”枚举值
类别 命名
修复是中断修复还是非中断修复 重大
在 .NET 8 中默认启用 否

原因

枚举成员的名称包含单词“reserved”。

规则说明

此规则假定当前不使用名称中包含“reserved”的枚举成员，而是将其作为一个占位符，以在将来的版本中重命名或移除它。 重命名或移除成员是一项重大更改。 不应期望用户仅因为成员名称包含“reserved”而忽略该成员，也不能指望用户阅读或遵守文档。 此外，由于预留成员显示在对象浏览器和智能集成开发环境中，因此他们可能会造成混淆，以致于不知道实际使用哪些成员。

在将来的版本中，向枚举添加新成员，而不是使用预留成员。 在大多数情况下，只要添加新成员不会导致原始成员的值发生变化，添加新成员就不是一项中断性变更。

在少数情况下，添加成员是一项中断性变更，即使原始成员保留其原始值也是如此。 主要问题是，如果不中断对包含整个成员列表的返回值使用 switch（在 Visual Basic 中为 Select）语句并且在默认情况下引发异常的调用方，则不能从现有代码路径返回新成员。 第二个问题是客户端代码可能无法处理反射方法（如 System.Enum.IsDefined）的行为更改。 因此，如果新成员必须从现有方法返回，或者由于反射的使用不当而发生已知的应用程序不兼容，则唯一的非中断性解决方案是：

  1. 添加包含原始成员和新成员的新枚举。

  2. 使用 System.ObsoleteAttribute 属性标记原始枚举。

    对于公开原始枚举的任何外部可见类型或成员，请执行相同的过程。

如何解决冲突

若要解决此规则的冲突，请删除或重命名该成员。

何时禁止显示警告

对于当前使用的成员或以前发布的库，可以安全地禁止显示此规则发出的警告。

抑制警告

如果只想抑制单个冲突，请将预处理器指令添加到源文件以禁用该规则，然后重新启用该规则。

#pragma warning disable CA1700
// The code that's violating the rule is on this line.
#pragma warning restore CA1700

若要对文件、文件夹或项目禁用该规则，请在配置文件中将其严重性设置为 none。

[*.{cs,vb}]
dotnet_diagnostic.CA1700.severity = none

有关详细信息，请参阅如何禁止显示代码分析警告。

配置代码以进行分析

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

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

包含特定的 API 图面

你可以根据代码库的可访问性，配置要针对其运行此规则的部分。 例如，若要指定规则应仅针对非公共 API 图面运行，请将以下键值对添加到项目中的 .editorconfig 文件：

dotnet_code_quality.CAXXXX.api_surface = private, internal

CA2217:不要使用 FlagsAttribute 标记枚举

CA1712:不要将类型名用作枚举值的前缀

CA1028:枚举存储应为 Int32

CA1008:枚举应具有零值

CA1027:用 FlagsAttribute 标记枚举