CA2208: Criar instância de exceções de argumento corretamente

Property	Valor
ID da regra	CA2208
Título	Criar instância de exceções de argumento corretamente
Categoria	Usage
Correção interruptiva ou sem interrupção	Sem interrupção
Habilitado por padrão no .NET 9	Como sugestão

Causa

Quando um método tem um parâmetro e gera um tipo de exceção ArgumentException ou derivado dele espera-se que ele chame um construtor aceitando um parâmetro paramName corretamente. As causa 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 é transmitido para um construtor parametrizado de um tipo de exceção ArgumentException ou derivado dele.
• Um dos nomes dos parâmetros é transmitido para o argumento message do construtor do tipo de exceção ArgumentException ou derivado dele.

Descrição da regra

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

As assinaturas de um e dois construtores de cadeia de caracteres de ArgumentException e seus tipos derivados não são consistentes com relação à posição message e aos parâmetros paramName. Verifique se 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 utilize uma mensagem, um nome de parâmetro ou ambos e verifique se os argumentos são adequados para o tipo de ArgumentException sendo chamado.

Dica

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

Se um nome de parâmetro, em vez de uma mensagem, for transmitido ao método ArgumentException(String), o reparador fornecerá a opção de alternar para o construtor de dois argumentos.

Quando suprimir avisos

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

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

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.CA2208.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.

• Incluir superfícies de API específicas

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 (Design) à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 deve 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

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 cria incorretamente 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 relacionadas

• CA1507: Usar nameof no lugar da cadeia de caracteres