CA1717: Nur FlagsAttribute-Enumerationen sollten Pluralnamen aufweisen.

  • Artikel
Eigenschaft Wert
Regel-ID CA1717
Titel Nur FlagsAttribute-Enumerationen sollten Pluralnamen aufweisen.
Kategorie Benennung
Fix führt oder führt nicht zur Unterbrechung Breaking
Standardmäßig in .NET 8 aktiviert Nein

Ursache

Der Name einer Enumeration endet mit einem Pluralwort, und die Enumeration ist nicht mit dem Attribut System.FlagsAttribute gekennzeichnet.

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

Regelbeschreibung

Gemäß den Benennungskonventionen gibt ein Pluralname für eine Enumeration an, dass für diese mehrere Werte gleichzeitig angegeben werden können. Der Compiler wird durch FlagsAttribute angewiesen, dass die Enumeration als Bitfeld behandelt werden soll, das bitweise Operationen für die Enumeration ermöglicht.

Wenn nur ein Wert einer Enumeration gleichzeitig angegeben werden kann, sollte der Name der Enumeration ein Singularwort sein. Beispielsweise kann eine Enumeration, die die Wochentage definiert, für die Verwendung in einer Anwendung vorgesehen sein, in der Sie mehrere Tage angeben können. Diese Enumeration sollte das Attribut FlagsAttribute aufweisen und könnte „Tage“ heißen. Eine ähnliche Enumeration, mit der nur ein Tag angegeben werden kann, würde dieses Attribut nicht aufweisen, und könnte „Tag“ heißen.

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

Behandeln von Verstößen

Ändern Sie den Namen der Enumeration in ein Singularwort, oder fügen Sie FlagsAttribute hinzu.

Wann sollten Warnungen unterdrückt werden?

Wenn der Name mit einem Singularwort endet, kann eine Warnung dieser Regel bedenkenlos unterdrückt werden.

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

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.CA1717.severity = none

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

Konfigurieren des zu analysierenden Codes

Mithilfe der folgenden Option können Sie konfigurieren, für welche Teile Ihrer Codebasis diese Regel ausgeführt werden soll.

Sie können diese Option 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

Siehe auch