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

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. Por exemplo, o paramName argumento não corresponde ao nome de um dos parâmetros do método.
• Um nome de parâmetro é passado para o message argumento do construtor de um 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 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.

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

Você pode configurar em quais partes da base de código executar essa regra, com base em sua acessibilidade, configurando a opção api_surface. 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

O código a seguir mostra um método que lança ArgumentNullException incorretamente com um paramName que não corresponde a nenhum dos parâmetros do método. A regra é acionada porque description é uma variável local, não um parâmetro de método.

public class Product
{
    public string? Description { get; set; }
    public string Name { get; set; } = string.Empty;
}

public class Example
{
    // Violates CA2208: 'description' is not a parameter of this method.
    public void ProcessProduct(Product product)
    {
        string? description = product.Description;
        if (description is null)
        {
            throw new ArgumentNullException(nameof(description), $"Product named {product.Name} had no description!");
        }
        // Process description...
    }
}

Public Class Product
    Public Property Description As String
    Public Property Name As String = String.Empty
End Class

Public Class Example
    ' Violates CA2208: 'description' is not a parameter of this method.
    Public Sub ProcessProduct(ByVal product As Product)
        Dim description As String = product.Description
        If description Is Nothing Then
            Throw New ArgumentNullException(NameOf(description), $"Product named {product.Name} had no description!")
        End If
        ' Process description...
    End Sub
End Class

O código a seguir corrige a violação anterior usando InvalidOperationException em vez disso, o que é apropriado quando o estado de um objeto é inválido.

public class Product
{
    public string? Description { get; set; }
    public string Name { get; set; } = string.Empty;
}

public class Example
{
    // Fixed: Use InvalidOperationException for invalid object state.
    public void ProcessProduct(Product product)
    {
        string? description = product.Description;
        if (description is null)
        {
            throw new InvalidOperationException($"Product named {product.Name} had no description!");
        }
        // Process description...
    }
}

Public Class Product
    Public Property Description As String
    Public Property Name As String = String.Empty
End Class

Public Class Example
    ' Fixed: Use InvalidOperationException for invalid object state.
    Public Sub ProcessProduct(ByVal product As Product)
        Dim description As String = product.Description
        If description Is Nothing Then
            Throw New InvalidOperationException($"Product named {product.Name} had no description!")
        End If
        ' Process description...
    End Sub
End Class

Regras relacionadas

• CA1507: Usar nameof no lugar da cadeia de caracteres