Note
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de changer d’annuaire.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de changer d’annuaire.
| 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 10 | À titre de 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 dérivé ou dérivé d’un ArgumentException constructeur qui accepte également un
paramNameparamètre. - Un argument de chaîne incorrect est passé à un constructeur paramétrisé d’un type d’exception qui est ou dérive de ArgumentException. Par exemple, l’argument
paramNamene correspond pas au nom de l’un des paramètres de la méthode. - Un nom de paramètre est passé pour l’argument
messagedu constructeur d’un 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 :
ArgumentException(string message)ArgumentException(string message, string paramName)ArgumentNullException(string paramName)ArgumentNullException(string paramName, string message)ArgumentOutOfRangeException(string paramName)ArgumentOutOfRangeException(string paramName, string message)DuplicateWaitObjectException(string parameterName)DuplicateWaitObjectException(string parameterName, string message)
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.
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.
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é, en définissant l'option api_surface. 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
Remarque
Remplacez la partie XXXX de CAXXXX par l’ID de la règle applicable.
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
Le code suivant montre une méthode qui jette incorrectement ArgumentNullException avec un paramName qui ne correspond à aucun des paramètres de la méthode. La règle se déclenche, car il s’agit description d’une variable locale, et non d’un paramètre de méthode.
public class Product
{
public string? Description { get; set; }
public string Name { get; set; } = string.Empty;
}
public class Example
{
// Violates CA2208: 'description' is not a parameter of this method.
public void ProcessProduct(Product product)
{
string? description = product.Description;
if (description is null)
{
throw new ArgumentNullException(nameof(description), $"Product named {product.Name} had no description!");
}
// Process description...
}
}
Public Class Product
Public Property Description As String
Public Property Name As String = String.Empty
End Class
Public Class Example
' Violates CA2208: 'description' is not a parameter of this method.
Public Sub ProcessProduct(ByVal product As Product)
Dim description As String = product.Description
If description Is Nothing Then
Throw New ArgumentNullException(NameOf(description), $"Product named {product.Name} had no description!")
End If
' Process description...
End Sub
End Class
Le code suivant corrige la violation précédente en utilisant InvalidOperationException à la place, ce qui convient quand l’état d’un objet n’est pas valide.
public class Product
{
public string? Description { get; set; }
public string Name { get; set; } = string.Empty;
}
public class Example
{
// Fixed: Use InvalidOperationException for invalid object state.
public void ProcessProduct(Product product)
{
string? description = product.Description;
if (description is null)
{
throw new InvalidOperationException($"Product named {product.Name} had no description!");
}
// Process description...
}
}
Public Class Product
Public Property Description As String
Public Property Name As String = String.Empty
End Class
Public Class Example
' Fixed: Use InvalidOperationException for invalid object state.
Public Sub ProcessProduct(ByVal product As Product)
Dim description As String = product.Description
If description Is Nothing Then
Throw New InvalidOperationException($"Product named {product.Name} had no description!")
End If
' Process description...
End Sub
End Class
Règles associées
Collaborez avec nous sur GitHub
La source de ce contenu se trouve sur GitHub, où vous pouvez également créer et examiner des issues et des pull requests. Pour plus d’informations, consultez notre guide des contributeurs.
