CA1046: Do not overload operator equals on reference types

Property Value
Rule ID CA1046
Title Do not overload operator equals on reference types
Category Design
Fix is breaking or non-breaking Breaking
Enabled by default in .NET 8 No

Cause

A public or nested public reference type overloads the equality operator.

Rule description

For reference types, the default implementation of the equality operator is almost always correct. By default, two references are equal only if they point to the same object.

How to fix violations

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

When to suppress warnings

It is safe to suppress a warning from this rule when the reference type behaves like a built-in value type. If it is meaningful to do addition or subtraction on instances of the type, it is probably correct to implement the equality operator and suppress the violation.

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.

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

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

[*.{cs,vb}]
dotnet_diagnostic.CA1046.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.

You can configure this option for just this rule, for all rules it applies to, or for all rules in this category (Design) 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. 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:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Example 1

The following example demonstrates the default behavior when comparing two references.

public class MyReferenceType
{
    private int a, b;
    public MyReferenceType(int a, int b)
    {
        this.a = a;
        this.b = b;
    }

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

Example 2

The following application compares some references.

public class ReferenceTypeEquality
{
    public static void Main1046()
    {
        MyReferenceType a = new MyReferenceType(2, 2);
        MyReferenceType b = new MyReferenceType(2, 2);
        MyReferenceType c = a;

        Console.WriteLine("a = new {0} and b = new {1} are equal? {2}", a, b, a.Equals(b) ? "Yes" : "No");
        Console.WriteLine("c and a are equal? {0}", c.Equals(a) ? "Yes" : "No");
        Console.WriteLine("b and a are == ? {0}", b == a ? "Yes" : "No");
        Console.WriteLine("c and a are == ? {0}", c == a ? "Yes" : "No");
    }
}

This example produces the following output:

a = new (2,2) and b = new (2,2) are equal? No
c and a are equal? Yes
b and a are == ? No
c and a are == ? Yes

See also