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 10 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 ct-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 ct)
        {
            MyMethodWithDefault();
        }
    }
}

Behebung:

Leiten Sie den ct-Parameter weiter:

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

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 ct)
{
    MyMethodWithDefault(default);
}

Oder CancellationToken.None explizit übergeben:

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

Beispiel 2

Die Regel wird vorschlagen, dass der ct-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 ct)
        {
            MyMethodWithOverload();
        }
    }
}

Behebung:

Leiten Sie den ct-Parameter weiter:

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

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 ct)
{
    MyMethodWithOverload(default);
}

Oder CancellationToken.None explizit übergeben:

public static void MyMethod(CancellationToken ct)
{
    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 ct, 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 ct)
        {
            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 ct)
        {
            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 ct1, CancellationToken ct2)
        {
            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 ct1 = default, CancellationToken ct2 = default)
        {
        }

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

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

using System.Threading;

namespace ConsoleApp
{
    public static class MyTestClass
    {
        public static void MyMethodWithOverload(CancellationToken ct1, CancellationToken ct2)
        {
        }

        public static void MyMethodWithOverload()
        {
        }

        public static void MyMethod(CancellationToken ct)
        {
            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 none auf fest.

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

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