CA1062: Validate arguments of public methods
Property | Value |
---|---|
Rule ID | CA1062 |
Title | Validate arguments of public methods |
Category | Design |
Fix is breaking or non-breaking | Non-breaking |
Enabled by default in .NET 8 | No |
Cause
An externally visible method dereferences one of its reference arguments without verifying whether that argument is null
(Nothing
in Visual Basic).
You can configure this rule to exclude certain types and parameters from analysis. You can also indicate null-check validation methods.
Rule description
All reference arguments that are passed to externally visible methods should be checked against null
. If appropriate, throw an ArgumentNullException when the argument is null
.
If a method can be called from an unknown assembly because it is declared public or protected, you should validate all parameters of the method. If the method is designed to be called only by known assemblies, mark the method internal
and apply the InternalsVisibleToAttribute attribute to the assembly that contains the method.
How to fix violations
To fix a violation of this rule, validate each reference argument against null
.
When to suppress warnings
You can suppress a warning from this rule if you are sure that the dereferenced parameter has been validated by another method call in the function.
Suppress a warning
If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.
#pragma warning disable CA1062
// The code that's violating the rule is on this line.
#pragma warning restore CA1062
To disable the rule for a file, folder, or project, set its severity to none
in the configuration file.
[*.{cs,vb}]
dotnet_diagnostic.CA1062.severity = none
For more information, see How to suppress code analysis warnings.
Configure code to analyze
Use the following options to configure which parts of your codebase to run this rule on.
- Include specific API surfaces
- Exclude specific symbols
- Exclude specific types and their derived types
- Exclude extension method 'this' parameter
- Null check validation methods
These options can be configured for just this rule, for all rules it applies to, or for all rules in this category (Design) that it applies to. For more information, see Code quality rule configuration options.
Include specific API surfaces
You can configure which parts of your codebase to run this rule on, based on their accessibility. For example, to specify that the rule should run only against the non-public API surface, add the following key-value pair to an .editorconfig file in your project:
dotnet_code_quality.CAXXXX.api_surface = private, internal
Note
This option is supported for CA1062 in .NET 7 and later versions only.
Exclude specific symbols
You can exclude specific symbols, such as types and methods, from analysis. For example, to specify that the rule should not run on any code within types named MyType
, add the following key-value pair to an .editorconfig file in your project:
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType
Allowed symbol name formats in the option value (separated by |
):
- Symbol name only (includes all symbols with the name, regardless of the containing type or namespace).
- Fully qualified names in the symbol's documentation ID format. Each symbol name requires a symbol-kind prefix, such as
M:
for methods,T:
for types, andN:
for namespaces. .ctor
for constructors and.cctor
for static constructors.
Examples:
Option Value | Summary |
---|---|
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType |
Matches all symbols named MyType . |
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 |
Matches all symbols named either MyType1 or MyType2 . |
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) |
Matches specific method MyMethod with the specified fully qualified signature. |
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) |
Matches specific methods MyMethod1 and MyMethod2 with the respective fully qualified signatures. |
Exclude specific types and their derived types
You can exclude specific types and their derived types from analysis. For example, to specify that the rule should not run on any methods within types named MyType
and their derived types, add the following key-value pair to an .editorconfig file in your project:
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType
Allowed symbol name formats in the option value (separated by |
):
- Type name only (includes all types with the name, regardless of the containing type or namespace).
- Fully qualified names in the symbol's documentation ID format, with an optional
T:
prefix.
Examples:
Option Value | Summary |
---|---|
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType |
Matches all types named MyType and all of their derived types. |
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 |
Matches all types named either MyType1 or MyType2 and all of their derived types. |
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType |
Matches specific type MyType with given fully qualified name and all of its derived types. |
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 |
Matches specific types MyType1 and MyType2 with the respective fully qualified names, and all of their derived types. |
Exclude extension method 'this' parameter
By default, this rule analyzes and flags the this
parameter for extension methods. You can exclude analysis of the this
parameter for extension methods by adding the following key-value pair to an .editorconfig file in your project:
dotnet_code_quality.CA1062.exclude_extension_method_this_parameter = true
Null check validation methods
This rule can lead to false positives if your code calls special null-check validation methods in referenced libraries or projects. You can avoid these false positives by specifying the name or signature of null-check validation methods. The analysis assumes that arguments passed to these methods are non-null after the call. For example, to mark all methods named Validate
as null-check validation methods, add the following key-value pair to an .editorconfig file in your project:
dotnet_code_quality.CA1062.null_check_validation_methods = Validate
Allowed method name formats in the option value (separated by |
):
- Method name only (includes all methods with the name, regardless of the containing type or namespace).
- Fully qualified names in the symbol's documentation ID format, with an optional
M:
prefix.
Examples:
Option Value | Summary |
---|---|
dotnet_code_quality.CA1062.null_check_validation_methods = Validate |
Matches all methods named Validate in the compilation. |
dotnet_code_quality.CA1062.null_check_validation_methods = Validate1|Validate2 |
Matches all methods named either Validate1 or Validate2 in the compilation. |
dotnet_code_quality.CA1062.null_check_validation_methods = NS.MyType.Validate(ParamType) |
Matches specific method Validate with given fully qualified signature. |
dotnet_code_quality.CA1062.null_check_validation_methods = NS1.MyType1.Validate1(ParamType)|NS2.MyType2.Validate2(ParamType) |
Matches specific methods Validate1 and Validate2 with respective fully qualified signature. |
Example 1
The following example shows a method that violates the rule and a method that satisfies the rule.
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
Example 2
Copy constructors that populate fields or properties that are reference objects can also violate rule CA1062. The violation occurs because the copied object that's passed to the copy constructor might be null
(Nothing
in Visual Basic). To resolve the violation, use a static
(Shared
in Visual Basic) method to check that the copied object is not null.
In the following Person
class example, the other
object that is passed to the Person
copy constructor might be 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)
{
}
}
Example 3
In the following revised Person
example, the other
object that's passed to the copy constructor is first checked for null in the PassThroughNonNull
method.
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;
}
}
Atsiliepimai
https://aka.ms/ContentUserFeedback.
Jau greitai: 2024 m. palaipsniui atsisakysime „GitHub“ problemų, kaip turiniui taikomo atsiliepimų mechanizmo, ir pakeisime jį nauja atsiliepimų sistema. Daugiau informacijos žr.Pateikti ir peržiūrėti atsiliepimą, skirtą