Редактиране

Споделяне чрез

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.

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, and N: 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;
    }
}