CA1710 : Les identificateurs doivent être dotés d'un suffixe correct

  • Article
Propriété Value
Identificateur de la règle CA1710
Titre Les identificateurs doivent être dotés d'un suffixe correct
Catégorie Dénomination
Le correctif est cassant ou non cassant Rupture
Activé par défaut dans .NET 8 Non

Cause

Un identificateur n’a pas le bon suffixe.

Par défaut, cette règle examine uniquement les identificateurs visibles en externe, mais elle est configurable.

Description de la règle

Par convention, les noms des types qui étendent certains types de base ou qui implémentent certaines interfaces, ou encore des types dérivés de ces types, présentent un suffixe associé au type de base ou à l’interface.

Les conventions de nommage fournissent une recherche commune pour les bibliothèques qui ciblent le common language runtime. Cette cohérence réduit la courbe d’apprentissage requise pour les nouvelles bibliothèques de logiciels et augmente la confiance des clients en ce qui concerne le développement de la bibliothèque par une personne qui a une expertise dans le développement de code managé.

Le tableau suivant répertorie les types de base et les interfaces qui ont des suffixes associés.

Type / interface de base Suffixe
System.Attribute Attribut
System.EventArgs EventArgs
System.Exception Exception
System.Collections.ICollection Collection
System.Collections.IDictionary Dictionnaire
System.Collections.IEnumerable Collection
System.Collections.Generic.IReadOnlyDictionary<TKey,TValue> Dictionnaire
System.Collections.Queue Collection ou file d’attente
System.Collections.Stack Collection ou pile
System.Collections.Generic.ICollection<T> Collection
System.Collections.Generic.IDictionary<TKey,TValue> Dictionnaire
System.Data.DataSet DataSet
System.Data.DataTable Collection ou DataTable
System.IO.Stream Stream
System.Security.IPermission Autorisation
System.Security.Policy.IMembershipCondition Condition
Délégué du gestionnaire d’événements. EventHandler

Les types qui implémentent ICollection et sont un type généralisé de structure de données, comme un dictionnaire, une pile ou une file d’attente, et sont des noms autorisés qui fournissent des informations significatives sur l’utilisation prévue du type.

Les types qui implémentent ICollection et sont une collection d’éléments spécifiques ont des noms qui se terminent par le mot « Collection ». Par exemple, une collection d’objets Queue aurait le nom « QueueCollection ». Le suffixe « Collection » signifie que les membres de la collection peuvent être énumérés à l’aide de l’instruction foreach (For Each en Visual Basic).

Les types qui implémentent IDictionary ou IReadOnlyDictionary<TKey,TValue> ont des noms qui se terminent par le mot « Dictionary », même si le type implémente également IEnumerable ou ICollection. Les conventions d’affectation de noms de suffixe « Collection » et « Dictionary » permettent aux utilisateurs de faire la distinction entre les deux modèles d’énumération suivants.

Les types avec le suffixe « Collection » suivent ce modèle d’énumération.

foreach(SomeType x in SomeCollection) { }

Les types avec le suffixe « Dictionary » suivent ce modèle d’énumération.

foreach(SomeType x in SomeDictionary.Values) { }

Un objet DataSet se compose d’une collection d’objets DataTable, qui comprennent notamment les collections d’objets System.Data.DataColumn et System.Data.DataRow. Ces collections implémentent ICollection via la classe de base System.Data.InternalDataCollectionBase.

Comment corriger les violations

Renommez le type afin qu’il ait le bon terme en suffixe.

Quand supprimer les avertissements

Il est possible de supprimer un avertissement pour utiliser le suffixe « Collection » si le type est une structure de données généralisée qui peut être étendue ou qui contiendra un ensemble arbitraire d’éléments divers. Dans ce cas, un nom qui fournit des informations importantes sur l’implémentation, les performances ou d’autres caractéristiques de la structure de données peut avoir un sens (par exemple, BinaryTree). Lorsque le type représente une collection d’un type spécifique (par exemple, StringCollection), ne supprimez pas d’avertissement de cette règle, car le suffixe indique que le type peut être énuméré à l’aide d’une instruction foreach.

Pour les autres suffixes, ne supprimez pas un avertissement de cette règle. Grâce au suffixe, le nom de type rend l’utilisation prévue évidente.

Supprimer un avertissement

Si vous voulez supprimer une seule violation, ajoutez des directives de préprocesseur à votre fichier source pour désactiver et réactiver la règle.

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

Pour désactiver la règle sur un fichier, un dossier ou un projet, définissez sa gravité sur none dans le fichier de configuration.

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

Pour plus d’informations, consultez Comment supprimer les avertissements de l’analyse de code.

Configurer le code à analyser

Utilisez l’option suivante pour configurer les parties de votre codebase sur lesquelles exécuter cette règle.

Vous pouvez configurer ces options pour cette règle uniquement, pour toutes les règles auxquelles elles s’appliquent ou pour toutes les règles de cette catégorie (Nommage) auxquelles elles s’appliquent. Pour plus d’informations, consultez Options de configuration des règles de qualité du code.

Inclure des surfaces d’API spécifiques

Vous pouvez configurer les parties de votre codebase sur lesquelles exécuter cette règle, en fonction de leur accessibilité. Par exemple, pour spécifier que la règle doit s’exécuter uniquement sur la surface d’API non publique, ajoutez la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

dotnet_code_quality.CAXXXX.api_surface = private, internal

Exclure les types de base indirects

Vous pouvez configurer l’exclusion des types de base indirects de la règle. Par défaut, cette option est définie sur true, ce qui limite l’analyse au type de base actuel.

dotnet_code_quality.CA1710.exclude_indirect_base_types = false

Suffixes requis supplémentaires

Vous pouvez fournir des suffixes requis supplémentaires ou remplacer le comportement de certains suffixes codés en dur en ajoutant la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

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

Séparez plusieurs valeurs par un caractère |. Les types peuvent être spécifiés dans l’un des formats suivants :

  • Nom du type uniquement (inclut tous les types avec le nom, quel que soit le type ou l’espace de noms qui les contient).
  • Les noms complets au format d’ID de documentation du symbole, avec un préfixe T: facultatif.

Exemples :

Valeur d’option Récapitulatif
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class Tous les types qui héritent de « MyClass » doivent avoir le suffixe « Class ».
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class|MyNamespace.IPath->Path Tous les types qui héritent de « MyClass » doivent avoir le suffixe « Class » ET tous les types qui implémentent « MyNamespace.IPath » doivent avoir le suffixe « Path ».
dotnet_code_quality.CA1710.additional_required_suffixes = T:System.Data.IDataReader->{} Remplace les suffixes intégrés. Dans ce cas, il n’est plus nécessaire que tous les types qui implémentent « IDataReader » se terminent par « Collection ».

CA1711 : Les identificateurs ne doivent pas porter un suffixe incorrect

Voir aussi