CA1062: Convalidare gli argomenti di metodi pubblici
Proprietà | valore |
---|---|
ID regola | CA1062 |
Title | Convalidare gli argomenti di metodi pubblici |
Categoria | Progettazione |
La correzione causa un'interruzione o meno | Non causa un'interruzione |
Abilitato per impostazione predefinita in .NET 9 | 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 null
a . 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.
- Includere superfici API specifiche
- Escludere simboli specifici
- Escludere tipi specifici e i relativi tipi derivati
- Escludere il metodo di estensione 'this' parametro
- Metodi di convalida dei controlli Null
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 eN:
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 facoltativo
T:
.
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 facoltativo
M:
.
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;
}
}