CA2016: Encaminhe o parâmetro CancellationToken para os métodos que recebem um

Property	Valor
Nome do tipo	ForwardCancellationTokenToInvocations
ID da regra	CA2016
Título	Encaminhe o parâmetro CancellationToken para os métodos que recebem um
Categoria	Confiabilidade
Correção interruptiva ou sem interrupção	Sem interrupção
Habilitado por padrão no .NET 10	Como sugestão

Causa

Essa regra localiza invocações de método que podem aceitar um parâmetro CancellationToken, mas não estão passando nenhum, e sugere encaminhar CancellationToken do método pai para eles.

Descrição da regra

Essa regra analisa definições de método que pegam um CancellationToken como último parâmetro e então analisa todos os métodos invocados em seu corpo. Se qualquer uma das invocações de método pode aceitar um CancellationToken como o último parâmetro ou tem uma sobrecarga que usa um parâmetro CancellationToken como o último parâmetro, a regra sugere usar essa opção para garantir que a notificação de cancelamento seja propagada para todas as operações que podem ouvi-la.

Observação

A regra CA2016 está disponível em todas as versões do .NET em que o tipo CancellationToken está disponível. Para versões aplicáveis, confira a seção CancellationToken "Aplica-se a".

Como corrigir violações

Você pode corrigir violações manualmente ou usar a correção de código disponível no Visual Studio. Focalize com o cursor do mouse a lâmpada que aparece ao lado da invocação do método e selecione a alteração sugerida.

O seguinte exemplo mostra duas alterações sugeridas:

É seguro suprimir uma violação dessa regra se você não está preocupado em encaminhar a notificação de operação cancelada para invocações de método inferior. Você também pode passar default explicitamente em C# (Nothing no Visual Basic) ou None para suprimir a violação de regra.

A regra pode detectar uma variedade de violações. Os seguintes exemplos mostram casos que a regra pode detectar:

Exemplo 1

A regra sugerirá o encaminhamento do parâmetro ct de MyMethod para a invocação MyMethodWithDefault, pois o método define um parâmetro de token opcional:

using System.Threading;

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

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

Correção:

Encaminhe o parâmetro ct:

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

Se você não estiver preocupado em encaminhar notificações de cancelamento para invocações mais baixas, poderá:

Passar explicitamente default:

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

Ou passar explicitamente CancellationToken.None:

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

Exemplo 2

A regra sugerirá o encaminhamento do parâmetro ct de MyMethod para a invocação MyMethodWithOverload, pois o método tem uma sobrecarga que usa um parâmetro 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 ct)
        {
            MyMethodWithOverload();
        }
    }
}

Correção:

Encaminhe o parâmetro ct:

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

Se você não estiver preocupado em encaminhar notificações de cancelamento para invocações mais baixas, poderá:

Passar explicitamente default:

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

Ou passar explicitamente CancellationToken.None:

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

Exemplos de não violação

O parâmetro CancellationToken no método pai não está na última posição:

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

O parâmetro CancellationToken no método padrão não está na última posição:

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

O parâmetro CancellationToken no método de sobrecarga não está na última posição:

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

O método pai define mais de um parâmetro CancellationToken:

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

O método com padrões define mais de um parâmetro CancellationToken:

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

A sobrecarga do método define mais de um parâmetro CancellationToken:

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

Suprimir um aviso

Para suprimir apenas uma violação, adicione diretivas de pré-processador ao arquivo de origem a fim de desabilitar e, em seguida, reabilitar a regra.

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

Para desabilitar a regra em um arquivo, uma pasta ou um projeto, defina a severidade como none no arquivo de configuração.

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

Para obter mais informações, confira Como suprimir avisos de análise de código.