CA1062: 必須驗證公用方法的參數

屬性	值
規則識別碼	CA1062
職稱	驗證公共方法的參數
類別	設計
修正是造成中斷還是不中斷	不中斷
在 .NET 10 中預設啟用	否
適用語言	C# 與 Visual Basic

原因

外部可見的方法會取值它的其中一個參考自變數，而不驗證該自變數是否為 null （Nothing 在 Visual Basic 中）。

您可以 設定 此規則來排除分析中的特定類型和參數。 您也可以 指出空值檢查驗證方法。

規則描述

所有傳遞至外部可見方法的參考參數都應該針對 null 檢查。 如果適用，當參數為 null 時，拋出 ArgumentNullException。

如果方法可以從未知元件呼叫，因為它宣告為公用或受保護，您應該驗證方法的所有參數。 如果方法的設計是只能由已知的組件呼叫，請標記該方法，並在包含該方法的元件上套用InternalsVisibleToAttribute屬性。

如何修正違規

若要修正此規則的違規，請針對 null驗證每個參考自變數。

隱藏警告的時機

如果您確定已由函式中的另一個方法呼叫驗證取值參數，則可以隱藏此規則的警告。

隱藏警告

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

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

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

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

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

設定程式代碼以分析

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

• 包含特定 API 介面
• 排除特定符號
• 排除特定類型及其衍生類型
• 排除擴充方法 『this』 參數
• Null 檢查驗證方法

此外，下列其他數據流分析相關選項適用於此規則：

• 跨程序分析類型
• max_interprocedural_lambda_or_local_function_call_chain
• max_interprocedural_method_call_chain
• points_to_analysis_kind
• copy_analysis
• 足夠_迭代計數_用於_弱_KDF_算法

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

包含特定 API 介面

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

dotnet_code_quality.CAXXXX.api_surface = private, internal

注意

以適用規則的標識碼取代 XXXX 的 CAXXXX 部分。

注意

僅限 .NET 7 和更新版本中的 CA1062 支援此選項。

排除特定符號

您可以藉由設定 [excluded_symbol_names] 選項，從分析中排除特定符號，例如類型和方法。 例如，若要指定規則不應該在名為 MyType的任何程式代碼上執行，請將下列機碼/值組新增至 專案中的 .editorconfig 檔案：

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

注意

以適用規則的標識碼取代 XXXX 的 CAXXXX 部分。

選項值中允許的符號名稱格式（以 |分隔）：

• 只含符號名稱（包括名稱的所有符號，不論其所屬類型或命名空間）。
• 符號的 文件識別碼格式中的完整名稱。 每個符號名稱都需要符號種類前置詞，例如 M: 方法、 T: 類型和 N: 命名空間。
• .ctor 用於建構函式和 .cctor 靜態建構函式。

範例：

選項值	摘要
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType	符合所有名為 MyType的符號。
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2	比對名為 MyType1 或 MyType2的所有符號。
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType)	比對特定方法 MyMethod 與指定的完整簽章。
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType)	比對特定方法 MyMethod1 和 MyMethod2，及其各自的完整簽章。

排除特定類型及其衍生類型

您可以藉由設定 [excluded_type_names_with_derived_types] 選項，從分析中排除特定類型及其衍生類型。 例如，若要指定規則不應該在具名 MyType 類型及其衍生型別內的任何方法上執行，請將下列機碼/值組新增至 專案中的 .editorconfig 檔案：

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

注意

以適用規則的標識碼取代 XXXX 的 CAXXXX 部分。

選項值中允許的符號名稱格式（以 |分隔）：

• 僅輸入類型名稱（包含該名稱的所有類型，不論包含類型或命名空間為何）。
• 符號的 文件識別碼格式中的完整限定名稱，具有可選的 T: 前置字首。

範例：

選項值	摘要
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType	比對所有具名 MyType 的類型及其所有衍生型別。
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2	比對所有名為 MyType1 或 MyType2 的型別，以及其所有衍生型別。
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType	比對指定完整名稱的特定類型 MyType 及其所有衍生類型。
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2	比對特定類型 MyType1 和 MyType2 及其所有衍生類型的完整名稱。

排除擴充方法 『this』 參數

根據預設，此規則會針對擴充方法的參數進行分析和標記 this。 您可以將下列索引鍵/值組新增至專案中的 .editorconfig 檔案，以排除擴充方法 this 參數的分析。

dotnet_code_quality.CA1062.exclude_extension_method_this_parameter = true

Null 檢查驗證方法

如果您的程式碼在參考的函式庫或專案中呼叫特殊的空值檢查驗證方法，此規則可能會導致誤報。 您可以藉由指定 Null 檢查驗證方法的名稱或簽章來避免這些誤判。 分析假設傳遞至這些方法的參數在呼叫後不是 Null 值。 例如，若要將所有名為 Validate 的方法標示為 null 檢查驗證方法，請將下列機碼/值組新增至 專案中的 .editorconfig 檔案：

dotnet_code_quality.CA1062.null_check_validation_methods = Validate

選項值中允許的方法名稱格式（以 |分隔）：

• 方法名稱僅考慮（包括所有具有此名稱的方法，不論所屬類型或命名空間為何）。
• 符號的 文件識別碼格式中的完整限定名稱，具有可選的 M: 前置字首。

範例：

選項值	摘要
dotnet_code_quality.CA1062.null_check_validation_methods = Validate	比對編譯中名為 Validate 的所有方法。
dotnet_code_quality.CA1062.null_check_validation_methods = Validate1|Validate2	比對編譯中名為 Validate1 或 Validate2 的所有方法。
dotnet_code_quality.CA1062.null_check_validation_methods = NS.MyType.Validate(ParamType)	比對具有指定完整簽章的特定方法 Validate 。
dotnet_code_quality.CA1062.null_check_validation_methods = NS1.MyType1.Validate1(ParamType)|NS2.MyType2.Validate2(ParamType)	比對特定方法Validate1和Validate2以及其各自的完整簽章。

範例 1

下列範例顯示違反規則的方法和符合規則的方法。

using System;

namespace DesignLibrary
{
    public class Test
    {
        // This method violates the rule.
        public void DoNotValidate(string input)
        {
            if (input.Length != 0)
            {
                Console.WriteLine(input);
            }
        }

        // This method satisfies the rule.
        public void Validate(string input)
        {
            if (input == null)
            {
                throw new ArgumentNullException(nameof(input));
            }
            if (input.Length != 0)
            {
                Console.WriteLine(input);
            }
        }
    }
}

Imports System

Namespace DesignLibrary

    Public Class Test

        ' This method violates the rule.
        Sub DoNotValidate(ByVal input As String)

            If input.Length <> 0 Then
                Console.WriteLine(input)
            End If

        End Sub

        ' This method satisfies the rule.
        Sub Validate(ByVal input As String)

            If input Is Nothing Then
                Throw New ArgumentNullException(NameOf(input))
            End If

            If input.Length <> 0 Then
                Console.WriteLine(input)
            End If

        End Sub

    End Class

End Namespace

範例 2

複製填入參考物件的欄位或屬性的建構函式，也可能違反規則 CA1062。 發生違規的原因是傳遞至複製建構函式的複製物件可能是 null （Nothing 在 Visual Basic 中）。 若要解決違規問題，請使用 static （Shared 在 Visual Basic 中為 ） 方法來檢查複製的物件是否不是 Null。

在下列 Person 類別範例中， other 傳遞至 Person 複製建構函式的物件可能是 null。

public class Person
{
    public string Name { get; private set; }
    public int Age { get; private set; }

    public Person(string name, int age)
    {
        Name = name;
        Age = age;
    }

    // Copy constructor CA1062 fires because other is dereferenced
    // without being checked for null
    public Person(Person other)
        : this(other.Name, other.Age)
    {
    }
}

範例 3

在下列修訂的 Person 範例中，會首先在 PassThroughNonNull 方法中檢查由 other 傳遞至複製建構子的物件是否為 Null。

public class Person
{
    public string Name { get; private set; }
    public int Age { get; private set; }

    public Person(string name, int age)
    {
        Name = name;
        Age = age;
    }

    // Copy constructor
    public Person(Person other)
        : this(PassThroughNonNull(other).Name, other.Age)
    {
    }

    // Null check method
    private static Person PassThroughNonNull(Person person)
    {
        if (person == null)
            throw new ArgumentNullException(nameof(person));
        return person;
    }
}