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

  • 發行項
屬性 值
規則識別碼 CA1062
標題 必須驗證公用方法的引數
類別 設計
修正程式是中斷或非中斷 不中斷
預設在 .NET 8 中啟用 No

原因

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

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

檔案描述

所有傳遞至外部可見方法的參考自變數都應該針對 null檢查。 如果適用，請在自變數為 null時擲回 ArgumentNullException 。

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

如何修正違規

若要修正此規則的違規，請針對 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 介面

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

dotnet_code_quality.CAXXXX.api_surface = private, internal

注意

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

排除特定符號

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

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

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

  • 只包含符號名稱（包含名稱的所有符號，不論包含類型或命名空間為何）。
  • 符號 檔案識別碼格式的完整名稱。 每個符號名稱都需要符號種類前置詞，例如 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) 比對特定方法和MyMethod1MyMethod2個別的完整簽章。

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

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

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

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

  • 僅限類型名稱（包含名稱的所有類型，不論包含類型或命名空間為何）。
  • 符號 文件識別碼格式的完整名稱，具有選擇性 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 比對特定類型和MyType1MyType2個別的完整名稱，以及其所有衍生型別。

排除擴充方法 『this』 參數

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

dotnet_code_quality.CA1062.exclude_extension_method_this_parameter = true

Null 檢查驗證方法

如果您的程式代碼在參考的連結庫或專案中呼叫特殊的 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) 比對特定方法和Validate1Validate2個別的完整簽章。

範例 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 的範例中， other 傳遞至複製建構函式的物件會先在方法中 PassThroughNonNull 檢查 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;
    }
}