CA1815:必須覆寫實值類型上的 Equals 方法和等號比較運算子

  • 發行項
屬性 值
規則識別碼 CA1815
標題 覆寫實值型別上的 Equals 和等號比較運算子
類別 效能
修正程式是中斷或非中斷 不中斷
預設在 .NET 8 中啟用 No

原因

實值型別不會覆寫 System.Object.Equals 或未實作等號運算符 （==）。 此規則不會檢查列舉。

根據預設，此規則只會查看外部可見的類型，但這是可設定的。

檔案描述

對於 非 blittable 實值型別，繼承的 實 Equals 作會使用 System.Reflection 連結庫來比較所有字段的內容。 但是 Reflection 相當耗費運算資源，而且可能不需要比較每個欄位是否相等。 如果您預期使用者比較或排序實例，或使用它們做為哈希表索引鍵，您的實值類型應該實 Equals作 。 如果您的程式設計語言支援運算子多載，則也應該提供相等和不等運算子的實作。

如何修正違規

若要修正違反此規則的情況，請提供 Equals 的實作。 如果可以，請實作等號運算符。

隱藏警告的時機

如果實值類型的實例不會彼此比較，則隱藏此規則的警告是安全的。

隱藏警告

如果您只想要隱藏單一違規，請將預處理器指示詞新增至原始程式檔以停用，然後重新啟用規則。

#pragma warning disable CA1815
// The code that's violating the rule is on this line.
#pragma warning restore CA1815

若要停用檔案、資料夾或項目的規則，請在組態檔中將其嚴重性設定為 。none

[*.{cs,vb}]
dotnet_diagnostic.CA1815.severity = none

如需詳細資訊，請參閱 如何隱藏程式代碼分析警告。

設定程式代碼以分析

使用下列選項來設定程式代碼基底要執行此規則的部分。

您可以只針對此規則、它套用的所有規則，或針對套用至此類別的所有規則（效能）設定此選項。 如需詳細資訊，請參閱 程式代碼品質規則組態選項。

包含特定 API 介面

您可以根據程式代碼基底的存取範圍，設定要執行此規則的部分。 例如，若要指定規則只應該針對非公用 API 介面執行，請將下列機碼/值組新增至 專案中的 .editorconfig 檔案：

dotnet_code_quality.CAXXXX.api_surface = private, internal

範例

下列程式代碼顯示違反此規則的結構（實值類型）：

// Violates this rule
public struct Point
{
    public Point(int x, int y)
    {
        X = x;
        Y = y;
    }

    public int X { get; }

    public int Y { get; }
}

下列程式代碼會藉由覆寫 System.ValueType.Equals 和實作等號運算符 （== 和 !=） 來修正先前的違規問題：

public struct Point : IEquatable<Point>
{
    public Point(int x, int y)
    {
        X = x;
        Y = y;
    }

    public int X { get; }

    public int Y { get; }

    public override int GetHashCode()
    {
        return X ^ Y;
    }

    public override bool Equals(object? obj)
    {
        if (!(obj is Point))
            return false;

        return Equals((Point)obj);
    }

    public bool Equals(Point other)
    {
        if (X != other.X)
            return false;

        return Y == other.Y;
    }

    public static bool operator ==(Point point1, Point point2)
    {
        return point1.Equals(point2);
    }

    public static bool operator !=(Point point1, Point point2)
    {
        return !point1.Equals(point2);
    }
}

另請參閱