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

  • Статья
Свойство Значение
Идентификатор правила CA1700
Заголовок Не присваивайте перечисляемым значениям имя Reserved
Категория Именование
Исправление является критическим или не критическим Критическое
Включен по умолчанию в .NET 8 No

Причина

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

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

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

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

В ограниченном числе случаев добавление элемента является критическим изменением, даже если исходные элементы сохраняют исходные значения. В основном новый элемент не может возвращаться из существующих путей кода без нарушения вызывающих объектов, использующих оператор switch (Select в Visual Basic) для возвращаемого значения, охватывающего список всех элементов и вызывающего исключение в случае по умолчанию. Дополнительная проблема заключается в том, что клиентский код может не обрабатывать изменение в поведении из методов отражения, например 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