CA1027: Enumerationen mit FlagsAttribute markieren.

  • Artikel
Eigenschaft Wert
Regel-ID CA1027
Titel Enumerationen mit FlagsAttribute markieren.
Kategorie Design
Fix führt oder führt nicht zur Unterbrechung Nicht unterbrechend
Standardmäßig in .NET 8 aktiviert Nein

Ursache

Die Werte einer Enumeration sind zwei oder Kombinationen aus anderen Werten, die in der Enumeration definiert sind, und das System.FlagsAttribute-Attribut ist nicht vorhanden. Um falsch positive Ergebnisse zu reduzieren, meldet diese Regel keinen Verstoß gegen Enumerationen, die zusammenhängende Werte aufweisen.

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

Regelbeschreibung

Eine Enumeration ist ein Werttyp, der einen Satz verwandter benannter Konstanten definiert. Wenden Sie FlagsAttribute auf eine Enumeration an, wenn deren benannte Konstanten sinnvoll kombiniert werden können. Stellen Sie sich z. B. eine Enumeration der Wochentage in einer Anwendung vor, die nachverfolgen, welche Tagesressourcen verfügbar sind. Wenn die Verfügbarkeit der einzelnen Ressourcen mithilfe der Enumeration mir vorhandener FlagsAttribute codiert ist, kann eine beliebige Kombination von Tagen dargestellt werden. Ohne das Attribut kann nur ein Wochentag dargestellt werden.

Für Felder, die kombinierbare Enumerationen speichern, werden die einzelnen Enumerationswerte als Gruppen von Bits im Feld behandelt. Daher werden solche Felder manchmal auch als Bitfelder bezeichnet. Verwenden Sie zum Kombinieren von Enumerationswerten für den Speicher in einem Bitfeld die booleschen bedingten Operatoren. Um ein Bitfeld zur Bestimmung, ob ein bestimmter Enumerationswert vorhanden ist, zu testen, verwenden Sie die logischen booleschen Operatoren. Damit ein Bitfeld kombinierte Enumerationswerte ordnungsgemäß speichert und abruft, muss jeder in der Enumeration definierte Wert eine Potenz von zwei sein. Falls dies nicht der Fall ist, können die logischen booleschen Operatoren die einzelnen Enumerationswerte, die im Feld gespeichert sind, nicht extrahieren.

Behandeln von Verstößen

Um einen Verstoß gegen diese Regel zu beheben, fügen Sie der Enumeration FlagsAttribute hinzu.

Wann sollten Warnungen unterdrückt werden?

Unterdrücken Sie eine Warnung aus dieser Regel, wenn Sie nicht möchten, dass die Enumerationswerte kombinierbar sind.

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

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.CA1027.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 Optionen nur für diese Regel, für alle zutreffenden Regeln oder für alle zutreffenden Regeln in dieser Kategorie (Entwurf) 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

Beispiel

Im folgenden Beispiel ist DaysEnumNeedsFlags eine Enumeration, die die Anforderungen für die Verwendung von FlagsAttribute erfüllt, jedoch nicht über diese verfügt. Die ColorEnumShouldNotHaveFlag-Enumeration weist keine Werte auf, die Zweierpotenzen sind, aber spezifiziert FlagsAttribute nicht korrekt. Dies verstößt gegen Regel CA2217: Enumerationen nicht mit FlagsAttribute markieren.

// Violates rule: MarkEnumsWithFlags.
public enum DaysEnumNeedsFlags
{
    None = 0,
    Monday = 1,
    Tuesday = 2,
    Wednesday = 4,
    Thursday = 8,
    Friday = 16,
    All = Monday | Tuesday | Wednesday | Thursday | Friday
}

// Violates rule: DoNotMarkEnumsWithFlags.
[FlagsAttribute]
public enum ColorEnumShouldNotHaveFlag
{
    None = 0,
    Red = 1,
    Orange = 3,
    Yellow = 4
}

Siehe auch