CA1036: Methoden bei vergleichbaren Typen überschreiben.

Eigenschaft	Wert
Regel-ID	CA1036
Titel	Methoden bei vergleichbaren Typen überschreiben.
Kategorie	Design
Fix führt oder führt nicht zur Unterbrechung	Nicht unterbrechend
Standardmäßig in .NET 9 aktiviert	No

Ursache

Ein Typ implementiert die System.IComparable Schnittstelle und überschreibt nicht System.Object.Equals überlädt nicht den sprachspezifischen Operator für gleich, ungleich, kleiner als oder größer als. Die Regel meldet keinen Verstoß, wenn der Typ nur eine Implementierung der Schnittstelle erbt.

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

Regelbeschreibung

Typen, die eine benutzerdefinierte Sortierreihenfolge definieren, implementieren die IComparable-Schnittstelle. Die CompareTo-Methode gibt einen ganzzahligen Wert zurück, der die richtige Sortierreihenfolge für zwei Instanzen des Typs angibt. Diese Regel identifiziert Typen, die eine Sortierreihenfolge festlegen. Das Festlegen einer Sortierreihenfolge impliziert, dass die gewöhnliche Bedeutung von gleich, ungleich, kleiner als und größer als nicht zutrifft. Wenn Sie eine Implementierung von IComparable bereitstellen, müssen Sie in der Regel auch Equals überschreiben, sodass Werte zurückgegeben werden, die mit CompareTo übereinstimmen. Wenn Sie Equals überschreiben und in einer Sprache programmieren, die Operatorüberladungen unterstützt, sollten Sie auch Operatoren bereitstellen, die mit Equals konsistent sind.

Behandeln von Verstößen

Um einen Verstoß gegen diese Regel zu beheben, überschreiben Sie Equals. Wenn Ihre Programmiersprache eine Operatorüberladung unterstützt, stellen Sie die folgenden Operatoren bereit:

• op_Equality
• op_Inequality
• op_LessThan
• op_GreaterThan

// In C#, implement these operators.
public static bool operator ==(SampleClass? one, SampleClass? other) { }
public static bool operator !=(SampleClass? one, SampleClass? other) { }
public static bool operator <(SampleClass? one, SampleClass? other) { }
public static bool operator >(SampleClass? one, SampleClass? other) { }

Wann sollten Warnungen unterdrückt werden?

Es ist sicher, eine Warnung von Regel CA1036 zu unterdrücken, wenn die Verletzung durch fehlende Operatoren verursacht wird und Ihre Programmiersprache die Operatorüberladung nicht unterstützt. Wenn Sie feststellen, dass die Implementierung der Operatoren in Ihrem App-Kontext nicht sinnvoll ist, ist es auch sicher, eine Warnung aus dieser Regel zu unterdrücken, wenn sie auf anderen Gleichheitsoperatoren als op_Equality. Sie sollten jedoch immer überschreiben op_Equality und den == Operator, wenn Sie außer Kraft setzen Object.Equals.

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

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.CA1036.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.

• Einschließen bestimmter API-Oberflächen

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 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.

Beispiele

Der folgende Code enthält einen Typ, der ordnungsgemäß IComparable implementiert. Code-Kommentare identifizieren die Methoden, die verschiedene Regeln erfüllen, die mit Equals und der IComparable Schnittstelle verknüpft sind.

// Valid ratings are between A and C.
// A is the highest rating; it is greater than any other valid rating.
// C is the lowest rating; it is less than any other valid rating.

public class RatingInformation : IComparable, IComparable<RatingInformation>
{
    public string Rating { get; private set; }

    public RatingInformation(string rating)
    {
        ArgumentNullException.ThrowIfNull(rating);

        string v = rating.ToUpper(CultureInfo.InvariantCulture);
        if (v.Length != 1 ||
            string.Compare(v, "C", StringComparison.Ordinal) > 0 ||
            string.Compare(v, "A", StringComparison.Ordinal) < 0)
        {
            throw new ArgumentException("Invalid rating value was specified.", nameof(rating));
        }

        Rating = v;
    }

    public int CompareTo(object? obj)
    {
        if (obj == null)
        {
            return 1;
        }

        if (obj is RatingInformation other)
        {
            return CompareTo(other);
        }

        throw new ArgumentException("A RatingInformation object is required for comparison.", nameof(obj));
    }

    public int CompareTo(RatingInformation? other)
    {
        if (other is null)
        {
            return 1;
        }

        // Ratings compare opposite to normal string order,
        // so reverse the value returned by String.CompareTo.
        return -string.Compare(Rating, other.Rating, StringComparison.OrdinalIgnoreCase);
    }

    public static int Compare(RatingInformation left, RatingInformation right)
    {
        if (object.ReferenceEquals(left, right))
        {
            return 0;
        }
        if (left is null)
        {
            return -1;
        }
        return left.CompareTo(right);
    }

    // Omitting Equals violates rule: OverrideMethodsOnComparableTypes.
    public override bool Equals(object? obj)
    {
        if (obj is RatingInformation other)
        {
            return CompareTo(other) == 0;
        }

        return false;
    }

    // Omitting getHashCode violates rule: OverrideGetHashCodeOnOverridingEquals.
    public override int GetHashCode()
    {
        char[] c = Rating.ToCharArray();
        return (int)c[0];
    }

    // Omitting any of the following operator overloads
    // violates rule: OverrideMethodsOnComparableTypes.
    public static bool operator ==(RatingInformation left, RatingInformation right)
    {
        if (left is null)
        {
            return right is null;
        }
        return left.Equals(right);
    }
    public static bool operator !=(RatingInformation left, RatingInformation right)
    {
        return !(left == right);
    }
    public static bool operator <(RatingInformation left, RatingInformation right)
    {
        return (Compare(left, right) < 0);
    }
    public static bool operator >(RatingInformation left, RatingInformation right)
    {
        return (Compare(left, right) > 0);
    }
}

Der folgende Anwendungscode testet das Verhalten der IComparable-Implementierung, die zuvor gezeigt wurde.

public class TestCompare
{
    public static void Main1036(params string[] args)
    {
        if (args.Length < 2)
        {
            return;
        }
        RatingInformation r1 = new(args[0]);
        RatingInformation r2 = new(args[1]);
        string answer;

        if (r1.CompareTo(r2) > 0)
            answer = "greater than";
        else if (r1.CompareTo(r2) < 0)
            answer = "less than";
        else
            answer = "equal to";

        Console.WriteLine($"{r1.Rating} is {answer} {r2.Rating}");
    }
}

Siehe auch

• System.IComparable
• System.Object.Equals
• Gleichheitsoperatoren