Muokkaa

Jaa

CA1710: Identifiers should have correct suffix

  • Artikkeli
Property Value
Rule ID CA1710
Title Identifiers should have correct suffix
Category Naming
Fix is breaking or non-breaking Breaking
Enabled by default in .NET 9 No

Cause

An identifier does not have the correct suffix.

By default, this rule only looks at externally visible identifiers, but this is configurable.

Rule description

By convention, the names of types that extend certain base types or that implement certain interfaces, or types derived from these types, have a suffix that is associated with the base type or interface.

Naming conventions provide a common look for libraries that target the common language runtime. This reduces the learning curve that is required for new software libraries, and increases customer confidence that the library was developed by someone who has expertise in developing managed code.

The following table lists the base types and interfaces that have associated suffixes.

Base type/Interface Suffix
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 or Queue
System.Collections.Stack Collection or Stack
System.Collections.Generic.ICollection<T> Collection
System.Collections.Generic.IDictionary<TKey,TValue> Dictionary
System.Data.DataSet DataSet
System.Data.DataTable Collection or DataTable
System.IO.Stream Stream
System.Security.IPermission Permission
System.Security.Policy.IMembershipCondition Condition
An event-handler delegate. EventHandler

Types that implement ICollection and are a generalized type of data structure, such as a dictionary, stack, or queue, are allowed names that provide meaningful information about the intended usage of the type.

Types that implement ICollection and are a collection of specific items have names that end with the word 'Collection'. For example, a collection of Queue objects would have the name 'QueueCollection'. The 'Collection' suffix signifies that the members of the collection can be enumerated by using the foreach (For Each in Visual Basic) statement.

Types that implement IDictionary or IReadOnlyDictionary<TKey,TValue> have names that end with the word 'Dictionary' even if the type also implements IEnumerable or ICollection. The 'Collection' and 'Dictionary' suffix naming conventions enable users to distinguish between the following two enumeration patterns.

Types with the 'Collection' suffix follow this enumeration pattern.

foreach(SomeType x in SomeCollection) { }

Types with the 'Dictionary' suffix follow this enumeration pattern.

foreach(SomeType x in SomeDictionary.Values) { }

A DataSet object consists of a collection of DataTable objects, which consist of collections of System.Data.DataColumn and System.Data.DataRow objects, among others. These collections implement ICollection through the base System.Data.InternalDataCollectionBase class.

How to fix violations

Rename the type so that it is suffixed with the correct term.

When to suppress warnings

It is safe to suppress a warning to use the 'Collection' suffix if the type is a generalized data structure that might be extended or that will hold an arbitrary set of diverse items. In this case, a name that provides meaningful information about the implementation, performance, or other characteristics of the data structure might make sense (for example, BinaryTree). In cases where the type represents a collection of a specific type (for example, StringCollection), do not suppress a warning from this rule because the suffix indicates that the type can be enumerated by using a foreach statement.

For other suffixes, do not suppress a warning from this rule. The suffix allows the intended usage to be evident from the type name.

Suppress a warning

If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.

#pragma warning disable CA1710
// The code that's violating the rule is on this line.
#pragma warning restore CA1710

To disable the rule for a file, folder, or project, set its severity to none in the configuration file.

[*.{cs,vb}]
dotnet_diagnostic.CA1710.severity = none

For more information, see How to suppress code analysis warnings.

Configure code to analyze

Use the following options to configure which parts of your codebase to run this rule on.

You can configure these options for just this rule, for all rules it applies to, or for all rules in this category (Naming) that it applies to. For more information, see Code quality rule configuration options.

Include specific API surfaces

You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an .editorconfig file in your project:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Exclude indirect base types

You can configure whether to exclude indirect base types from the rule. By default, this option is set to true, which restricts analysis to the current base type.

dotnet_code_quality.CA1710.exclude_indirect_base_types = false

Additional required suffixes

You can provide additional required suffixes or override the behavior of some hardcoded suffixes by adding the following key-value pair to an .editorconfig file in your project:

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

Separate multiple values with a | character. Types can be specified in either of the following formats:

  • Type name only (includes all types with the name, regardless of the containing type or namespace).
  • Fully qualified names in the symbol's documentation ID format with an optional T: prefix.

Examples:

Option Value Summary
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class All types that inherit from 'MyClass' are required to have the 'Class' suffix.
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class|MyNamespace.IPath->Path All types that inherit from 'MyClass' are required to have the 'Class' suffix AND all types that implement 'MyNamespace.IPath' are required to have the 'Path' suffix.
dotnet_code_quality.CA1710.additional_required_suffixes = T:System.Data.IDataReader->{} Overrides built-in suffixes. In this case, all types that implement 'IDataReader' are no longer required to end in 'Collection'.

CA1711: Identifiers should not have incorrect suffix

See also