CA2208: Argumentausnahmen korrekt instanziieren.

  • Artikel
Eigenschaft Wert
Regel-ID CA2208
Titel Argumentausnahmen korrekt instanziieren.
Kategorie Verwendung
Fix führt oder führt nicht zur Unterbrechung Nicht unterbrechend
Standardmäßig in .NET 8 aktiviert Als Vorschlag

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:

  • Der Standardkonstruktor (ohne Parameter) eines Ausnahmetyps ArgumentException (oder davon abgeleitet) wird aufgerufen. Dieser weist einen Konstruktor auf, der einen paramName-Parameter annimmt.

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

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.

Tipp

In Visual Studio ist ein Codefix für falsch positionierte Parameternamen verfügbar. Positionieren Sie den Cursor in der Warnungszeile, und drücken Sie STRG+. (Punkt), um diesen zu verwenden. Wählen Sie aus der angezeigten Liste mit Optionen Argumentreihenfolge tauschen aus.

Code fix for CA2208 - swap arguments.

Wenn ein Parametername anstelle einer Meldung an die ArgumentException(String)-Methode übergeben wird, bietet die Korrekturregel die Option, stattdessen zum Konstruktor mit zwei Argumenten zu wechseln.

Code fix for CA2208 - switch to two-argument constructor.

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.

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