CA1710:标识符应具有正确的后缀

  • 项目
属性 值
规则 ID CA1710
标题 标识符应具有正确的后缀
类别 命名
修复是中断修复还是非中断修复 重大
在 .NET 8 中默认启用 否

原因

标识符的后缀不正确。

默认情况下，此规则仅查看外部可见的标识符，但这是可配置的。

规则说明

按照约定，扩展某些基类型或实现某些接口的类型的名称，或者由这些类型派生的类型的名称应具有与相应基类型或接口关联的后缀。

命名约定为面向公共语言运行时的库提供通用外观。 这缩短了新软件库所需的学习曲线，让客户更加有信心，相信该库是由拥有开发托管代码专业知识的人员开发的。

下表列出了具有关联后缀的基类型和接口。

基类型/接口 Suffix
System.Attribute 属性
System.EventArgs EventArgs
System.Exception 例外
System.Collections.ICollection 集合
System.Collections.IDictionary 字典
System.Collections.IEnumerable 集合
System.Collections.Generic.IReadOnlyDictionary<TKey,TValue> 字典
System.Collections.Queue 集合或队列
System.Collections.Stack 集合或堆栈
System.Collections.Generic.ICollection<T> 集合
System.Collections.Generic.IDictionary<TKey,TValue> 字典
System.Data.DataSet 数据集
System.Data.DataTable 集合或 DataTable
System.IO.Stream Stream
System.Security.IPermission 权限
System.Security.Policy.IMembershipCondition 条件
事件处理程序委托。 EventHandler

实现 ICollection 的类型是一种通用的数据结构类型（如字典、堆栈或队列），允许在名称中包含有关该类型预期用途的有用信息。

实现 ICollection 的类型是特定项的集合，其名称以单词 Collection 结尾。 例如，Queue 对象的集合的名称会是 QueueCollection。 Collection 后缀表示通过使用 foreach（Visual Basic中的 For Each）语句，可枚举该集合中的成员。

实现 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 等对象的集合组成）的集合组成。 这些集合通过 System.Data.InternalDataCollectionBase 基类实现 ICollection。

如何解决冲突

重命名该类型，使其带有正确的字词后缀。

何时禁止显示警告

如果类型是可扩展的或将保留任意一组不同的项的通用数据结构类型，则可禁止显示使用 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 图面运行，请将以下键值对添加到项目中的 .editorconfig 文件：

dotnet_code_quality.CAXXXX.api_surface = private, internal

排除间接基类型

可以配置是否从规则中排除间接基类型。 默认情况下，此选项设置为 true，这会将分析限制为对当前的基类型执行。

dotnet_code_quality.CA1710.exclude_indirect_base_types = false

其他所需的后缀

可通过将以下键值对添加到项目中的 .editorconfig 文件，提供其他所需的后缀或重写某些硬编码的后缀的行为：

dotnet_code_quality.CA1710.additional_required_suffixes = [type]->[suffix]

用 | 这一字符来分隔多个值。 可用以下任意一种格式指定类型：

  • 仅类型名称（包括具有相应名称的所有类型，不考虑包含的类型或命名空间）
  • 完全限定的名称，使用符号的文档 ID 格式，前缀为 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:标识符应采用正确的后缀

请参阅