Freigeben über

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 9 aktiviert No

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 Exception
System.Collections.ICollection Collection
System.Collections.IDictionary Dictionary
System.Collections.IEnumerable Collection
System.Collections.Generic.IReadOnlyDictionary<TKey,TValue> Dictionary
System.Collections.Queue Collection oder Queue
System.Collections.Stack Collection oder Stack
System.Collections.Generic.ICollection<T> Collection
System.Collections.Generic.IDictionary<TKey,TValue> Dictionary
System.Data.DataSet DataSet
System.Data.DataTable Collection oder DataTable
System.IO.Stream Stream
System.Security.IPermission Permission
System.Security.Policy.IMembershipCondition Condition
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 haben. Das Suffix Collection bedeutet, dass die Mitglieder 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 mit dem 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 problemlos 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 none auf 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 Regeln, für die sie gelten, oder für alle Regeln in dieser Kategorie (Benennung), für die sie gelten, konfigurieren. Weitere Informationen finden Sie unter Konfigurationsoptionen für die Codequalitätsregel.

Einschließen bestimmter API-Oberflächen

Mit der Option api_surface können Sie festlegen, für welche Elemente Ihrer Codebasis diese Regel ausgeführt werden soll, und zwar auf der Grundlage ihrer Zugreifbarkeit. 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

Hinweis

Ersetzen Sie den XXXX-Teil von CAXXXX durch die ID der anwendbaren Regel.

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