CA2208 : Instanciez les exceptions d'argument comme il se doit

  • Article
Propriété Value
Identificateur de la règle CA2208
Titre Instanciez les exceptions d'argument comme il se doit
Catégorie Utilisation
Le correctif est cassant ou non cassant Sans rupture
Activé par défaut dans .NET 8 Comme suggestion

Cause

Lorsqu’une méthode comporte un paramètre et qu’elle lève un type d’exception qui est ou dérive de ArgumentException, il est attendu que l’on appelle un constructeur acceptant correctement un paramètre paramName. Les causes possibles incluent les situations suivantes :

  • Un appel est effectué au constructeur par défaut (sans paramètre) d’un type d’exception qui est ou dérive d’un ArgumentException qui a un constructeur acceptant un paramètre paramName.

  • Un argument de chaîne incorrect est passé à un constructeur paramétrisé d’un type d’exception qui est ou dérive de ArgumentException.

  • L’un des noms des paramètres est passé pour l’argument message du constructeur du type d’exception qui est ou dérive de ArgumentException.

Description de la règle

Au lieu d’appeler le constructeur par défaut, appelez l’une des surcharges du constructeur qui permet de fournir un message d’exception plus significatif. Le message d’exception doit cibler le développeur et expliquer clairement la condition d’erreur et comment corriger ou éviter l’exception.

Les signatures des constructeurs de chaînes un et deux de ArgumentException et de ses types dérivés ne sont pas cohérentes par rapport aux paramètres message et paramName de la position. Assurez-vous que ces constructeurs sont appelés avec les arguments de chaîne appropriés. Les signatures sont les suivantes :

Comment corriger les violations

Pour corriger une violation de cette règle, appelez un constructeur qui accepte un message, un nom de paramètre ou les deux, et vérifiez que les arguments sont appropriés pour le type de ArgumentException qui est appelé.

Conseil

Un correctif de code est disponible dans Visual Studio pour les noms de paramètres mal positionnés. Pour l’utiliser, positionnez le curseur sur la ligne d’avertissement et appuyez sur Ctrl+. (point). Choisissez Échanger l’ordre des arguments dans la liste des options présentées.

Code fix for CA2208 - swap arguments.

Si un nom de paramètre est passé à la méthode ArgumentException(String) au lieu d’un message, le correcteur offre l’option de basculer vers le constructeur à deux arguments à la place.

Code fix for CA2208 - switch to two-argument constructor.

Quand supprimer les avertissements

Vous pouvez supprimer un avertissement de cette règle de manière sécurisée uniquement si un constructeur paramétrisé est appelé avec les arguments de chaîne corrects.

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 CA2208
// The code that's violating the rule is on this line.
#pragma warning restore CA2208

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.CA2208.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.

Vous pouvez configurer cette option pour cette règle uniquement, pour toutes les règles auxquelles elle s’applique ou pour toutes les règles de cette catégorie (Conception) auxquelles elle s’applique. 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

Par défaut, la règle CA2208 s’applique à toutes les aires d’API (publiques, internes et privées).

Exemple

Le code suivant montre un constructeur qui instancie incorrectement une instance de ArgumentNullException.

public class Book
{
    public Book(string title)
    {
        Title = title ??
            throw new ArgumentNullException("All books must have a title.", nameof(title));
    }

    public string Title { get; }
}

Public Class Book

    Private ReadOnly _Title As String

    Public Sub New(ByVal title As String)
        ' Violates this rule (constructor arguments are switched)            
        If (title Is Nothing) Then
            Throw New ArgumentNullException("title cannot be a null reference (Nothing in Visual Basic)", "title")
        End If
        _Title = title
    End Sub

    Public ReadOnly Property Title()
        Get
            Return _Title
        End Get
    End Property

End Class

Le code suivant corrige la violation précédente en changeant les arguments du constructeur.

public class Book
{
    public Book(string title)
    {
        Title = title ??
            throw new ArgumentNullException(nameof(title), "All books must have a title.");
    }

    public string Title { get; }
}

Public Class Book

    Private ReadOnly _Title As String

    Public Sub New(ByVal title As String)
        If (title Is Nothing) Then
            Throw New ArgumentNullException("title", "title cannot be a null reference (Nothing in Visual Basic)")
        End If

        _Title = title
    End Sub

    Public ReadOnly Property Title()
        Get
            Return _Title
        End Get
    End Property

End Class