CA2231: Überladen Sie den Gleichheitsoperator beim Überschreiben von ValueType.Equals.

  • Artikel
Eigenschaft Wert
Regel-ID CA2231
Titel Überladen Sie den Gleichheitsoperator beim Überschreiben von ValueType.Equals.
Kategorie Verwendung
Fix führt oder führt nicht zur Unterbrechung Nicht unterbrechend
Standardmäßig in .NET 8 aktiviert Als Vorschlag

Ursache

Ein Werttyp setzt System.Object.Equals außer Kraft, implementiert jedoch nicht den Gleichheitsoperator.

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

Regelbeschreibung

In den meisten Programmiersprachen gibt es keine Standardimplementierung des Gleichheitsoperators (==) für Werttypen. Wenn Ihre Programmiersprache Operatorüberladungen unterstützt, sollten Sie die Implementierung des Gleichheitsoperators in Erwägung ziehen. Das Verhalten sollte mit dem Verhalten von Equals identisch sein.

Der Standard-Gleichheitsoperator kann nicht in einer überladenen Implementierung des Gleichheitsoperators verwendet werden. Dies führt zu einem Stapelüberlauf. Um den Gleichheitsoperator zu implementieren, verwenden Sie in Ihrer Implementierung die Object.Equals-Methode. Beispiel:

If (Object.ReferenceEquals(left, Nothing)) Then
    Return Object.ReferenceEquals(right, Nothing)
Else
    Return left.Equals(right)
End If

if (Object.ReferenceEquals(left, null))
    return Object.ReferenceEquals(right, null);
return left.Equals(right);

Behandeln von Verstößen

Um einen Verstoß gegen diese Regel zu beheben, implementieren Sie den Gleichheitsoperator.

Wann sollten Warnungen unterdrückt werden?

Es ist sicher, eine Warnung aus dieser Regel zu unterdrücken. Es wird jedoch empfohlen, nach Möglichkeit den Gleichheitsoperator zu nutzen.

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

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.CA2231.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 (Verwendung) 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

Das folgende Beispiel zeigt einen Typ, der gegen diese Regel verstößt:

public struct PointWithoutHash
{
    private int x, y;

    public PointWithoutHash(int x, int y)
    {
        this.x = x;
        this.y = y;
    }

    public override string ToString()
    {
        return String.Format("({0},{1})", x, y);
    }

    public int X { get { return x; } }

    public int Y { get { return x; } }

    // Violates rule: OverrideGetHashCodeOnOverridingEquals.
    // Violates rule: OverrideOperatorEqualsOnOverridingValueTypeEquals.
    public override bool Equals(object? obj)
    {
        if (obj?.GetType() != typeof(PointWithoutHash))
            return false;

        PointWithoutHash p = (PointWithoutHash)obj;
        return ((this.x == p.x) && (this.y == p.y));
    }
}

Siehe auch