CA2231: Sobrecarregar operador equals ao substituir ValueType.Equals

  • Artigo
Property Valor
ID da regra CA2231
Título Sobrecarregar operador equals ao substituir ValueType.Equals
Categoria Usage
Correção interruptiva ou sem interrupção Sem interrupção
Habilitado por padrão no .NET 8 Como sugestão

Causa

Um tipo de valor substitui System.Object.Equals, mas não implementa o operador de igualdade.

Por padrão, essa regra apenas analisa os tipos visíveis externamente, mas isso é configurável.

Descrição da regra

Na maioria das linguagens de programação, não há implementação padrão do operador de igualdade (==) para tipos de valor. Se sua linguagem de programação oferece suporte a sobrecargas de operador, você deve considerar a implementação do operador de igualdade. Seu comportamento deve ser idêntico ao de Equals.

Você não pode usar o operador de igualdade padrão em uma implementação sobrecarregada do operador de igualdade. Isso causará um estouro de pilha. Para implementar o operador de igualdade, use o método Object.Equals em sua implementação. Por exemplo:

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

Como corrigir violações

Para corrigir uma violação dessa regra, implemente o operador de igualdade.

Quando suprimir avisos

É seguro suprimir um aviso desta regra; no entanto, recomendamos que você forneça o operador de igualdade, se possível.

Suprimir um aviso

Para suprimir apenas uma violação, adicione diretivas de pré-processador ao arquivo de origem a fim de desabilitar e, em seguida, reabilitar a regra.

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

Para desabilitar a regra em um arquivo, uma pasta ou um projeto, defina a severidade como none no arquivo de configuração.

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

Para obter mais informações, confira Como suprimir avisos de análise de código.

Configurar código para analisar

Use a opção a seguir para configurar em quais partes da base de código essa regra deve ser executada.

Você pode configurar essa opção apenas para essa regra, para todas as regras às quais ela se aplica ou para todas as regras nessa categoria (Uso) às quais ela se aplica. Para saber mais, confira Opções de configuração de regra de qualidade de código.

Incluir superfícies de API específicas

É possível configurar em quais partes da base de código essa regra deverá ser executada, com base na acessibilidade. Por exemplo, para especificar que a regra deverá ser executada apenas na superfície de API não pública, adicione o seguinte par chave-valor a um arquivo .editorconfig no projeto:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Exemplo

O exemplo a seguir define um tipo que viola essa regra:

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

Confira também