CA2208: Argumentausnahmen korrekt instanziieren.

Ursache

Wenn eine Methode einen Parameter aufweist und einen Ausnahmetyp auslöst, der ArgumentException ist oder davon abgeleitet ist, sollte ein Konstruktor aufgerufen werden, der einen paramName-Parameter korrekt annimmt. Zu den möglichen Ursachen zählen folgende Situationen:

• Es wird ein Aufruf an den Standardkonstruktor (parameterlose) eines Ausnahmetyps ausgeführt, der ebenfalls einen Konstruktor enthält, ArgumentException der einen paramName Parameter akzeptiert.
• Ein falsches Zeichenfolgenargument wird an einen parametrisierten Konstruktor eines Ausnahmetyps übergeben, der ArgumentException oder davon abgeleitet ist.
• Einer der Parameternamen wird für das message-Argument des Konstruktors des Ausnahmetyps übergeben, der ArgumentException oder davon abgeleitet ist.

Regelbeschreibung

Anstatt den Standardkonstruktor aufzurufen, rufen Sie eine der Konstruktorüberladungen auf, die eine aussagekräftigere Ausnahmemeldung ermöglichen. Die Ausnahmemeldung sollte auf den Entwickler ausgerichtet sein und die Fehlerbedingungen sowie die Maßnahmen zum Korrigieren oder Vermeiden der Ausnahme klar erläutern.

Die Signaturen der Konstruktoren von ArgumentException mit einer bzw. zwei Zeichenfolgen und deren abgeleitete Typen sind im Hinblick auf die Position der message- und paramName-Parameter nicht konsistent. Stellen Sie sicher, dass diese Konstruktoren mit den richtigen Zeichenfolgenargumenten aufgerufen werden. Die Signaturen lauten wie folgt:

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

Behandeln von Verstößen

Rufen Sie einen Konstruktor auf, der eine Meldung, einen Parameternamen oder beides annimmt, und stellen Sie sicher, dass die richtigen Argumente für den aufgerufenen ArgumentException-Typ verwendet werden, um einen Verstoß gegen diese Regel zu korrigieren.

Wann sollten Warnungen unterdrückt werden?

Es ist nur sicher, eine Warnung dieser Regel zu unterdrücken, wenn ein parametrisierter Konstruktor mit den richtigen Zeichenfolgenargumenten aufgerufen wird.

Unterdrücken einer Warnung

Um nur eine einzelne Verletzung zu unterdrücken, fügen Sie der Quelldatei Präprozessoranweisungen hinzu, um die Regel zu deaktivieren und dann wieder zu aktivieren.

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

Um die Regel für eine Datei, einen Ordner oder ein Projekt zu deaktivieren, legen Sie den Schweregrad in der Konfigurationsdatei auf none fest.

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

Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken von Codeanalyse-Warnungen.

Konfigurieren des zu analysierenden Codes

Mithilfe der folgenden Option können Sie konfigurieren, für welche Teile Ihrer Codebasis diese Regel ausgeführt werden soll.

• Einschließen bestimmter API-Oberflächen

Sie können diese Optionen nur für diese Regel, für alle zutreffenden Regeln oder für alle zutreffenden Regeln in dieser Kategorie (Entwurf) konfigurieren. Weitere Informationen finden Sie unter Konfigurationsoptionen für die Codequalitätsregel.

Einschließen bestimmter API-Oberflächen

Sie können je nach Zugänglichkeit festlegen, für welche Bestandteile Ihrer Codebasis diese Regel ausgeführt wird. Sie können beispielsweise festlegen, dass die Regel nur für die nicht öffentliche API-Oberfläche ausgeführt werden soll, indem Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzufügen:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Standardmäßig gilt die CA2208-Regel für alle API-Oberflächen (öffentlich, intern und privat).

Beispiel

Der folgende Code zeigt einen Konstruktor, der eine Instanz von ArgumentNullException falsch instanziiert.

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

Mit dem folgenden Code wird der vorherige Verstoß korrigiert, indem die Konstruktorargumente gewechselt werden.

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

Verwandte Regeln

• CA1507: „nameof“ anstelle der Zeichenfolge verwenden