CA2208: Argumentum-kivételek helyes példányosítása

Tulajdonság	Érték
Szabályazonosító	CA2208
Cím	Argumentum-kivételek helyes példányosítása
Kategória	Használat
A javítás kompatibilitástörő vagy nem törik	Nem törés
Alapértelmezés szerint engedélyezve a .NET 10-ben	Javaslatként

Ok

Ha egy metódus paraméterrel rendelkezik, és olyan kivételtípust ad ki, amelyből származik vagy származik, ArgumentExceptionakkor egy konstruktornak megfelelően kell meghívnia egy paramétert elfogadó konstruktort paramName . A lehetséges okok közé tartoznak a következő helyzetek:

• Egy olyan kivételtípus alapértelmezett (paraméter nélküli) konstruktorának hívása történik, amely egy paramétert elfogadó ArgumentException konstruktorsal is rendelkezik. paramName
• A rendszer helytelen sztringargumentumot ad át egy olyan kivételtípus paraméteres konstruktorának, amely vagy amelyből származik. ArgumentException Az argumentum például paramName nem egyezik a metódus egyik paraméterének nevével.
• A rendszer paraméternevet ad át egy message kivételtípus konstruktorának argumentumához, amely a következőből származik ArgumentException.

Szabály leírása

Az alapértelmezett konstruktor meghívása helyett hívja meg az egyik konstruktor túlterhelését, amely lehetővé teszi, hogy értelmesebb kivételüzenetet adjon meg. A kivételüzenetnek a fejlesztőre kell irányulnia, és egyértelműen meg kell magyaráznia a hibafeltételt, valamint a kivétel kijavításának vagy elkerülésének módját.

Az egy és két sztring konstruktorának ArgumentException és származtatott típusainak aláírásai nem összhangban vannak a pozícióval message és paramName a paraméterekkel. Győződjön meg arról, hogy ezek a konstruktorok a megfelelő sztringargumentumokkal vannak meghívva. Az aláírások a következők:

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

Szabálysértések kijavítása

A szabály megsértésének kijavításához hívjon meg egy olyan konstruktort, amely üzenetet, paraméternevet vagy mindkettőt használ, és győződjön meg arról, hogy az argumentumok megfelelőek a meghívott típushoz ArgumentException .

Tipp.

A Visual Studióban kódjavítás érhető el a helytelenül elhelyezett paraméternevekhez. A használatához helyezze a kurzort a figyelmeztető sorra, és nyomja le a Ctrl+ billentyűt. (pont). Válassza az argumentumok sorrendjének felcserélése lehetőséget a megjelenő lehetőségek listájából.

Ha üzenet helyett paraméternevet ad át a ArgumentException(String) metódusnak, a javító lehetővé teszi, hogy inkább a két argumentumos konstruktorra váltson.

Mikor kell letiltani a figyelmeztetéseket?

A szabály figyelmeztetését csak akkor lehet letiltani, ha egy paraméteres konstruktort a megfelelő sztringargumentumokkal hív meg.

Figyelmeztetés mellőzése

Ha csak egyetlen szabálysértést szeretne letiltani, adjon hozzá előfeldolgozási irányelveket a forrásfájlhoz a szabály letiltásához és újbóli engedélyezéséhez.

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

Ha le szeretné tiltani egy fájl, mappa vagy projekt szabályát, állítsa annak súlyosságát none a konfigurációs fájlban.

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

További információ: Kódelemzési figyelmeztetések letiltása.

Kód konfigurálása elemzéshez

A következő beállítással konfigurálhatja, hogy a kódbázis mely részein futtassa ezt a szabályt.

• Adott API-felületek belefoglalása

Ezt a beállítást konfigurálhatja csak ehhez a szabályhoz, az összes szabályhoz, vagy az ebben a kategóriában (Tervezés) szereplő összes szabályhoz, amelyekre vonatkozik. További információ: Kódminőségi szabály konfigurációs beállításai.

Adott API-felületek belefoglalása

A api_surface beállítással konfigurálhatja, hogy a kódbázis mely részein futtassa a szabályt az akadálymentességük alapján. Ha például meg szeretné adni, hogy a szabály csak a nem nyilvános API-felületen fusson, adja hozzá a következő kulcs-érték párot a projekt egyik .editorconfig fájljához:

dotnet_code_quality.CAXXXX.api_surface = private, internal

Jegyzet

Cserélje le a XXXXCAXXXX részét a vonatkozó szabály azonosítójára.

Alapértelmezés szerint a CA2208 szabály minden API-felületre (nyilvános, belső és privát) érvényes.

Példa

Az alábbi kód egy konstruktort mutat be, amely helytelenül példányosítja a példányt 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

Az alábbi kód a konstruktor argumentumainak átváltásával kijavítja az előző szabálysértést.

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

Az alábbi kód olyan módszert mutat be, amely helytelenül dob egy ArgumentNullExceptionparamName, amelyik nem felel meg a metódus egyik paraméterének sem. A szabály azért aktiválódik, mert description helyi változó, nem metódusparaméter.

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

Az alábbi kód az előző szabálysértést kijavítja azáltal, hogy ahelyett InvalidOperationException-t használ, ami megfelelő, amikor egy objektum állapota érvénytelen.

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

Kapcsolódó szabályok

• CA1507: A sztring helyett a név megadása