CA2016 : Transférer le paramètre CancellationToken aux méthodes qui l’acceptent

Propriété	Valeur
Nom du type	ForwardCancellationTokenToInvocations
Identificateur de la règle	CA2016
Titre	Transférer le paramètre CancellationToken aux méthodes qui l’acceptent
Catégorie	Fiabilité
Le correctif est cassant ou non cassant	Sans rupture
Activé par défaut dans .NET 8	À titre de suggestion

Cause

Cette règle localise les appels de méthode qui peuvent accepter un paramètre CancellationToken, mais qui ne les transmettent pas, et suggère de leur transférer le CancellationToken de la méthode parente.

Description de la règle

Cette règle analyse les définitions de méthode qui acceptent un CancellationToken comme dernier paramètre, puis analyse toutes les méthodes appelées dans son corps. Si l’un des appels de méthode peut accepter un CancellationToken comme dernier paramètre ou avoir une surcharge qui prend un CancellationToken comme dernier paramètre, la règle suggère d’utiliser plutôt cette option afin de s’assurer que la notification d’annulation est propagée à toutes les opérations qui peuvent l’écouter.

Notes

La règle CA2016 est disponible dans toutes les versions de .NET où le type CancellationToken est disponible. Pour connaître les versions applicables, consultez la section « S’applique à » de CancellationToken.

Comment corriger les violations

Vous pouvez corriger les violations manuellement ou utiliser le correctif de code disponible dans Visual Studio. Pointez sur l’ampoule qui apparaît en regard de l’appel de méthode et sélectionnez la modification suggérée.

L’exemple suivant montre deux suggestions de modification :

Vous pouvez supprimer sans risque une violation de cette règle si vous n’êtes pas préoccupé par le transfert de la notification d’opération annulée à des appels de méthode inférieurs. Vous pouvez également passer default explicitement en C# (Nothing en Visual Basic) ou None pour supprimer la violation de règle.

La règle peut détecter diverses violations. Les exemples suivants illustrent les cas que la règle peut détecter :

Exemple 1

La règle suggère de transférer le paramètre c de MyMethod vers l’appel MyMethodWithDefault, car la méthode définit un paramètre de jeton facultatif :

using System.Threading;

namespace ConsoleApp
{
    public static class MyTestClass
    {
        public static void MyMethodWithDefault(CancellationToken ct = default)
        {
        }

        public static void MyMethod(CancellationToken c)
        {
            MyMethodWithDefault();
        }
    }
}

Correctif :

Transférez le paramètre c :

        public static void MyMethod(CancellationToken c)
        {
            MyMethodWithDefault(c);
        }

Si vous n’êtes pas préoccupé par le transfert des notifications d’annulation vers des appels inférieurs, vous pouvez :

Passer explicitement default :

        public static void MyMethod(CancellationToken c)
        {
            MyMethodWithDefault(default);
        }

Ou passer explicitement CancellationToken.None :

        public static void MyMethod(CancellationToken c)
        {
            MyMethodWithDefault(CancellationToken.None);
        }

Exemple 2

La règle suggère de transférer le paramètre c de MyMethod à l’appel MyMethodWithOverload, car la méthode a une surcharge qui prend un paramètre CancellationToken :

using System.Threading;

namespace ConsoleApp
{
    public static class MyTestClass
    {
        public static void MyMethodWithOverload()
        {
        }

        public static void MyMethodWithOverload(CancellationToken ct = default)
        {
        }

        public static void MyMethod(CancellationToken c)
        {
            MyMethodWithOverload();
        }
    }
}

Correctif :

Transférez le paramètre c :

        public static void MyMethod(CancellationToken c)
        {
            MyMethodWithOverload(c);
        }

Si vous n’êtes pas préoccupé par le transfert des notifications d’annulation vers des appels inférieurs, vous pouvez :

Passer explicitement default :

        public static void MyMethod(CancellationToken c)
        {
            MyMethodWithOverload(default);
        }

Ou passer explicitement CancellationToken.None :

        public static void MyMethod(CancellationToken c)
        {
            MyMethodWithOverload(CancellationToken.None);
        }

Exemples de non-violation

Le paramètre CancellationToken dans la méthode parente n’est pas à la dernière position :

using System.Threading;

namespace ConsoleApp
{
    public static class MyTestClass
    {
        public static void MyMethodWithDefault(CancellationToken ct = default)
        {
        }

        public static void MyMethod(CancellationToken c, int lastParameter)
        {
            MyMethodWithDefault();
        }
    }
}

Le paramètre CancellationToken dans la méthode par défaut n’est pas à la dernière position :

using System.Threading;

namespace ConsoleApp
{
    public static class MyTestClass
    {
        public static void MyMethodWithDefault(CancellationToken ct = default, int lastParameter = 0)
        {
        }

        public static void MyMethod(CancellationToken c)
        {
            MyMethodWithDefault();
        }
    }
}

Le paramètre CancellationToken dans la méthode de surcharge n’est pas à la dernière position :

using System.Threading;

namespace ConsoleApp
{
    public static class MyTestClass
    {
        public static void MyMethodWithOverload(int lastParameter)
        {
        }
        public static void MyMethodWithOverload(CancellationToken ct, int lastParameter)
        {
        }

        public static void MyMethod(CancellationToken c)
        {
            MyMethodWithOverload();
        }
    }
}

La méthode parente définit plusieurs paramètres CancellationToken :

using System.Threading;

namespace ConsoleApp
{
    public static class MyTestClass
    {
        public static void MyMethodWithDefault(CancellationToken ct = default)
        {
        }

        public static void MyMethod(CancellationToken c1, CancellationToken c2)
        {
            MyMethodWithDefault();
        }
    }
}

La méthode avec des valeurs par défaut définit plusieurs paramètres CancellationToken :

using System.Threading;

namespace ConsoleApp
{
    public static class MyTestClass
    {
        public static void MyMethodWithDefault(CancellationToken c1 = default, CancellationToken c2 = default)
        {
        }

        public static void MyMethod(CancellationToken c)
        {
            MyMethodWithDefault();
        }
    }
}

La surcharge de méthode définit plusieurs paramètres CancellationToken :

using System.Threading;

namespace ConsoleApp
{
    public static class MyTestClass
    {
        public static void MyMethodWithOverload(CancellationToken c1, CancellationToken c2)
        {
        }

        public static void MyMethodWithOverload()
        {
        }

        public static void MyMethod(CancellationToken c)
        {
            MyMethodWithOverload();
        }
    }
}

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

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.CA2016.severity = none

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