CA1710: идентификаторы должны иметь правильные суффиксы
| Свойство | Значение |
|---|---|
| Идентификатор правила | CA1710 |
| Заголовок | Идентификаторы должны иметь правильные суффиксы |
| Категория | Именование |
| Исправление является критическим или не критическим | Критическое |
| Включен по умолчанию в .NET 9 | No |
Причина
В идентификаторе отсутствует правильный суффикс.
По умолчанию это правило проверяет только видимые извне идентификаторы, но это поведение можно настроить.
Описание правила
По соглашению имена типов, расширяющих определенные базовые типы или реализующих определенные интерфейсы, а также типов, являющихся производными от первых, имеют суффикс, связанный с базовым типом или интерфейсом.
Соглашения об именовании обеспечивают единство вида библиотек, предназначенных для среды CLR. Это сокращает время, необходимое для изучения новых библиотек программного обеспечения, и позволяет клиентам увериться в том, что разработчик библиотеки имеет опыт разработки управляемого кода.
В следующей таблице перечислены базовые типы и интерфейсы, имеющие связанные суффиксы.
| Базовый тип или интерфейс | Суффикс |
|---|---|
| System.Attribute | Attribute |
| System.EventArgs | EventArgs |
| System.Exception | Exception |
| System.Collections.ICollection | Collection |
| System.Collections.IDictionary | Dictionary |
| System.Collections.IEnumerable | Collection |
| System.Collections.Generic.IReadOnlyDictionary<TKey,TValue> | Dictionary |
| System.Collections.Queue |
Collection или Queue |
| System.Collections.Stack |
Collection или Stack |
| System.Collections.Generic.ICollection<T> | Collection |
| System.Collections.Generic.IDictionary<TKey,TValue> | Dictionary |
| System.Data.DataSet | DataSet |
| System.Data.DataTable |
Collection или DataTable |
| System.IO.Stream | Stream |
| System.Security.IPermission | Permission |
| System.Security.Policy.IMembershipCondition | Condition |
| Делегат обработчика событий. | EventHandler |
Для типов, реализующих ICollection и являющихся обобщенными типами структуры данных, таких как словарь, стек или очередь, допускаются имена, которые предоставляют значимую информацию о предполагаемом использовании типа.
Типы, реализующие ICollection и являются коллекцией определенных элементов, имеют имена, заканчивающиеся словом Collection. Например, коллекция объектов Queue будет иметь имя QueueCollection. Суффикс Collection означает, что элементы коллекции можно перечислить с помощью инструкции foreach (For Each в Visual Basic).
Типы, реализующие IDictionary или IReadOnlyDictionary<TKey,TValue>, имеют имена, заканчивающиеся словом Dictionary даже если тип также реализует IEnumerable или ICollection. Соглашения об именовании Collection и Dictionary позволяют пользователям различать следующие два шаблона перечисления.
Типы с суффиксом Collection соответствуют этому шаблону перечисления.
foreach(SomeType x in SomeCollection) { }
Типы с суффиксом Dictionary соответствуют этому шаблону перечисления.
foreach(SomeType x in SomeDictionary.Values) { }
В объект DataSet входит коллекция объектов DataTable, которая, в свою очередь, содержит среди прочих коллекции объектов System.Data.DataColumn и System.Data.DataRow. Эти коллекции реализуют ICollection посредством базового класса System.Data.InternalDataCollectionBase.
Устранение нарушений
Переименуйте тип так, чтобы он заканчивался правильным термином.
Когда лучше отключить предупреждения
Предупреждение можно отключить для использования суффикса Collection, если тип является обобщенной структурой данных, которая может быть расширена или будет содержать произвольный набор различных элементов. В таком случае имя, предоставляющее значимую информацию о применении, производительности или других характеристиках структуры данных, может быть осмысленным (например, BinaryTree). В случаях, когда тип представляет коллекцию определенного типа (например, StringCollection), не следует отключать предупреждение из этого правила, так как суффикс указывает, что этот тип может быть перечислен с помощью инструкции foreach.
Для других суффиксов не следует отключать предупреждение из этого правила. Суффикс позволяет понять предполагаемое использование из имени типа.
Отключение предупреждений
Если вы просто хотите отключить одно нарушение, добавьте директивы препроцессора в исходный файл, чтобы отключить и повторно включить правило.
#pragma warning disable CA1710
// The code that's violating the rule is on this line.
#pragma warning restore CA1710
Чтобы отключить правило для файла, папки или проекта, задайте его серьезность none в файле конфигурации.
[*.{cs,vb}]
dotnet_diagnostic.CA1710.severity = none
Дополнительные сведения см. в разделе Практическое руководство. Скрытие предупреждений анализа кода.
Настройка кода для анализа
Используйте следующие параметры, чтобы указать части базы кода, к которым будет применяться это правило.
- Включение определенных контактных зон API
- Исключить косвенные базовые типы
- Дополнительные обязательные суффиксы
Эти параметры можно настроить только для этого правила, для всех правил, к которым они применяются, или для всех правил в этой категории (именования), к которым они применяются. Дополнительные сведения см. в статье Параметры конфигурации правила качества кода.
Включение определенных контактных зон API
Вы можете настроить компоненты базы кода для выполнения этого правила на основе их специальных возможностей, задав параметр api_surface. Например, чтобы указать, что правило должно выполняться только для закрытой контактной зоны API, добавьте следующую пару "ключ-значение" в файл EDITORCONFIG в своем проекте:
dotnet_code_quality.CAXXXX.api_surface = private, internal
Заметка
Замените XXXX частью CAXXXX идентификатором применимого правила.
Исключить косвенные базовые типы
Вы можете указать, следует ли исключать из правила косвенные базовые типы. По умолчанию этот параметр имеет значение true, что означает, что анализ ограничен текущим базовым типом.
dotnet_code_quality.CA1710.exclude_indirect_base_types = false
Дополнительные обязательные суффиксы
Вы можете указать дополнительные обязательные суффиксы или переопределить поведение некоторых жестко заданных суффиксов, добавив следующую пару "ключ-значение" в файл с расширением .editorconfig в своем проекте:
dotnet_code_quality.CA1710.additional_required_suffixes = [type]->[suffix]
Для разделения значений используйте символ |. Типы можно указывать в одном из следующих форматов:
- Только имя типа (включает все типы с этим именем, любого типа и в любом пространстве имен).
- Полные имена в формате идентификатора документации для символа с необязательным префиксом
T:.
Примеры:
| Значение параметра | Итоги |
|---|---|
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class |
Все типы, наследующие от "MyClass", должны иметь суффикс "Class". |
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class|MyNamespace.IPath->Path |
Все типы, наследующие от "MyClass", должны иметь суффикс "Class", и все типы, реализующие "MyNamespace.IPath", должны иметь суффикс "Path". |
dotnet_code_quality.CA1710.additional_required_suffixes = T:System.Data.IDataReader->{} |
Переопределяет встроенные суффиксы. В данном случае все типы, реализующие "IDataReader", больше не обязаны иметь суффикс "Collection". |
Связанные правила
CA1711: идентификаторы не должны иметь неверных суффиксов
