CA2208:必須正確執行個體化引數例外狀況

屬性	值
規則識別碼	CA2208
標題	必須正確執行個體化引數例外狀況
類別	使用方式
修正程式是中斷或非中斷	不中斷
預設在 .NET 8 中啟用	建議

原因

當方法具有 參數，而且會擲回例外狀況類型，也就是 或衍生自 時， ArgumentException 預期會呼叫接受參數的 paramName 建構函式。 可能的原因包括下列情況：

• 對例外狀況類型的預設 （無參數） 建構函式進行呼叫，其為接受參數的建構函式，或衍生自 ArgumentException 該建構 paramName 函式。

• 不正確的字串引數會傳遞至例外狀況類型的參數化建構函式，或衍生自 ArgumentException 。

• 其中一個參數的名稱會針對 message 例外狀況類型之建構函式的引數傳遞，該引數為 或衍生自 ArgumentException 。

檔案描述

而不是呼叫預設建構函式，請呼叫其中一個建構函式多載，以允許提供更有意義的例外狀況訊息。 例外狀況訊息應以開發人員為目標，並清楚說明錯誤狀況，以及如何更正或避免例外狀況。

一和兩個字串建構 ArgumentException 函式及其衍生型別的簽章與位置和 messageparamName 參數不一致。 請確定使用正確的字串引數呼叫這些建構函式。 簽章如下所示：

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

如何修正違規

若要修正此規則的違規，請呼叫接受訊息、參數名稱或兩者的建構函式，並確定引數適用于所呼叫的類型 ArgumentException 。

提示

Visual Studio 中有一個程式碼修正程式碼，無法正確定位參數名稱。 若要使用它，請將游標放在警告資料列上，然後按 Ctrl + 。 （句號）。 從 所呈現的選項清單中選擇 [交換引數順序 ]。

如果參數名稱而非訊息傳遞至 ArgumentException(String) 方法，修正程式會提供切換至雙引數建構函式的選項。

隱藏警告的時機

只有在使用正確的字串引數呼叫參數化建構函式時，才能安全地隱藏此規則的警告。

隱藏警告

如果您只想要隱藏單一違規，請將預處理器指示詞新增至原始程式檔以停用，然後重新啟用規則。

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

若要停用檔案、資料夾或專案的規則，請在組態檔 中將其嚴重性設定為 。 none

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

如需詳細資訊，請參閱 如何隱藏程式碼分析警告 。

設定程式碼以分析

使用下列選項來設定程式碼基底要執行此規則的部分。

• 包含特定 API 介面

您可以只針對此規則、針對它套用的所有規則，或針對套用至此類別的所有規則，或針對它套用的所有規則，設定此選項。 如需詳細資訊，請參閱 程式碼品質規則組態選項 。

包含特定 API 介面

您可以根據程式碼基底的存取範圍，設定要執行此規則的部分。 例如，若要指定規則只應該針對非公用 API 介面執行，請將下列機碼/值組新增至 專案中的 .editorconfig 檔案：

dotnet_code_quality.CAXXXX.api_surface = private, internal

根據預設，CA2208 規則會套用至所有 API 介面（公用、內部和私用）。

範例

下列程式碼顯示不正確地具現化 實例的 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

下列程式碼會藉由切換建構函式引數來修正先前的違規。

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

相關規則

• CA1507:使用 nameof 取代字串