Freigeben über

CA1711: Bezeichner sollten kein falsches Suffix aufweisen.

  • Artikel
Eigenschaft Wert
Regel-ID CA1711
Titel Bezeichner sollten kein falsches Suffix aufweisen.
Kategorie Benennung
Fix is breaking or non-breaking Breaking
Standardmäßig in .NET 9 aktiviert Nein

Ursache

Ein Bezeichner weist ein falsches Suffix auf.

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

Regelbeschreibung

Nur die Namen von Typen, die bestimmte Basistypen erweitern oder bestimmte Schnittstellen bzw. Typen implementieren, die von diesen Typen abgeleitet werden, sollten stets mit bestimmten reservierten Suffixen enden. Für andere Typnamen sollten diese reservierten Suffixe nicht verwendet werden.

In der folgenden Tabelle werden die reservierten Suffixe sowie die Basistypen und die Schnittstellen aufgeführt, denen die Suffixe zugeordnet sind.

Suffix Basistyp/Schnittstelle
Attribute System.Attribute
Collection System.Collections.ICollection

System.Collections.IEnumerable

System.Collections.Queue

System.Collections.Stack

System.Collections.Generic.ICollection<T>

System.Data.DataSet

System.Data.DataTable
Dictionary System.Collections.IDictionary

System.Collections.Generic.IDictionary<TKey,TValue>
EventArgs System.EventArgs
EventHandler Ein Ereignishandlerdelegat.
Exception System.Exception
Permission System.Security.IPermission
Queue System.Collections.Queue
Stack System.Collections.Stack
Stream System.IO.Stream

Außerdem sollten die folgenden Suffixe nicht verwendet werden:

  • Delegate
  • Enum
  • Ex oder ein ähnliches Suffix zur Unterscheidung von einer früheren Version desselben Typs
  • Flag oder Flags für Enum-Typen
  • Impl (verwenden Sie stattdessen Core)
  • New, wenn ein Element mit demselben Namen, aber ohne das suffix New bereits vorhanden ist

Benennungskonventionen bieten eine allgemeine Suche nach Bibliotheken, die auf die .NET Common Language Runtime abzielen. Diese Konventionen reduzieren die Lernkurve, die für neue Softwarebibliotheken erforderlich ist, und erhöhen Sie das Vertrauen der Kunden, dass die Bibliothek von jemandem entwickelt wurde, der über Kenntnisse bei der Entwicklung von verwaltetem Code verfügt. Weitere Informationen finden Sie unter Benennungsrichtlinien: Klassen, Strukturen und Schnittstellen.

So beheben Sie Verstöße

Entfernen Sie das Suffix aus dem Typnamen.

Wann sollten Warnungen unterdrückt werden?

Unterdrücken Sie keine Warnung dieser Regel, es sei denn, das Suffix hat eine eindeutige Bedeutung in der Anwendungsdomäne.

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 CA1711
// The code that's violating the rule is on this line.
#pragma warning restore CA1711

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

[*.{cs,vb}]
dotnet_diagnostic.CA1711.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 konfigurieren, für alle Regeln, auf die sie angewendet werden, oder für alle Regeln auf die sie in dieser Kategorie (Benennung) angewendet werden. Weitere Informationen finden Sie unter Konfigurationsoptionen für die Codequalitätsregel.

Bestimmte API-Schnittstellen einbeziehen

Sie können konfigurieren, auf welchen Teilen Ihrer Codebasis je nach Barrierefreiheit diese Regel ausgeführt werden soll, indem Sie die Option api_surface festlegen. 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.

Suffixe zulassen

Sie können eine Liste zulässiger Suffixe konfigurieren. Darin wird jedes Suffix durch einen senkrechten Strich („|“) getrennt. Sie können beispielsweise festlegen, dass die Regel nicht gegen Flags und deren Suffixe ausgeführt werden soll, indem Sie einer .editorconfig-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzufügen:

dotnet_code_quality.ca1711.allowed_suffixes = Flag|Flags

Siehe auch