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

属性 值
规则 ID CA1710
Title 标识符应具有正确的后缀
类别 命名
修复是中断修复还是非中断修复 突发
在 .NET 10 中默认启用 否
默认在 .NET 11 中启用 否
适用的语言 C# 和 Visual Basic

原因

标识符的后缀不正确。

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

规则说明

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

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

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

基类型/接口 后缀
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(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 等对象的集合组成)的集合组成。 这些集合通过 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_surface 选项来配置要基于可访问性对代码库的哪些部分运行此规则。 例如,若要指定规则应仅针对非公共 API 图面运行,请将以下键值对添加到项目中的 .editorconfig 文件:

dotnet_code_quality.CAXXXX.api_surface = private, internal

注意

将 XXXX 的 CAXXXX 部分替换为适用规则的 ID。

排除间接基类型

可以配置是否从规则中排除间接基类型。 默认情况下,此选项设置为 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:标识符不应有不正确的后缀

请参阅