CA2208: Instanciar exceções de argumento corretamente

Property	valor
ID da regra	CA2208
Título	Instanciar exceções de argumento corretamente
Categoria	Utilização
A correção está quebrando ou não quebrando	Sem quebra
Habilitado por padrão no .NET 9	Como sugestão

Motivo

Quando um método tem um parâmetro e lança um tipo de exceção que é, ou deriva de, ArgumentException, espera-se que chame um construtor aceitando um paramName parâmetro corretamente. As causas possíveis incluem as seguintes situações:

• Uma chamada é feita para o construtor padrão (sem parâmetros) de um tipo de exceção que é, ou deriva de, ArgumentException que também tem um construtor que aceita um paramName parâmetro.
• Um argumento de cadeia de caracteres incorreto é passado para um construtor parametrizado de um tipo de exceção que é, ou deriva de, ArgumentException.
• Um dos nomes dos parâmetros é passado para o message argumento do construtor do tipo de exceção que é, ou deriva de, ArgumentException.

Descrição da regra

Em vez de chamar o construtor padrão, chame uma das sobrecargas do construtor que permite que uma mensagem de exceção mais significativa seja fornecida. A mensagem de exceção deve ter como alvo o desenvolvedor e explicar claramente a condição de erro e como corrigir ou evitar a exceção.

As assinaturas dos construtores de uma e duas cadeias de caracteres de ArgumentException e seus tipos derivados não são consistentes com relação à posição message e paramName aos parâmetros. Certifique-se de que esses construtores são chamados com os argumentos de cadeia de caracteres corretos. As assinaturas são as seguintes:

• ArgumentException(string message)
• ArgumentException(string message, string paramName)
• ArgumentNullException(string paramName)
• ArgumentNullException(string paramName, string message)
• ArgumentOutOfRangeException(string paramName)
• ArgumentOutOfRangeException(string paramName, string message)
• DuplicateWaitObjectException(string parameterName)
• DuplicateWaitObjectException(string parameterName, string message)

Como corrigir violações

Para corrigir uma violação dessa regra, chame um construtor que usa uma mensagem, um nome de parâmetro ou ambos e verifique se os argumentos são adequados para o tipo de ArgumentException chamada.

Gorjeta

Uma correção de código está disponível no Visual Studio para nomes de parâmetros posicionados incorretamente. Para usá-lo, posicione o cursor na linha de aviso e pressione Ctrl+. Escolha Trocar a ordem dos argumentos na lista de opções apresentada.

Se um nome de parâmetro em vez de uma mensagem é passado para o ArgumentException(String) método, o fixador fornece a opção de alternar para o construtor de dois argumentos.

Quando suprimir avisos

É seguro suprimir um aviso dessa regra somente se um construtor parametrizado for chamado com os argumentos de cadeia de caracteres corretos.

Suprimir um aviso

Se você quiser apenas suprimir uma única violação, adicione diretivas de pré-processador ao seu arquivo de origem para desativar e, em seguida, reativar a regra.

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

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

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

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

Configurar código para análise

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

• Incluir superfícies de API específicas

Você pode configurar essa opção apenas para esta regra, para todas as regras às quais ela se aplica ou para todas as regras nesta categoria (Design) às quais ela se aplica. Para obter mais informações, consulte Opções de configuração da regra de qualidade de código.

Incluir superfícies de API específicas

Você pode configurar em quais partes da sua base de código executar essa regra, com base em sua acessibilidade. Por exemplo, para especificar que a regra deve ser executada somente na superfície de API não pública, adicione o seguinte par chave-valor a um arquivo .editorconfig em seu projeto:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Por padrão, a regra CA2208 se aplica a todas as superfícies de API (pública, interna e privada).

Exemplo

O código a seguir mostra um construtor que incorretamente instancia uma instância de ArgumentNullException.

public class Book
{
    public Book(string title)
    {
        Title = title ??
            throw new ArgumentNullException("All books must have a title.", nameof(title));
    }

    public string Title { get; }
}

Public Class Book

    Private ReadOnly _Title As String

    Public Sub New(ByVal title As String)
        ' Violates this rule (constructor arguments are switched)            
        If (title Is Nothing) Then
            Throw New ArgumentNullException("title cannot be a null reference (Nothing in Visual Basic)", "title")
        End If
        _Title = title
    End Sub

    Public ReadOnly Property Title()
        Get
            Return _Title
        End Get
    End Property

End Class

O código a seguir corrige a violação anterior alternando os argumentos do construtor.

public class Book
{
    public Book(string title)
    {
        Title = title ??
            throw new ArgumentNullException(nameof(title), "All books must have a title.");
    }

    public string Title { get; }
}

Public Class Book

    Private ReadOnly _Title As String

    Public Sub New(ByVal title As String)
        If (title Is Nothing) Then
            Throw New ArgumentNullException("title", "title cannot be a null reference (Nothing in Visual Basic)")
        End If

        _Title = title
    End Sub

    Public ReadOnly Property Title()
        Get
            Return _Title
        End Get
    End Property

End Class

Regras conexas

• CA1507: Use nameof no lugar de string