แก้ไข

แชร์ผ่าน


CA1700: Do not name enum values 'Reserved'

Property Value
Rule ID CA1700
Title Do not name enum values 'Reserved'
Category Naming
Fix is breaking or non-breaking Breaking
Enabled by default in .NET 8 No

Cause

The name of an enumeration member contains the word "reserved".

Rule description

This rule assumes that an enumeration member that has a name that contains "reserved" is not currently used but is a placeholder to be renamed or removed in a future version. Renaming or removing a member is a breaking change. You should not expect users to ignore a member just because its name contains "reserved", nor can you rely on users to read or abide by documentation. Furthermore, because reserved members appear in object browsers and smart integrated development environments, they can cause confusion about which members are actually being used.

Instead of using a reserved member, add a new member to the enumeration in the future version. In most cases the addition of the new member is not a breaking change, as long as the addition does not cause the values of the original members to change.

In a limited number of cases the addition of a member is a breaking change even when the original members retain their original values. Primarily, the new member cannot be returned from existing code paths without breaking callers that use a switch (Select in Visual Basic) statement on the return value that encompasses the whole member list and that throw an exception in the default case. A secondary concern is that client code might not handle the change in behavior from reflection methods such as System.Enum.IsDefined. Accordingly, if the new member has to be returned from existing methods or a known application incompatibility occurs because of poor reflection usage, the only nonbreaking solution is to:

  1. Add a new enumeration that contains the original and new members.

  2. Mark the original enumeration with the System.ObsoleteAttribute attribute.

    Follow the same procedure for any externally visible types or members that expose the original enumeration.

How to fix violations

To fix a violation of this rule, remove or rename the member.

When to suppress warnings

It is safe to suppress a warning from this rule for a member that is currently used or for libraries that have previously shipped.

Suppress a warning

If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.

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

To disable the rule for a file, folder, or project, set its severity to none in the configuration file.

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

For more information, see How to suppress code analysis warnings.

Configure code to analyze

Use the following option to configure which parts of your codebase to run this rule on.

You can configure this option for just this rule, for all rules it applies to, or for all rules in this category (Naming) that it applies to. For more information, see Code quality rule configuration options.

Include specific API surfaces

You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an .editorconfig file in your project:

dotnet_code_quality.CAXXXX.api_surface = private, internal

CA2217: Do not mark enums with FlagsAttribute

CA1712: Do not prefix enum values with type name

CA1028: Enum storage should be Int32

CA1008: Enums should have zero value

CA1027: Mark enums with FlagsAttribute