CA1700: не следует называть значения перечислений именем "Reserved"

Свойство	Значение
Идентификатор правила	CA1700
Заголовок	Не присваивайте перечисляемым значениям имя Reserved
Категория	Именование
Исправление является критическим или не критическим	Срочное
Включен по умолчанию в .NET 10	Нет
Применимые языки	C# и Visual Basic

Причина

Имя элемента перечисления содержит слово "reserved".

Описание правила

В данном правиле предполагается, что член перечисления, имя которого содержит слово "reserved", не используется в настоящее время, а является местозаполнителем, который будет в дальнейшем переименован или удален. Переименование или удаление члена — это критическое изменение. Не следует рассчитывать, что пользователи будут игнорировать элемент только потому, что его имя содержит "reserved", и не стоит полагаться на то, что они будут читать и следовать документации. Более того, поскольку зарезервированные элементы отображаются в обозревателях объектов и интеллектуальных интегрированных средах разработки, может возникнуть путаница относительно того, какие элементы на самом деле используются.

Вместо использования зарезервированного элемента добавьте новый элемент в перечисление в следующей версии. В большинстве случаев добавление нового элемента не является критическим изменением при условии, что добавление не приводит к изменению значений исходных элементов.

В ограниченном числе случаев добавление элемента является критическим изменением, даже если исходные элементы сохраняют исходные значения. В первую очередь, новый элемент не может быть возвращен из существующих путей кода без того, чтобы не вызвать нарушение в работе вызывающих функций, которые используют оператор switch (Select в Visual Basic) на возвращаемом значении, охватывающем весь список членов, и которые вызывают исключение в случае по умолчанию. Дополнительная проблема заключается в том, что клиентский код может не обрабатывать изменение в поведении из методов отражения, например System.Enum.IsDefined. Соответственно, если новый элемент должен возвращаться из существующих методов или известно, что несовместимость приложения возникает из-за неправильного использования отражения, единственным некритическим решением будет следующее:

1. Добавьте новое перечисление, которое содержит исходный и новый элементы.

2. Пометьте исходное перечисление атрибутом System.ObsoleteAttribute.

   Выполните ту же процедуру для всех видимых снаружи типов или членов, которые раскрывают исходное перечисление.

Устранение нарушений

Чтобы устранить нарушение этого правила, удалите или переименуйте член.

Example

// This enum violates the rule.
public enum BadPaymentStatus
{
    Pending = 0,
    Completed = 1,
    ReservedError = 2,
    Reserved = 3,
}

// This enum satisfies the rule.
public enum GoodPaymentStatus
{
    Pending = 0,
    Completed = 1,
    Error = 2,
    Unknown = 3,
}

Когда лучше отключить предупреждения

Безопасно отключить предупреждение для этого правила для элемента, который используется в настоящее время, или для библиотек, которые уже были поставлены.

Отключение предупреждений

Если вы просто хотите отключить одно нарушение, добавьте директивы препроцессора в исходный файл, чтобы отключить и повторно включить правило.

#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

Вы можете настроить компоненты базы кода для выполнения этого правила на основе их специальных возможностей, задав параметр api_surface. Например, чтобы указать, что правило должно выполняться только для непубличной поверхности API, добавьте следующую пару "ключ-значение" в файл .editorconfig в ваш проект:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Заметка

Замените XXXX частью CAXXXX идентификатором применимого правила.

Связанные правила

CA2217: не следует помечать перечисления атрибутом FlagsAttribute

CA1712: не добавляйте имя типа перед перечисляемыми значениями

CA1028: хранилище перечислений должно иметь тип Int32

CA1008: перечисляемые типы должны иметь нулевое значение

CA1027: помечайте перечисления атрибутом FlagsAttribute