CA2208: Instanciar exceções de argumento corretamente

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

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 base de código executar essa regra, com base em sua acessibilidade, definindo a opção api_surface. 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

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 conexas

• CA1507: Use nameof no lugar de string