CA2016：將 CancellationToken 參數傳遞給使用該參數的方法

發行項
11/12/2024

屬性	值
類型名稱	ForwardCancellationTokenToInvocations
規則識別碼	CA2016
職稱	將 CancellationToken 參數傳遞給使用該參數的方法
類別	可靠性
修正程式是中斷或非中斷	不中斷
預設在 .NET 9 中啟用	建議

原因

此規則會找出可以接受 CancellationToken 參數的方法調用，但不會傳遞任何參數，並建議將父方法的 CancellationToken 轉送至它們。

檔案描述

此規則會分析採用作為其最後一個 CancellationToken 參數的方法定義，然後分析在其主體中叫用的所有方法。如果任一方法調用可以接受 CancellationToken 做為最後一個參數，或具有採用作為最後一個參數的多載 CancellationToken ，則規則會建議改用該選項，以確保取消通知會傳播到可接聽它的所有作業。

注意

規則 CA2016 適用於所有可用的 .NET 版本 CancellationToken 。如需適用的版本，請參閱 CancellationToken「適用於」一節。

如何修正違規

您可以手動修正違規，或使用 Visual Studio 中可用的程式代碼修正。將燈泡暫留在方法調用旁邊，然後選取建議的變更。

下列範例顯示兩個建議的變更：

規則 CA2016 - 將 CancellationToken 參數轉送至採用一個方法的方法

如果您不擔心將取消的作業通知轉送至較低的方法調用，則隱藏此規則的違規是安全的。您也可以明確地傳入 default C# （Nothing 在 Visual Basic 中），或 None 隱藏規則違規。

此規則可以偵測各種違規。下列範例顯示規則可以偵測到的案例：

範例 1

規則會建議將 c 參數從 MyMethod 轉送至 MyMethodWithDefault 調用，因為方法會定義選擇性的 Token 參數：

using System.Threading;

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

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

修正：

c轉寄參數：

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

如果您不擔心將取消通知轉送至較低的調用，您可以：

明確傳遞 default：

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

或明確傳遞 CancellationToken.None：

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

範例 2

規則會建議將參數從 MyMethod 轉送c至MyMethodWithOverload調用，因為方法具有採用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();
        }
    }
}

修正：

c轉寄參數：

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

如果您不擔心將取消通知轉送至較低的調用，您可以：

明確傳遞 default：

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

或明確傳遞 CancellationToken.None：

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

非違規範例

CancellationToken父方法中的參數不在最後一個位置：

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

CancellationToken預設方法中的參數不在最後一個位置：

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

CancellationToken多載方法中的參數不在最後一個位置：

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

父方法會定義多個 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();
        }
    }
}

預設值的方法會定義一個 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();
        }
    }
}

方法多載會定義多個 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();
        }
    }
}

隱藏警告

如果您只想要隱藏單一違規，請將預處理器指示詞新增至原始程式檔以停用，然後重新啟用規則。

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

若要停用檔案、資料夾或項目的規則，請在組態檔中將其嚴重性設定為。none

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

如需詳細資訊，請參閱如何隱藏程式代碼分析警告。

共用方式為