CA2016: Parameter "CancellationToken" an Methoden weiterleiten, die diesen Parameter akzeptieren.

Eigenschaft	Wert
Typname	ForwardCancellationTokenToInvocations
Regel-ID	CA2016
Titel	Parameter "CancellationToken" an Methoden weiterleiten, die diesen Parameter akzeptieren.
Kategorie	Zuverlässigkeit
Fix führt oder führt nicht zur Unterbrechung	Nicht unterbrechend
Standardmäßig in .NET 9 aktiviert	Als Vorschlag

Ursache

Diese Regel sucht Methodenaufrufe, die zwar einen CancellationToken-Parameter akzeptieren, aber keine übergeben, und schlägt vor, die übergeordneten Methoden CancellationToken an sie weiterzuleiten.

Regelbeschreibung

Diese Regel analysiert Methodendefinitionen, die einen CancellationToken als letzten Parameter annehmen, und analysiert dann alle Methoden, die im Textkörper aufgerufen werden. Wenn einer der Methodenaufrufe entweder einen CancellationToken als letzten Parameter akzeptieren oder über eine Überladung verfügen kann, die CancellationToken als den letzten Parameter annimmt, schlägt die Regel die Verwendung dieser Option vor, um sicherzustellen, dass die Abbruchbenachrichtigung an alle Vorgänge weitergegeben wird, die darauf lauschen können.

Hinweis

Die Regel CA2016 ist in allen .NET-Versionen verfügbar, in denen der CancellationToken-Typ verfügbar ist. Die anwendbaren Versionen finden Sie im CancellationToken-Abschnitt „Gilt für“.

Behandeln von Verstößen

Sie können Verstöße entweder manuell beheben oder den in Visual Studio verfügbaren Codefix verwenden. Zeigen Sie mit dem Mauszeiger auf die Glühbirne, die neben dem Methodenaufruf angezeigt wird, und wählen Sie die vorgeschlagene Änderung aus.

Im folgenden Beispiel werden zwei vorgeschlagene Änderungen gezeigt:

Es ist sicher, einen Verstoß gegen diese Regel zu unterdrücken, wenn Sie sich keine Gedanken darüber machen, wie die abgebrochene Vorgangsbenachrichtigung an niedrigere Methodenaufrufe weitergeleitet werden soll. Sie können auch default in C# (Nothing in Visual Basic) oder None explizit übergeben, um den Regelverstoß zu unterdrücken.

Die Regel kann eine Vielzahl von Verstößen erkennen. In den folgenden Beispielen werden Fälle gezeigt, die von der Regel erkannt werden können:

Beispiel 1

Die Regel wird vorschlagen, dass der c-Parameter von MyMethod zur MyMethodWithDefault-Invocation weitergeleitet wird, da die Methode einen optionalen Token-Paramter definiert:

using System.Threading;

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

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

Behebung:

Leiten Sie den c-Parameter weiter:

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

Wenn Sie sich keine Gedanken über das Weiterleiten von Abbruch-Benachrichtigungen an niedrigere Aufrufe machen, haben Sie folgende Möglichkeiten:

default explizit übergeben:

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

Oder CancellationToken.None explizit übergeben:

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

Beispiel 2

Die Regel wird vorschlagen, dass der c-Parameter von MyMethod zur MyMethodWithOverload-Invocation weitergeleitet wird, da die Methode eine Überladung aufweist, die einen CancellationToken-Parameter akzeptiert:

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

Behebung:

Leiten Sie den c-Parameter weiter:

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

Wenn Sie sich keine Gedanken über das Weiterleiten von Abbruch-Benachrichtigungen an niedrigere Aufrufe machen, haben Sie folgende Möglichkeiten:

default explizit übergeben:

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

Oder CancellationToken.None explizit übergeben:

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

Beispiele für Nichtverstoß

Der CancellationToken-Parameter in der übergeordneten Methode befindet sich nicht in der letzten 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();
        }
    }
}

Der CancellationToken-Parameter in der Standardmethode befindet sich nicht in der letzten 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();
        }
    }
}

Der CancellationToken-Parameter in der Überladungsmethode befindet sich nicht in der letzten 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();
        }
    }
}

Die übergeordnete Methode definiert mehr als einen CancellationToken-Parameter:

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

Die Methode mit Standardwerten definiert mehr als einen CancellationToken-Parameter:

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

Die Methodenüberladung definiert mehr als einen CancellationToken-Parameter:

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

Unterdrücken einer Warnung

Um nur eine einzelne Verletzung zu unterdrücken, fügen Sie der Quelldatei Präprozessoranweisungen hinzu, um die Regel zu deaktivieren und dann wieder zu aktivieren.

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

Um die Regel für eine Datei, einen Ordner oder ein Projekt zu deaktivieren, legen Sie den Schweregrad in der Konfigurationsdatei auf none fest.

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

Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken von Codeanalyse-Warnungen.