CA1062: Validate arguments of public methods

Value
Rule ID CA1062
Category Microsoft.Design
Fix is breaking or non-breaking Non-breaking

Cause

An externally visible method dereferences one of its reference arguments without verifying whether that argument is null (Nothing in Visual Basic).

The following aspects of this rule are configurable:

  • Whether or not to analyze extension method 'this' parameter.
  • Specify null check validation methods in referenced libraries or projects, which validate that arguments passed to it are non-null.
  • Parts of codebase to exclude from analysis.

Rule description

All reference arguments that are passed to externally visible methods should be checked against null. If appropriate, throw a 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, you should make 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.

Configurability

This rule has the following configurable options.

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 will then assume that arguments passed to this method are non-null after the call. For example, to mark all methods named Validate as null check validation methods, you can 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

Excluded symbol names

You can configure which parts of your codebase to exclude 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.CA1062.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:" prefix for methods, T: prefix for types, "N:" prefix for namespaces, etc.
  • .ctor for constructors and .cctor for static constructors

Examples:

Option Value Summary
dotnet_code_quality.CA1062.excluded_symbol_names = MyType Matches all symbols named 'MyType' in the compilation
dotnet_code_quality.CA1062.excluded_symbol_names = MyType1|MyType2 Matches all symbols named either 'MyType1' or 'MyType2' in the compilation
dotnet_code_quality.CA1062.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Matches specific method 'MyMethod' with given fully qualified signature
dotnet_code_quality.CA1062.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Matches specific methods 'MyMethod1' and 'MyMethod2' with respective fully qualified signature

You can configure all of these options for just this rule, for all rules, or for all rules in this category (Design). For more information, see Code quality rule configuration options.

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 field or properties that are reference objects can also violate the CA1062 rule. The violation occurs because the copied object that is 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 is 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;
    }
}