Partilhar via

CA1062: Validar argumentos de métodos públicos

  • Artigo
Property valor
ID da regra CA1062
Título Validar argumentos de métodos públicos
Categoria Desenho
A correção está quebrando ou não quebrando Sem quebra
Habilitado por padrão no .NET 9 Não

Motivo

Um método visível externamente desreferencia um de seus argumentos de referência sem verificar se esse argumento é null (Nothing no Visual Basic).

Você pode configurar essa regra para excluir determinados tipos e parâmetros da análise. Você também pode indicar métodos de validação de verificação nula.

Descrição da regra

Todos os argumentos de referência que são passados para métodos visíveis externamente devem ser verificados em relação ao null. Se apropriado, lance um ArgumentNullException quando o argumento for null.

Se um método pode ser chamado a partir de um assembly desconhecido porque é declarado público ou protegido, você deve validar todos os parâmetros do método. Se o método for projetado para ser chamado somente por assemblies conhecidos, marque o método internal e aplique o InternalsVisibleToAttribute atributo ao assembly que contém o método.

Como corrigir violações

Para corrigir uma violação desta regra, valide cada argumento de referência contra null.

Quando suprimir avisos

Você pode suprimir um aviso dessa regra se tiver certeza de que o parâmetro desreferenciado foi validado por outra chamada de método na função.

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

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

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

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

Configurar código para análise

Use as opções a seguir para configurar em quais partes da base de código executar essa regra.

Essas opções podem ser configuradas 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

Nota

Esta opção é suportada apenas para CA1062 no .NET 7 e versões posteriores.

Excluir símbolos específicos

Você pode excluir símbolos específicos, como tipos e métodos, da análise. Por exemplo, para especificar que a regra não deve ser executada em nenhum código dentro de tipos nomeados MyType, adicione o seguinte par chave-valor a um arquivo .editorconfig em seu projeto:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Formatos de nome de símbolo permitidos no valor da opção (separados por |):

  • Somente nome do símbolo (inclui todos os símbolos com o nome, independentemente do tipo ou namespace que o contém).
  • Nomes totalmente qualificados no formato de ID de documentação do símbolo. Cada nome de símbolo requer um prefixo de tipo de símbolo, como M: para métodos, T: para tipos e N: para namespaces.
  • .ctor para construtores e .cctor para construtores estáticos.

Exemplos:

Valor da opção Resumo
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Corresponde a todos os símbolos denominados MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Corresponde a todos os símbolos denominados ou MyType1 MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Corresponde ao método MyMethod específico com a assinatura totalmente qualificada especificada.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Corresponde a métodos MyMethod1 específicos e MyMethod2 com as respetivas assinaturas totalmente qualificadas.

Excluir tipos específicos e seus tipos derivados

Você pode excluir tipos específicos e seus tipos derivados da análise. Por exemplo, para especificar que a regra não deve ser executada em nenhum método dentro de tipos nomeados MyType e seus tipos derivados, adicione o seguinte par chave-valor a um arquivo .editorconfig em seu projeto:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Formatos de nome de símbolo permitidos no valor da opção (separados por |):

  • Somente nome do tipo (inclui todos os tipos com o nome, independentemente do tipo ou namespace que o contém).
  • Nomes totalmente qualificados no formato de ID de documentação do símbolo, com um prefixo opcionalT:.

Exemplos:

Valor da opção Resumo
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Corresponde a todos os tipos nomeados MyType e todos os seus tipos derivados.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Corresponde a todos os tipos nomeados ou MyType1 e MyType2 todos os seus tipos derivados.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Corresponde a um tipo MyType específico com um determinado nome totalmente qualificado e todos os seus tipos derivados.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Corresponde a tipos MyType1 específicos e MyType2 com os respetivos nomes totalmente qualificados, e todos os seus tipos derivados.

Excluir parâmetro do método de extensão 'this'

Por padrão, essa regra analisa e sinaliza o this parâmetro para métodos de extensão. Você pode excluir a this análise do parâmetro para métodos de extensão adicionando o seguinte par chave-valor a um arquivo .editorconfig em seu projeto:

dotnet_code_quality.CA1062.exclude_extension_method_this_parameter = true

Métodos de validação de verificação nula

Essa regra pode levar a falsos positivos se seu código chamar métodos especiais de validação de verificação nula em bibliotecas ou projetos referenciados. Você pode evitar esses falsos positivos especificando o nome ou a assinatura dos métodos de validação de verificação nula. A análise assume que os argumentos passados para esses métodos não são nulos após a chamada. Por exemplo, para marcar todos os métodos nomeados Validate como métodos de validação null-check, adicione o seguinte par chave-valor a um arquivo .editorconfig em seu projeto:

dotnet_code_quality.CA1062.null_check_validation_methods = Validate

Formatos de nome de método permitidos no valor da opção (separados por |):

  • Somente nome do método (inclui todos os métodos com o nome, independentemente do tipo ou namespace que o contém).
  • Nomes totalmente qualificados no formato de ID de documentação do símbolo, com um prefixo opcionalM:.

Exemplos:

Valor da opção Resumo
dotnet_code_quality.CA1062.null_check_validation_methods = Validate Corresponde a todos os métodos nomeados Validate na compilação.
dotnet_code_quality.CA1062.null_check_validation_methods = Validate1|Validate2 Corresponde a todos os métodos nomeados ou Validate1 Validate2 na compilação.
dotnet_code_quality.CA1062.null_check_validation_methods = NS.MyType.Validate(ParamType) Corresponde a um método Validate específico com uma determinada assinatura totalmente qualificada.
dotnet_code_quality.CA1062.null_check_validation_methods = NS1.MyType1.Validate1(ParamType)|NS2.MyType2.Validate2(ParamType) Corresponde a métodos Validate1 específicos e Validate2 com a respetiva assinatura totalmente qualificada.

Exemplo 1

O exemplo a seguir mostra um método que viola a regra e um método que satisfaz a regra.

using System;

namespace DesignLibrary
{
    public class Test
    {
        // This method violates the rule.
        public void DoNotValidate(string input)
        {
            if (input.Length != 0)
            {
                Console.WriteLine(input);
            }
        }

        // This method satisfies the rule.
        public void Validate(string input)
        {
            if (input == null)
            {
                throw new ArgumentNullException(nameof(input));
            }
            if (input.Length != 0)
            {
                Console.WriteLine(input);
            }
        }
    }
}

Imports System

Namespace DesignLibrary

    Public Class Test

        ' This method violates the rule.
        Sub DoNotValidate(ByVal input As String)

            If input.Length <> 0 Then
                Console.WriteLine(input)
            End If

        End Sub

        ' This method satisfies the rule.
        Sub Validate(ByVal input As String)

            If input Is Nothing Then
                Throw New ArgumentNullException(NameOf(input))
            End If

            If input.Length <> 0 Then
                Console.WriteLine(input)
            End If

        End Sub

    End Class

End Namespace

Exemplo 2

Os construtores de cópia que preenchem campos ou propriedades que são objetos de referência também podem violar a regra CA1062. A violação ocorre porque o objeto copiado que é passado para o construtor de cópia pode ser null (Nothing no Visual Basic). Para resolver a violação, use um static método (Shared no Visual Basic) para verificar se o objeto copiado não é nulo.

No exemplo de classe a seguir, o other objeto que é passado para o Person construtor copy pode ser null.Person

public class Person
{
    public string Name { get; private set; }
    public int Age { get; private set; }

    public Person(string name, int age)
    {
        Name = name;
        Age = age;
    }

    // Copy constructor CA1062 fires because other is dereferenced
    // without being checked for null
    public Person(Person other)
        : this(other.Name, other.Age)
    {
    }
}

Exemplo 3

No exemplo revisado Person a seguir, o other objeto que é passado para o construtor copy é primeiro verificado PassThroughNonNull para null no método.

public class Person
{
    public string Name { get; private set; }
    public int Age { get; private set; }

    public Person(string name, int age)
    {
        Name = name;
        Age = age;
    }

    // Copy constructor
    public Person(Person other)
        : this(PassThroughNonNull(other).Name, other.Age)
    {
    }

    // Null check method
    private static Person PassThroughNonNull(Person person)
    {
        if (person == null)
            throw new ArgumentNullException(nameof(person));
        return person;
    }
}