CA1062 : Valider les arguments de méthodes publiques

Cause

Une méthode visible en externe déréférence l’un de ses arguments de référence sans vérifier si cet argument est null (Nothing dans Visual Basic).

Vous pouvez configurer cette règle pour exclure certains types et paramètres de l’analyse. Vous pouvez également indiquer des méthodes de validation par contrôles de valeur null.

Description de la règle

Tous les arguments de référence validés par les méthodes visibles en externe doivent être vérifiés pour voir s’ils ont la valeur null. Si nécessaire, levez une valeur ArgumentNullException lorsque l’argument est null.

Si une méthode peut être appelée à partir d’un assembly inconnu, car elle est déclarée publique ou protégée, vous devez valider tous les paramètres de la méthode. Si la méthode est conçue pour être appelée uniquement par les assemblys connus, marquez la méthode comme internal et appliquez l’attribut InternalsVisibleToAttribute à l’assembly qui contient la méthode.

Comment corriger les violations

Pour corriger une violation de cette règle, validez chaque argument de référence par rapport à null.

Quand supprimer les avertissements

Vous pouvez supprimer un avertissement de cette règle si vous êtes sûr que le paramètre de déréférencement a été validé par un autre appel de méthode dans la fonction.

Supprimer un avertissement

Si vous voulez supprimer une seule violation, ajoutez des directives de préprocesseur à votre fichier source pour désactiver et réactiver la règle.

#pragma warning disable CA1062
// The code that's violating the rule is on this line.
#pragma warning restore CA1062

Pour désactiver la règle sur un fichier, un dossier ou un projet, définissez sa gravité sur none dans le fichier de configuration.

[*.{cs,vb}]
dotnet_diagnostic.CA1062.severity = none

Pour plus d’informations, consultez Comment supprimer les avertissements de l’analyse de code.

Configurer le code à analyser

Utilisez l’option suivante pour configurer les parties de votre codebase sur lesquelles exécuter cette règle.

• Inclure des surfaces d’API spécifiques
• Exclure des symboles spécifiques
• Exclure des types spécifiques et leurs types dérivés
• Exclusion du paramètre 'this' de la méthode d’extension
• Méthodes de validation par contrôles de valeur null

Vous pouvez configurer toutes ces options pour cette règle uniquement, pour toutes les règles auxquelles elles s’appliquent ou pour toutes les règles de cette catégorie (Conception) auxquelles elles s’appliquent. Pour plus d’informations, consultez Options de configuration des règles de qualité du code.

Inclure des surfaces d’API spécifiques

Vous pouvez configurer les parties de votre codebase sur lesquelles exécuter cette règle, en fonction de leur accessibilité. Par exemple, pour spécifier que la règle doit s’exécuter uniquement sur la surface d’API non publique, ajoutez la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

dotnet_code_quality.CAXXXX.api_surface = private, internal

Exclure des symboles spécifiques

Vous pouvez exclure de l’analyse des symboles spécifiques, comme des types et des méthodes. Par exemple, pour spécifier que la règle ne doit pas s’exécuter sur du code dans des types nommés MyType, ajoutez la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Formats de nom de symbole autorisés dans la valeur d’option (séparés par |) :

• Nom du symbole uniquement (inclut tous les symboles avec le nom, quel que soit le type ou l’espace de noms qui les contient).
• Noms qualifiés complets au format d’ID de documentation du symbole. Chaque nom de symbole nécessite un préfixe de type symbole, comme M: pour les méthodes, T: pour les types et N: pour les espaces de noms.
• .ctor pour les constructeurs et .cctor pour les constructeurs statiques.

Exemples :

Exclure des types spécifiques et leurs types dérivés

Vous pouvez exclure de l’analyse des types spécifiques et leurs types dérivés. Par exemple, pour spécifier que la règle ne doit s’exécuter sur aucune méthode dans des types nommés MyType et leurs types dérivés, ajoutez la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Formats de nom de symbole autorisés dans la valeur d’option (séparés par |) :

• Nom du type uniquement (inclut tous les types avec le nom, quel que soit le type ou l’espace de noms qui les contient).
• Noms qualifiés complets au format d’ID de documentation du symbole, avec un préfixe T: facultatif.

Exemples :

Exclusion du paramètre 'this' de la méthode d’extension

Par défaut, cette règle analyse et marque le paramètre this pour les méthodes d’extension. Vous pouvez exclure l’analyse du paramètre this pour les méthodes d’extension en ajoutant la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

dotnet_code_quality.CA1062.exclude_extension_method_this_parameter = true

Méthodes de validation par contrôles de valeur null

Cette règle peut entraîner des faux positifs si votre code appelle des méthodes de validation par contrôles de valeur null spéciales dans des bibliothèques ou des projets référencés. Vous pouvez éviter ces faux positifs en indiquant le nom ou la signature des méthodes de validation par contrôle de valeur null. L’analyse suppose que les arguments validés par ces méthodes ne présentent pas la valeur null après l’appel. Par exemple, pour marquer toutes les méthodes nommées Validate comme méthodes de validation par contrôles de valeur null, ajoutez la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

dotnet_code_quality.CA1062.null_check_validation_methods = Validate

Formats de nom de méthode autorisés dans la valeur d’option (séparés par |) :

• Nom de la méthode uniquement (inclut toutes les méthodes portant le nom, quel que soit le type ou l’espace de noms conteneur).
• Noms qualifiés complets au format d’ID de documentation du symbole, avec un préfixe M: facultatif.

Exemples :

Exemple 1

L’exemple suivant montre une méthode qui enfreint la règle et une méthode qui est conforme à la règle.

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

Exemple 2

Les constructeurs de copie qui remplissent des champs ou des propriétés qui sont des objets de référence peuvent également enfreindre la règle CA1062. La violation se produit parce que l’objet copié validé par le constructeur de copie peut être null (Nothing dans Visual Basic). Pour résoudre la violation, utilisez une méthode static (Shared dans Visual Basic) pour vérifier que l’objet copié ne présente pas la valeur null.

Dans l’exemple de classe Person suivant, l’objet other validé par le constructeur de copie Person peut être 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)
    {
    }
}

Exemple 3

Dans l’exemple Person révisé suivant, l’objet other validé par le constructeur de copie est d’abord contrôlé pour la valeur null dans la méthode PassThroughNonNull.

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