CA2208: Prawidłowo twórz wyjątki argumentów

Właściwości	Wartość
Identyfikator reguły	CA2208
Tytuł	Prawidłowo inicjuj wyjątki argumentów
Kategoria	Użycie
Poprawka łamiąca lub nienaruszająca	Niezgodność
Domyślnie włączone na platformie .NET 10	Jako sugestia
Zastosowane języki	C# i Visual Basic

Przyczyna

Jeśli metoda ma parametr i zgłasza wyjątek typu, który jest lub pochodzi z ArgumentException, oczekuje się, że konstruktor poprawnie przyjmuje parametr paramName. Możliwe przyczyny obejmują następujące sytuacje:

• Wywoływane jest domyślne (bezparametrowe) wywołanie konstruktora typu wyjątku, który jest lub dziedziczy po ArgumentException, a który ma także konstruktor akceptujący parametr paramName.
• Nieprawidłowy argument ciągu znaków jest przekazywany do sparametryzowanego konstruktora typu wyjątku, który jest lub wywodzi się z klasy ArgumentException. Na przykład paramName argument nie jest zgodny z nazwą jednego z parametrów metody.
• Nazwa parametru zostaje przekazana dla message argumentu konstruktora typu wyjątku, który jest lub wywodzi się z ArgumentException.

Opis reguły

Zamiast wywoływać konstruktor domyślny, wywołaj jedno z przeciążeń konstruktora, które umożliwia podanie bardziej znaczącego komunikatu o wyjątku. Komunikat o wyjątku powinien być skierowany do dewelopera i jasno wyjaśnić warunek błędu oraz jak poprawić lub uniknąć wyjątku.

Podpisy jednego i dwóch konstruktorów ciągów ArgumentException i jego typów pochodnych nie są zgodne z położeniem message i paramName parametrami. Upewnij się, że te konstruktory są wywoływane z poprawnymi argumentami ciągu. Podpisy są następujące:

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

Jak naprawić naruszenia

Aby naprawić naruszenie tej reguły, wywołaj konstruktor, który przyjmuje komunikat, nazwę parametru lub oba te elementy i upewnij się, że argumenty są odpowiednie dla typu wywoływanego ArgumentException .

Wskazówka

Poprawka kodu jest dostępna w programie Visual Studio dla niepoprawnie umieszczonych nazw parametrów. Aby go użyć, umieść kursor na wierszu ostrzeżenia i naciśnij Ctrl+. (kropka). Wybierz pozycję Zamień kolejność argumentów z wyświetlonej listy opcji.

Jeśli zamiast wiadomości do ArgumentException(String) metody przekazywana jest nazwa parametru, poprawka oferuje możliwość przełączenia się na konstruktor z dwoma argumentami.

Kiedy pomijać ostrzeżenia

Można bezpiecznie pominąć ostrzeżenie z tej reguły tylko wtedy, gdy konstruktor sparametryzowany jest wywoływany z poprawnymi argumentami ciągu.

Pomijanie ostrzeżenia

Jeśli chcesz po prostu pominąć pojedyncze naruszenie, dodaj dyrektywy preprocesora do pliku źródłowego, aby wyłączyć, a następnie ponownie włączyć regułę.

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

Aby wyłączyć regułę dla pliku, folderu lub projektu, ustaw jego ważność na none w pliku konfiguracji.

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

Aby uzyskać więcej informacji, zobacz Jak pominąć ostrzeżenia dotyczące analizy kodu.

Konfigurowanie kodu do analizowania

Użyj następującej opcji, aby skonfigurować, które części kodu mają być objęte tą regułą.

• Uwzględnij określone powierzchnie interfejsu API

Tę opcję można skonfigurować tylko dla tej reguły, dla wszystkich reguł, do których ma ona zastosowanie, lub dla wszystkich reguł w tej kategorii (Projekt), których dotyczy. Aby uzyskać więcej informacji, zobacz Opcje konfiguracji reguły jakości kodu.

Uwzględnij określone powierzchnie interfejsu API

Możesz skonfigurować, na które części bazy kodu ma być stosowana ta reguła, na podstawie ich poziomu dostępu, ustawiając opcję api_surface. Aby na przykład określić, że reguła powinna być uruchamiana tylko na powierzchni niepublicznego interfejsu API, dodaj następującą parę klucz-wartość do pliku editorconfig w projekcie:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Notatka

Zastąp część XXXXCAXXXX identyfikatorem odpowiedniej reguły.

Domyślnie reguła CA2208 dotyczy wszystkich powierzchni interfejsu API (publicznych, wewnętrznych i prywatnych).

Przykład

Poniższy kod przedstawia konstruktor, który niepoprawnie tworzy wystąpienie klasy 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

Poniższy kod naprawia poprzednie naruszenie, przełączając argumenty konstruktora.

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

Poniższy kod przedstawia metodę, która niepoprawnie zgłasza ArgumentNullException z paramName, które nie pasuje do żadnego z parametrów metody. Reguła jest uruchamiana, ponieważ description jest zmienną lokalną, a nie parametrem metody.

public class Product
{
    public string? Description { get; set; }
    public string Name { get; set; } = string.Empty;
}

public class Example
{
    // Violates CA2208: 'description' is not a parameter of this method.
    public void ProcessProduct(Product product)
    {
        string? description = product.Description;
        if (description is null)
        {
            throw new ArgumentNullException(nameof(description), $"Product named {product.Name} had no description!");
        }
        // Process description...
    }
}

Public Class Product
    Public Property Description As String
    Public Property Name As String = String.Empty
End Class

Public Class Example
    ' Violates CA2208: 'description' is not a parameter of this method.
    Public Sub ProcessProduct(ByVal product As Product)
        Dim description As String = product.Description
        If description Is Nothing Then
            Throw New ArgumentNullException(NameOf(description), $"Product named {product.Name} had no description!")
        End If
        ' Process description...
    End Sub
End Class

Poniższy kod naprawia poprzednie naruszenie przy użyciu polecenia InvalidOperationException , co jest odpowiednie, gdy stan obiektu jest nieprawidłowy.

public class Product
{
    public string? Description { get; set; }
    public string Name { get; set; } = string.Empty;
}

public class Example
{
    // Fixed: Use InvalidOperationException for invalid object state.
    public void ProcessProduct(Product product)
    {
        string? description = product.Description;
        if (description is null)
        {
            throw new InvalidOperationException($"Product named {product.Name} had no description!");
        }
        // Process description...
    }
}

Public Class Product
    Public Property Description As String
    Public Property Name As String = String.Empty
End Class

Public Class Example
    ' Fixed: Use InvalidOperationException for invalid object state.
    Public Sub ProcessProduct(ByVal product As Product)
        Dim description As String = product.Description
        If description Is Nothing Then
            Throw New InvalidOperationException($"Product named {product.Name} had no description!")
        End If
        ' Process description...
    End Sub
End Class

Powiązane reguły

• CA1507: Użyj nameof zamiast ciągu