CA1710: Bezeichner sollten ein richtiges Suffix aufweisen.

  • Artikel
Eigenschaft Wert
Regel-ID CA1710
Titel Bezeichner sollten ein richtiges Suffix aufweisen.
Kategorie Benennung
Fix führt oder führt nicht zur Unterbrechung Breaking
Standardmäßig in .NET 8 aktiviert Nein

Ursache

Ein Bezeichner weist nicht das richtige Suffix auf.

Standardmäßig werden mit dieser Regel nur extern sichtbare Bezeichner überprüft, aber dies ist konfigurierbar.

Regelbeschreibung

Die Namen von Typen, die bestimmte Basistypen erweitern oder bestimmte Schnittstellen implementieren, bzw. von diesen Typen abgeleitete Typen weisen stets ein Suffix auf, das mit dem Basistyp oder der Schnittstelle verknüpft ist.

Durch Benennungskonventionen erhalten Bibliotheken, die auf die Common Language Runtime abzielen, ein einheitliches Erscheinungsbild. Dadurch wird der Lernaufwand für neue Softwarebibliotheken verringert. Zudem wird das Kundenvertrauen dahingehend gestärkt, dass die Bibliothek von einem erfahrenen Entwickler für verwalteten Code erstellt wurde.

In der folgenden Tabelle werden die Basistypen und Schnittstellen aufgelistet, denen Suffixe zugeordnet sind.

Basistyp/Schnittstelle Suffix
System.Attribute attribute
System.EventArgs EventArgs
System.Exception Ausnahme
System.Collections.ICollection Sammlung
System.Collections.IDictionary Wörterbuch
System.Collections.IEnumerable Sammlung
System.Collections.Generic.IReadOnlyDictionary<TKey,TValue> Wörterbuch
System.Collections.Queue Sammlung oder Warteschlange
System.Collections.Stack Sammlung oder Stapel
System.Collections.Generic.ICollection<T> Sammlung
System.Collections.Generic.IDictionary<TKey,TValue> Wörterbuch
System.Data.DataSet Dataset
System.Data.DataTable Sammlung oder Datentabelle
System.IO.Stream Datenstrom
System.Security.IPermission Berechtigung
System.Security.Policy.IMembershipCondition Bedingung
Ein Ereignishandlerdelegat. EventHandler

Typen, die ICollection implementieren und einen generalisierten Typ von Datenstruktur wie z. B. Wörterbuch, Stapel oder Warteschlange darstellen, dürfen Namen aufweisen, die aussagekräftige Informationen zur beabsichtigten Verwendung des Typs bereitstellen.

Typen, die ICollection implementieren und eine Sammlung bestimmter Elemente darstellen, enden mit dem Wort „Collection“. Eine Sammlung von Queue-Objekten würde beispielsweise den Namen „QueueCollection“ aufweisen. Das Suffix „Collection“ bedeutet, dass die Member der Sammlung mithilfe der foreach-Anweisung (For Each in Visual Basic) aufgelistet werden können.

Namen von Typen, die IDictionary oder IReadOnlyDictionary<TKey,TValue> implementieren, enden auch dann auf das Wort „Dictionary“, wenn der jeweilige Typ außerdem IEnumerable oder ICollection implementiert. Durch die Namenskonventionen mit den Suffixen „Collection“ und „Dictionary“ können Benutzer zwischen den folgenden beiden Enumerationsmustern unterscheiden.

Typen mit dem Suffix „Collection“ folgen diesem Enumerationsmuster.

foreach(SomeType x in SomeCollection) { }

Typen mit dem Suffix „Dictionary“ folgen diesem Enumerationsmuster.

foreach(SomeType x in SomeDictionary.Values) { }

Ein DataSet-Objekt besteht aus einer Sammlung von DataTable-Objekten, die unter anderem aus Sammlungen von System.Data.DataColumn- und System.Data.DataRow-Objekten bestehen. Diese Sammlungen implementieren ICollection über die System.Data.InternalDataCollectionBase-Basisklasse.

Behandeln von Verstößen

Benennen Sie den Typ so um, dass er den richtigen Begriff als Suffix aufweist.

Wann sollten Warnungen unterdrückt werden?

Eine Warnung zur Verwendung des Suffixes „Collection“ kann sicher unterdrückt werden, wenn der Typ eine generalisierte Datenstruktur darstellt, die erweitert werden kann oder einen beliebigen Satz unterschiedlicher Elemente enthalten wird. In diesem Fall kann es sinnvoll sein, einen Namen zu wählen, der aussagekräftige Informationen zur Implementierung, zur Leistung oder zu anderen Merkmalen der Datenstruktur liefert (z. B. BinaryTree). In Fällen, in denen der Typ eine Sammlung eines bestimmten Typs (z. B. StringCollection) darstellt, dürfen Sie Warnungen dieser Regel nicht unterdrücken, weil das Suffix angibt, dass der Typ mithilfe einer foreach-Anweisung aufgelistet werden kann.

Bei anderen Suffixen dürfen die Warnungen dieser Regel nicht unterdrückt werden. Das Suffix ermöglicht, dass die beabsichtigte Verwendung aus dem Typnamen ersichtlich ist.

Unterdrücken einer Warnung

Um nur eine einzelne Verletzung zu unterdrücken, fügen Sie der Quelldatei Präprozessoranweisungen hinzu, um die Regel zu deaktivieren und dann wieder zu aktivieren.

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

Um die Regel für eine Datei, einen Ordner oder ein Projekt zu deaktivieren, legen Sie den Schweregrad in der Konfigurationsdatei auf none fest.

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

Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken von Codeanalyse-Warnungen.

Konfigurieren des zu analysierenden Codes

Mit den folgenden Optionen können Sie konfigurieren, für welche Teile Ihrer Codebasis diese Regel ausgeführt werden soll.

Sie können diese Optionen nur für diese Regel, für alle zutreffenden Regeln oder für alle zutreffenden Regeln in dieser Kategorie (Benennung) konfigurieren. Weitere Informationen finden Sie unter Konfigurationsoptionen für die Codequalitätsregel.

Einschließen bestimmter API-Oberflächen

Sie können je nach Zugänglichkeit festlegen, für welche Bestandteile Ihrer Codebasis diese Regel ausgeführt wird. Sie können beispielsweise festlegen, dass die Regel nur für die nicht öffentliche API-Oberfläche ausgeführt werden soll, indem Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzufügen:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Ausschließen indirekter Basistypen

Sie können konfigurieren, ob indirekte Basistypen von der Regel ausgeschlossen werden sollen. Standardmäßig ist diese Option auf TRUE festgelegt, wodurch die Analyse auf den aktuellen Basistyp beschränkt wird.

dotnet_code_quality.CA1710.exclude_indirect_base_types = false

Weitere erforderliche Suffixe

Sie können zusätzliche erforderliche Suffixe bereitstellen oder das Verhalten einiger hartcodierter Suffixe überschreiben, indem Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzufügen:

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

Trennen Sie mehrere Werte durch ein |-Zeichen. Typen können in einem der folgenden Formate angegeben werden:

  • Nur Typname (schließt alle Typen mit ihrem Namen ein, unabhängig vom enthaltenden Typ oder Namespace).
  • Vollqualifizierte Namen im Dokumentations-ID-Format des Symbols mit einem optionalen Präfix T:.

Beispiele:

Optionswert Zusammenfassung
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class Alle Typen, die von „MyClass“ erben, müssen das Suffix „Class“ aufweisen.
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class|MyNamespace.IPath->Path Alle Typen, die von „MyClass“ erben, müssen das Suffix „Class“ aufweisen, UND alle Typen, die „MyNamespace.IPath“ implementieren, müssen das Suffix „Path“ aufweisen.
dotnet_code_quality.CA1710.additional_required_suffixes = T:System.Data.IDataReader->{} Überschreibt integrierte Suffixe. In diesem Fall ist es nicht mehr erforderlich, dass alle Typen, die „IDataReader“ implementieren, auf „Collection“ enden.

CA1711: Bezeichner sollten kein falsches Suffix aufweisen.

Siehe auch