CA1062: Convalidare gli argomenti di metodi pubblici

  • Articolo
Proprietà valore
ID regola CA1062
Title Convalidare gli argomenti di metodi pubblici
Categoria Progettazione
Correzione che causa un'interruzione o un'interruzione Nessuna interruzione
Abilitato per impostazione predefinita in .NET 8 No

Causa

Un metodo visibile esternamente dereferenzia uno dei relativi argomenti di riferimento senza verificare se l'argomento è null (Nothing in Visual Basic).

È possibile configurare questa regola per escludere determinati tipi e parametri dall'analisi. È anche possibile indicare metodi di convalida null-check.

Descrizione regola

Tutti gli argomenti di riferimento passati a metodi visibili esternamente devono essere controllati rispetto nulla . Se appropriato, generare un'eccezione ArgumentNullException quando l'argomento è null.

Se un metodo può essere chiamato da un assembly sconosciuto perché è dichiarato pubblico o protetto, è necessario convalidare tutti i parametri del metodo . Se il metodo è progettato per essere chiamato solo da assembly noti, contrassegnare il metodo internal e applicare l'attributo all'assembly InternalsVisibleToAttribute che contiene il metodo .

Come correggere le violazioni

Per correggere una violazione di questa regola, convalidare ogni argomento di riferimento rispetto a null.

Quando eliminare gli avvisi

È possibile eliminare un avviso da questa regola se si è certi che il parametro dereferenziato sia stato convalidato da un'altra chiamata al metodo nella funzione.

Eliminare un avviso

Se si vuole eliminare una singola violazione, aggiungere direttive del preprocessore al file di origine per disabilitare e quindi riabilitare la regola.

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

Per disabilitare la regola per un file, una cartella o un progetto, impostarne la gravità none su nel file di configurazione.

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

Per altre informazioni, vedere Come eliminare gli avvisi di analisi del codice.

Configurare il codice da analizzare

Usare le opzioni seguenti per configurare le parti della codebase in cui eseguire questa regola.

Queste opzioni possono essere configurate solo per questa regola, per tutte le regole a cui si applica o per tutte le regole di questa categoria (Progettazione) a cui si applica. Per altre informazioni, vedere Opzioni di configurazione delle regole di qualità del codice.

Includere superfici API specifiche

È possibile configurare le parti della codebase in modo da eseguire questa regola in base all'accessibilità. Ad esempio, per specificare che la regola deve essere eseguita solo sulla superficie dell'API non pubblica, aggiungere la coppia chiave-valore seguente a un file con estensione editorconfig nel progetto:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Nota

Questa opzione è supportata solo per CA1062 in .NET 7 e versioni successive.

Escludere simboli specifici

È possibile escludere simboli specifici, ad esempio tipi e metodi, dall'analisi. Ad esempio, per specificare che la regola non deve essere eseguita in alcun codice all'interno di tipi denominati MyType, aggiungere la coppia chiave-valore seguente a un file con estensione editorconfig nel progetto:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Formati di nome simbolo consentiti nel valore dell'opzione (separati da |):

  • Solo nome simbolo (include tutti i simboli con il nome, indipendentemente dal tipo o dallo spazio dei nomi contenitore).
  • Nomi completi nel formato ID della documentazione del simbolo. Ogni nome di simbolo richiede un prefisso di tipo simbolo, ad esempio M: per i metodi, T: per i tipi e N: per gli spazi dei nomi.
  • .ctor per costruttori e .cctor per costruttori statici.

Esempi:

Valore opzione Riepilogo
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Corrisponde a tutti i simboli denominati MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Corrisponde a tutti i simboli denominati MyType1 o MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Corrisponde a un metodo MyMethod specifico con la firma completa specificata.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Trova la corrispondenza con metodi MyMethod1 specifici e MyMethod2 con le rispettive firme complete.

Escludere tipi specifici e i relativi tipi derivati

È possibile escludere tipi specifici e i relativi tipi derivati dall'analisi. Ad esempio, per specificare che la regola non deve essere eseguita in alcun metodo all'interno di tipi denominati MyType e dei relativi tipi derivati, aggiungere la coppia chiave-valore seguente a un file con estensione editorconfig nel progetto:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Formati di nome simbolo consentiti nel valore dell'opzione (separati da |):

  • Solo nome di tipo (include tutti i tipi con il nome, indipendentemente dal tipo o dallo spazio dei nomi contenitore).
  • Nomi completi nel formato ID della documentazione del simbolo, con un prefisso facoltativoT:.

Esempi:

Valore opzione Riepilogo
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Corrisponde a tutti i tipi denominati MyType e a tutti i relativi tipi derivati.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Corrisponde a tutti i tipi denominati MyType1 o MyType2 e a tutti i relativi tipi derivati.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Corrisponde a un tipo MyType specifico con il nome completo specificato e tutti i relativi tipi derivati.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Corrisponde a tipi MyType1 specifici e MyType2 con i rispettivi nomi completi e tutti i relativi tipi derivati.

Escludere il metodo di estensione 'this' parametro

Per impostazione predefinita, questa regola analizza e contrassegna il this parametro per i metodi di estensione. È possibile escludere l'analisi del parametro per i this metodi di estensione aggiungendo la coppia chiave-valore seguente a un file con estensione editorconfig nel progetto:

dotnet_code_quality.CA1062.exclude_extension_method_this_parameter = true

Metodi di convalida dei controlli Null

Questa regola può causare falsi positivi se il codice chiama metodi speciali di convalida con controllo Null nelle librerie o nei progetti a cui si fa riferimento. È possibile evitare questi falsi positivi specificando il nome o la firma dei metodi di convalida del controllo Null. L'analisi presuppone che gli argomenti passati a questi metodi non siano Null dopo la chiamata. Ad esempio, per contrassegnare tutti i metodi denominati Validate come metodi di convalida null-check, aggiungere la coppia chiave-valore seguente a un file con estensione editorconfig nel progetto:

dotnet_code_quality.CA1062.null_check_validation_methods = Validate

I formati dei nomi dei metodi consentiti nel valore dell'opzione (separati da |):

  • Solo nome metodo (include tutti i metodi con il nome, indipendentemente dal tipo o dallo spazio dei nomi contenitore).
  • Nomi completi nel formato ID della documentazione del simbolo, con un prefisso facoltativoM:.

Esempi:

Valore opzione Riepilogo
dotnet_code_quality.CA1062.null_check_validation_methods = Validate Corrisponde a tutti i metodi denominati Validate nella compilazione.
dotnet_code_quality.CA1062.null_check_validation_methods = Validate1|Validate2 Corrisponde a tutti i metodi denominati Validate1 o Validate2 nella compilazione.
dotnet_code_quality.CA1062.null_check_validation_methods = NS.MyType.Validate(ParamType) Corrisponde a un metodo Validate specifico con una firma completa specificata.
dotnet_code_quality.CA1062.null_check_validation_methods = NS1.MyType1.Validate1(ParamType)|NS2.MyType2.Validate2(ParamType) Trova la corrispondenza con metodi Validate1 specifici e Validate2 con la rispettiva firma completa.

Esempio 1

Nell'esempio seguente viene illustrato un metodo che viola la regola e un metodo che soddisfa la regola.

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

Esempio 2

I costruttori di copia che popolano campi o proprietà che sono oggetti di riferimento possono violare anche la regola CA1062. La violazione si verifica perché l'oggetto copiato passato al costruttore di copia potrebbe essere null (Nothing in Visual Basic). Per risolvere la violazione, utilizzare un static metodo (Shared in Visual Basic) per verificare che l'oggetto copiato non sia Null.

Nell'esempio di classe seguente, l'oggetto other passato al Person costruttore di copia potrebbe essere 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)
    {
    }
}

Esempio 3

Nell'esempio modificato Person seguente, l'oggetto other passato al costruttore di copia viene prima controllato per null nel PassThroughNonNull metodo .

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;
    }
}