CA1065: Não acionar exceções em locais inesperados

Causa

Um método que não deve acionar exceções aciona uma exceção.

Descrição da regra

Métodos que não devem gerar exceções podem ser categorizados da seguinte maneira:

• Métodos de obtenção de propriedade
• Métodos de acesso a eventos
• Métodos iguais
• Métodos GetHashCode
• Métodos ToString
• Construtores estáticos
• Finalizadores
• Métodos de descarte
• Operadores de igualdade
• Operadores de conversão implícitos

As seções a seguir discutem esses tipos de métodos.

Métodos de obtenção de propriedade

As propriedades são basicamente campos inteligentes. Portanto, elas devem se comportar como um campo tanto quanto possível. Os campos não geram exceções e nem as propriedades deveriam. Se você tiver uma propriedade que gera uma exceção, considere transformá-la em um método.

As seguintes exceções podem ser geradas de um método get de propriedade:

• System.InvalidOperationException e todos os derivados (incluindo System.ObjectDisposedException)
• System.NotSupportedException e todos os derivados
• System.ArgumentException (somente da obtenção indexada)
• System.Collections.Generic.KeyNotFoundException (somente do get indexado)

Métodos de acesso a eventos

Os acessadores de eventos devem ser operações simples que não geram exceções. Um evento não deve gerar uma exceção quando você tentar adicionar ou remover um manipulador de eventos.

As seguintes exceções podem ser geradas de um acessador de eventos:

• System.InvalidOperationException e todos os derivados (incluindo System.ObjectDisposedException)
• System.NotSupportedException e todos os derivados
• System.ArgumentException e derivados

Métodos iguais

Os seguintes métodos Equals não devem gerar exceções:

• System.Object.Equals
• System.IEquatable<T>.Equals

Um Equals método deve retornar true ou false em vez de lançar uma exceção. Por exemplo, se dois tipos incompatíveis forem passados para Equals, ele deve apenas retornar false em vez de lançar um ArgumentException.

Métodos GetHashCode

Os seguintes GetHashCode métodos geralmente não devem gerar exceções:

• System.Object.GetHashCode
• System.Collections.IEqualityComparer.GetHashCode

GetHashCode deve sempre retornar um valor. Caso contrário, você pode perder itens na tabela de hash.

As versões GetHashCode que recebem um argumento podem lançar um ArgumentException. No entanto, Object.GetHashCode nunca deve lançar uma exceção.

Métodos ToString

O depurador usa System.Object.ToString para ajudar a exibir informações sobre objetos no formato de cadeia de caracteres. Portanto, ToString não deve alterar o estado de um objeto e não deve gerar exceções.

Construtores estáticos

Gerar exceções de um construtor estático faz com que o tipo seja inutilizável no domínio do aplicativo atual. Você deve ter um bom motivo (como um problema de segurança) para lançar uma exceção de um construtor estático.

Finalizadores

Gerar uma exceção a partir de um finalizador faz com que o CLR falhe rapidamente, o que encerra o processo. Portanto, evite lançar exceções em um finalizador.

Métodos de descarte

Um método System.IDisposable.Dispose não deve gerar uma exceção. Dispose geralmente é chamado como parte da lógica de limpeza em uma cláusula finally. Portanto, forçar o lançamento de uma exceção explicitamente a partir de Dispose obriga o usuário a adicionar tratamento de exceção dentro da cláusula finally.

O caminho de código Dispose(false) nunca deve lançar exceções, porque Dispose é chamado quase sempre a partir de um finalizador.

Operadores de igualdade (==, !=)

Assim como os métodos Equals, os operadores de igualdade devem retornar ou true ou false, e não devem lançar exceções.

Operadores de conversão implícitos

Como o usuário geralmente não sabe que um operador de conversão implícita foi chamado, uma exceção gerada pelo operador de conversão implícita é inesperada. Portanto, nenhuma exceção deve ser gerada de operadores de conversão implícita.

Como corrigir violações

Para getters de propriedade, altere a lógica para que ela não precise mais lançar uma exceção ou altere a propriedade em um método.

Para todos os outros tipos de método listados anteriormente, altere a lógica para que ela não precise mais gerar uma exceção.

Quando suprimir avisos

Se a violação foi causada por uma declaração de exceção em vez de uma exceção lançada, é seguro suprimir um aviso desta regra.

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

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.CA1065.severity = none

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

Regras relacionadas

• CA2219: Não lançar exceções em cláusulas de exceção

Confira também

• Regras de design