CA1062:必須驗證公用方法的引數
| 屬性 | 值 |
|---|---|
| 規則識別碼 | CA1062 |
| 職稱 | 必須驗證公用方法的引數 |
| 類別 | 設計 |
| 修正程式是中斷或非中斷 | 不中斷 |
| 預設在 .NET 9 中啟用 | 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;
}
}
