CA2231: Overload operator equals on overriding ValueType.Equals

Property	Value
Rule ID	CA2231
Title	Overload operator equals on overriding ValueType.Equals
Category	Usage
Fix is breaking or non-breaking	Non-breaking
Enabled by default in .NET 9	As suggestion

Cause

A value type overrides System.Object.Equals but does not implement the equality operator.

By default, this rule only looks at externally visible types, but this is configurable.

Rule description

In most programming languages, there is no default implementation of the equality operator (==) for value types. If your programming language supports operator overloads, you should consider implementing the equality operator. Its behavior should be identical to that of Equals.

You cannot use the default equality operator in an overloaded implementation of the equality operator. Doing so will cause a stack overflow. To implement the equality operator, use the Object.Equals method in your implementation. For example:

C#

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

How to fix violations

To fix a violation of this rule, implement the equality operator.

When to suppress warnings

It is safe to suppress a warning from this rule; however, we recommend that you provide the equality operator if possible.

Suppress a warning

If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.

C#

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

To disable the rule for a file, folder, or project, set its severity to none in the configuration file.

ini

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

For more information, see How to suppress code analysis warnings.

Configure code to analyze

Use the following option to configure which parts of your codebase to run this rule on.

• Include specific API surfaces

You can configure this option for just this rule, for all rules it applies to, or for all rules in this category (Usage) that it applies to. For more information, see Code quality rule configuration options.

Include specific API surfaces

You can configure which parts of your codebase to run this rule on, based on their accessibility, by setting the api_surface option. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an .editorconfig file in your project:

ini

dotnet_code_quality.CAXXXX.api_surface = private, internal

Obs!

Replace the XXXX part of CAXXXX with the ID of the applicable rule.

Example

The following example defines a type that violates this rule:

C#

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));
    }
}

Related rules

• CA1046: Do not overload operator equals on reference types
• CA2225: Operator overloads have named alternates
• CA2226: Operators should have symmetrical overloads

See also

• System.Object.Equals