CA1068 : Les paramètres CancellationToken doivent venir en dernier

  • Article
Propriété Value
Identificateur de la règle CA1068
Titre Les paramètres CancellationToken doivent venir en dernier
Catégorie Conception
Le correctif est cassant ou non cassant Rupture
Activé par défaut dans .NET 8 À titre de suggestion

Cause

Une méthode a un paramètre CancellationToken qui n’est pas le dernier paramètre.

Par défaut, cette règle analyse l’intégralité du codebase, mais elle est configurable.

Description de la règle

Les méthodes qui effectuent des opérations de longue durée ou asynchrones et qui peuvent être annulées prennent normalement un paramètre de jeton d’annulation. Chaque jeton d’annulation a un CancellationTokenSource qui crée le jeton et l’utilise pour les calculs annulables. Il est courant d’avoir une longue chaîne d’appels de méthode qui passent le jeton d’annulation des appelants aux appelés. Par conséquent, un grand nombre de méthodes qui participent à un calcul annulable finissent par avoir un paramètre de jeton d’annulation. Toutefois, le jeton d’annulation lui-même n’est généralement pas pertinent pour les fonctionnalités principales de la plupart de ces méthodes. Il est considéré comme une bonne pratique de conception d’API de faire en sorte que ce paramètre soit le dernier de la liste.

Cas particuliers

La règle CA1068 ne se déclenche pas dans les cas spéciaux suivants :

  • La méthode a un ou plusieurs paramètres optional (Optional en Visual Basic) après un paramètre de jeton d’annulation non facultatif. Le compilateur exige que tous les paramètres facultatifs soient définis après tous les paramètres non facultatifs.
  • La méthode a un ou plusieurs paramètres ref ou out (ByRef en Visual Basic) après un paramètre de jeton d’annulation. Le placement des paramètres ref ou out à la fin de la liste est une pratique courante, car ils indiquent généralement des valeurs de sortie pour la méthode.

Comment corriger les violations

Modifiez la signature de méthode pour déplacer le paramètre de jeton d’annulation à la fin de la liste. Par exemple, les deux extraits de code suivants montrent une violation de la règle et comment la corriger :

// Violates CA1068
public void LongRunningOperation(CancellationToken token, string usefulParameter)
{
    ...
}

// Does not violate CA1068
public void LongRunningOperation(string usefulParameter, CancellationToken token)
{
    ...
}

Quand supprimer les avertissements

Si la méthode est une API publique visible en externe qui fait déjà partie d’une bibliothèque livrée, vous pouvez sans risque supprimer un avertissement de cette règle afin d’éviter un changement cassant pour les consommateurs de bibliothèque.

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

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.CA1068.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 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 :

Valeur d’option Récapitulatif
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType Correspond à tous les symboles nommés MyType.
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 Correspond à tous les symboles nommés MyType1 ou MyType2.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) Correspond à une méthode MyMethod spécifique avec la signature complète spécifiée.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) Correspond à des méthodes MyMethod1 et MyMethod2 spécifiques avec la signature complète spécifiée.

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 :

Valeur d’option Récapitulatif
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType Correspond à tous les types nommés MyType et à tous leurs types dérivés.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 Correspond à tous les types nommés MyType1 ou MyType2, et à tous leurs types dérivés.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType Correspond à un type MyType spécifique avec un nom complet donné et tous ses types dérivés.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 Correspond à des types MyType1 ou MyType2 spécifiques avec leur nom complet respectif et tous leurs types dérivés.

Voir aussi