CA2208: Creare istanze di eccezioni di argomento correttamente

Proprietà	valore
ID regola	CA2208
Title	Creare istanze di eccezioni di argomento correttamente
Categoria	Utilizzo
La correzione causa un'interruzione o meno	Non causa un'interruzione
Abilitato per impostazione predefinita in .NET 9	Come suggerimento

Causa

Quando un metodo ha un parametro e genera un tipo di eccezione o deriva da , ArgumentExceptionè previsto chiamare un costruttore che accetta correttamente un paramName parametro. Le possibili cause includono le situazioni seguenti:

• Viene effettuata una chiamata al costruttore predefinito (senza parametri) di un tipo di eccezione, ovvero deriva da , ArgumentException che ha anche un costruttore che accetta un paramName parametro.
• Un argomento stringa non corretto viene passato a un costruttore con parametri di un tipo di eccezione o deriva da . ArgumentException
• Uno dei nomi dei parametri viene passato per l'argomento message del costruttore del tipo di eccezione, ovvero deriva da , ArgumentException.

Descrizione regola

Anziché chiamare il costruttore predefinito, chiamare uno degli overload del costruttore che consente di fornire un messaggio di eccezione più significativo. Il messaggio di eccezione deve essere destinati allo sviluppatore e spiegare chiaramente la condizione di errore e come correggere o evitare l'eccezione.

Le firme di uno e due costruttori stringa di ArgumentException e i relativi tipi derivati non sono coerenti rispetto alla posizione message e paramName ai parametri. Assicurarsi che questi costruttori vengano chiamati con gli argomenti stringa corretti. Le firme sono le seguenti:

• 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)

Come correggere le violazioni

Per correggere una violazione di questa regola, chiamare un costruttore che accetta un messaggio, un nome di parametro o entrambi e assicurarsi che gli argomenti siano appropriati per il tipo di ArgumentException chiamata.

Suggerimento

Una correzione del codice è disponibile in Visual Studio per i nomi dei parametri posizionati in modo non corretto. Per usarlo, posizionare il cursore sulla riga di avviso e premere CTRL+. (punto). Scegliere Scambia l'ordine degli argomenti dall'elenco di opzioni presentate.

Se al metodo viene passato ArgumentException(String) un nome di parametro anziché un messaggio, il fixer fornisce invece l'opzione per passare al costruttore a due argomenti.

Quando eliminare gli avvisi

È possibile eliminare un avviso da questa regola solo se viene chiamato un costruttore con parametri con gli argomenti stringa corretti.

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

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.CA2208.severity = none

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

Configurare il codice da analizzare

Usare l'opzione seguente per configurare le parti della codebase in cui eseguire questa regola.

• Includere superfici API specifiche

È possibile configurare questa opzione solo per questa regola, per tutte le regole a cui si applica o per tutte le regole in 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

Per impostazione predefinita, la regola CA2208 si applica a tutte le superfici API (pubbliche, interne e private).

Esempio

Nel codice seguente viene illustrato un costruttore che crea erroneamente un'istanza di 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

Il codice seguente corregge la violazione precedente cambiando gli argomenti del costruttore.

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

Regole correlate

• CA1507: Usare nameof al posto della stringa