CA1062: Validate arguments of public methods

#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 System.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 System.Runtime.CompilerServices.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

In addition, the following other dataflow analysis–related options apply to this rule:

• interprocedural_analysis_kind
• max_interprocedural_lambda_or_local_function_call_chain
• max_interprocedural_method_call_chain
• points_to_analysis_kind
• copy_analysis
• sufficient_IterationCount_for_weak_KDF_algorithm

These options can be configured for just this rule, for all rules they apply to, or for all rules in this category (Design) that they apply 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, by setting the api_surface option. 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

#Exclude specific symbols

You can exclude specific symbols, such as types and methods, from analysis by setting the excluded_symbol_names option. 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:

#Exclude specific types and their derived types

You can exclude specific types and their derived types from analysis by setting the excluded_type_names_with_derived_types option. 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:

#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:

#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;
    }
}