Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C#

OperationCanceledException — sinalizar o cancelamento de uma operação

OperationCanceledException sinaliza que uma operação foi cancelada. Saiba como funciona com CancellationToken, o que faz ThrowIfCancellationRequested() e em que diferem pedir o cancelamento e dar resposta ao pedido.

Versão: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification

Sintaxe

token.ThrowIfCancellationRequested();
throw new OperationCanceledException(token);
catch (OperationCanceledException ex) when (ex.CancellationToken == token && token.IsCancellationRequested) { /* handle expected cancellation */ }

OperationCanceledException, no espaço de nomes System, sinaliza o cancelamento de uma operação. O cancelamento é cooperativo: CancellationTokenSource.Cancel() pede o cancelamento, mas não interrompe por si só o código em execução. A operação tem de detetar o pedido e parar o seu trabalho.

O ponto de verificação recomendado é token.ThrowIfCancellationRequested(): lança uma exceção apenas quando foi pedido o cancelamento e inclui o token. É equivalente a verificar token.IsCancellationRequested e executar throw new OperationCanceledException(token);. A propriedade CancellationToken da exceção permite identificar o token associado.

TaskCanceledException deriva de OperationCanceledException, pelo que capturar a classe base abrange ambos os tipos. Trate o cancelamento esperado num limite adequado da operação; o filtro do exemplo verifica tanto a identidade do token como o pedido de cancelamento, em vez de ignorar todas as exceções deste tipo.

Nas sobrecargas de Task.Run(..., token) que aceitam um delegado síncrono, se o delegado for executado e lançar esta exceção, a tarefa só passa para o estado Canceled se o token da exceção corresponder ao token fornecido e tiver sido pedido o cancelamento para esse token. Caso contrário, a tarefa passa para Faulted. Se o delegado terminar normalmente, o estado é RanToCompletion.

No caso de um delegado async que devolve uma tarefa, uma OperationCanceledException não capturada no delegado pode cancelar a tarefa interna, mesmo que o token da exceção seja diferente do fornecido a Task.Run ou que não tenha sido pedido o cancelamento. A tarefa proxy devolvida por Task.Run reflete a forma como a tarefa interna termina. O exemplo síncrono mostra o mecanismo sem condições de corrida temporais e não requer funcionalidades da linguagem em versão preview.

Exemplos

using System;
using System.Threading;

using var source = new CancellationTokenSource();
CancellationToken token = source.Token;
source.Cancel();

try
{
    token.ThrowIfCancellationRequested();
    Console.WriteLine("Completed");
}
catch (OperationCanceledException ex)
    when (ex.CancellationToken == token && token.IsCancellationRequested)
{
    Console.WriteLine("Canceled");
}

Resultado

Canceled

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes