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 8	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 c 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 c)
        {
            MyMethodWithDefault();
        }
    }
}

Correção:

Encaminhe o parâmetro c:

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

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

Ou passar explicitamente CancellationToken.None:

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

Exemplo 2

A regra sugerirá o encaminhamento do parâmetro c 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 c)
        {
            MyMethodWithOverload();
        }
    }
}

Correção:

Encaminhe o parâmetro c:

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

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

Ou passar explicitamente CancellationToken.None:

        public static void MyMethod(CancellationToken c)
        {
            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 c, 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 c)
        {
            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 c)
        {
            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 c1, CancellationToken c2)
        {
            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 c1 = default, CancellationToken c2 = default)
        {
        }

        public static void MyMethod(CancellationToken c)
        {
            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 c1, CancellationToken c2)
        {
        }

        public static void MyMethodWithOverload()
        {
        }

        public static void MyMethod(CancellationToken c)
        {
            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.