Cancelamento de tarefa

As classes System.Threading.Tasks.Task e System.Threading.Tasks.Task<TResult> dão suporte ao cancelamento com o uso de tokens de cancelamento. Para obter mais informações, consulte Cancelamento em Threads Gerenciados. Nas classes Task, o cancelamento envolve a cooperação entre o representante do usuário, que representa uma operação cancelável e o código que solicitou o cancelamento. Um cancelamento bem-sucedido envolve o código solicitante chamar o método CancellationTokenSource.Cancel e o delegado do usuário encerrar a operação de maneira oportuna. Você pode encerrar a operação usando uma destas opções:

• Retornando do delegado. Em muitos cenários, essa opção é suficiente. No entanto, uma instância de tarefa cancelada dessa forma faz a transição para o TaskStatus.RanToCompletion estado, não para o TaskStatus.Canceled estado.

• Ao gerar um OperationCanceledException e transmitir o token em que o cancelamento foi solicitado. A maneira preferida de executar é usar o ThrowIfCancellationRequested método. Uma tarefa cancelada dessa forma faz a transição para o estado Cancelado, que o código de chamada pode usar para verificar se a tarefa respondeu à solicitação de cancelamento.

O exemplo a seguir mostra o padrão básico de cancelamento de tarefa que gera a exceção:

Observação

O token é passado para o delegado do usuário e para a instância da tarefa.

using System;
using System.Threading;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var tokenSource2 = new CancellationTokenSource();
        CancellationToken ct = tokenSource2.Token;

        var task = Task.Run(() =>
        {
            // Were we already canceled?
            ct.ThrowIfCancellationRequested();

            bool moreToDo = true;
            while (moreToDo)
            {
                // Poll on this property if you have to do
                // other cleanup before throwing.
                if (ct.IsCancellationRequested)
                {
                    // Clean up here, then...
                    ct.ThrowIfCancellationRequested();
                }
            }
        }, tokenSource2.Token); // Pass same token to Task.Run.

        tokenSource2.Cancel();

        // Just continue on this thread, or await with try-catch:
        try
        {
            await task;
        }
        catch (OperationCanceledException e)
        {
            Console.WriteLine($"{nameof(OperationCanceledException)} thrown with message: {e.Message}");
        }
        finally
        {
            tokenSource2.Dispose();
        }

        Console.ReadKey();
    }
}

Imports System.Threading
Imports System.Threading.Tasks

Module Test
    Sub Main()
        Dim tokenSource2 As New CancellationTokenSource()
        Dim ct As CancellationToken = tokenSource2.Token

        Dim t2 = Task.Factory.StartNew(Sub()
                                           ' Were we already canceled?
                                           ct.ThrowIfCancellationRequested()

                                           Dim moreToDo As Boolean = True
                                           While moreToDo = True
                                               ' Poll on this property if you have to do
                                               ' other cleanup before throwing.
                                               If ct.IsCancellationRequested Then

                                                   ' Clean up here, then...
                                                   ct.ThrowIfCancellationRequested()
                                               End If

                                           End While
                                       End Sub _
        , tokenSource2.Token) ' Pass same token to StartNew.

        ' Cancel the task.
        tokenSource2.Cancel()

        ' Just continue on this thread, or Wait/WaitAll with try-catch:
        Try
            t2.Wait()

        Catch e As AggregateException

            For Each item In e.InnerExceptions
                Console.WriteLine(e.Message & " " & item.Message)
            Next
        Finally
            tokenSource2.Dispose()
        End Try

        Console.ReadKey()
    End Sub
End Module

Para obter um exemplo completo, confira Como cancelar uma tarefa e seus filhos.

Quando uma instância de tarefa observa uma OperationCanceledException gerada pelo código do usuário, ela compara o token da exceção com o token associado (aquele que foi passado para a API que criou a Tarefa). Se os tokens forem os mesmos e a propriedade IsCancellationRequested do token retornar true, a tarefa interpretará isso como o cancelamento da confirmação e fará a transição para o estado cancelado. Se você não usar um método Wait ou WaitAll para esperar pela tarefa, então a tarefa apenas definirá seu status como Canceled.

Se você estiver aguardando uma tarefa que faça a transição para o estado Cancelado, uma exceção System.Threading.Tasks.TaskCanceledException (envolvida em uma exceção AggregateException) será lançada. Essa exceção indica o cancelamento bem-sucedido em vez de uma situação com falha. Portanto, a propriedade Exception da tarefa retorna null.

Se a propriedade do IsCancellationRequested do token retornar false ou se o token da exceção não corresponder ao token da Tarefa, o OperationCanceledException será tratado como uma exceção normal, fazendo com que a Tarefa faça a transição para o estado de falha. A presença de outras exceções também fará com que a Tarefa transite para o estado de falha. Você pode obter o status da tarefa concluída na Status propriedade.

É possível que uma tarefa continue a processar alguns itens após a solicitação de cancelamento.

Consulte também

• Cancelamento em threads gerenciados
• Como: cancelar uma tarefa e seus filhos