1. Introdução
Quando você executa uma operação assíncrona (ou longa), o usuário (ou outro código) pode de repente decidir: "Para! Já não precisa! Para!". Por exemplo, o usuário decidiu interromper o download de um arquivo gigante, fechou a janela do programa ou mudou de ideia sobre buscar informações em um grande banco de dados. Sem suporte a cancelamento seu programa pode continuar rodando e consumindo recursos à toa — não é a melhor demonstração de cuidado com o usuário e com a máquina.
Cenários típicos de cancelamento:
- Cancelamento de download de arquivo ou cancelamento de envio de dados.
- Sair rápido de um processamento pesado a pedido do usuário.
- Interrupção/pausa brusca de uma tarefa longa que já não é mais relevante.
Cancelamento — seu ingrediente secreto para apps responsivos, amigáveis e econômicos.
Como cancelar operações assíncronas no .NET?
No .NET, para cancelar tarefas longas usa-se a ideia do "token de cancelamento" (CancellationToken). É um objeto especial que é passado para todas as partes da tarefa. Se alguém solicitar cancelamento — o token avisa instantaneamente todas as partes interessadas do programa. Na prática é como uma bandeira vermelha: quem ver primeiro, para.
No .NET esse mecanismo é implementado com dois classes chave:
- CancellationTokenSource — cria e gerencia o token de cancelamento.
- CancellationToken — é passado para métodos assíncronos para que possam ser cancelados.
Importante: o token em si não interrompe a execução do código, ele só "sinaliza" — e sua aplicação decide quando e como reagir a esse sinal.
2. Criando um token de cancelamento e cancelando a tarefa
Vamos ver como isso funciona com um exemplo simples (vamos desenvolver nosso app de console didático).
Exemplo: operação assíncrona simples com cancelamento
using System;
using System.Threading;
using System.Threading.Tasks;
namespace DemoApp
{
class Program
{
static async Task Main()
{
// Criamos a fonte do token de cancelamento
CancellationTokenSource cts = new CancellationTokenSource();
// Iniciamos a tarefa assíncrona
Task longRunningTask = DoWorkAsync(cts.Token);
Console.WriteLine("Pressione qualquer tecla para cancelar a operação...");
Console.ReadKey();
// Solicitamos cancelamento
cts.Cancel();
try
{
await longRunningTask;
}
catch (OperationCanceledException)
{
Console.WriteLine("A operação foi cancelada!");
}
}
// Método assíncrono que suporta cancelamento
static async Task DoWorkAsync(CancellationToken cancellationToken)
{
for (int i = 0; i < 10; i++)
{
// Checamos o sinal de cancelamento
cancellationToken.ThrowIfCancellationRequested();
Console.WriteLine($"Executando passo {i + 1}/10...");
await Task.Delay(1000); // Delay de 1 segundo
}
Console.WriteLine("Operação concluída com sucesso!");
}
}
}
Como isso funciona?
- Nós criamos CancellationTokenSource (cts), de onde obtemos o token (cts.Token).
- Passamos esse token para nossa operação assíncrona.
- Dentro de DoWorkAsync() verificamos regularmente o token de cancelamento usando ThrowIfCancellationRequested(). Se o usuário pedir cancelamento — o método lança a exceção OperationCanceledException, e a tarefa é interrompida.
- Em Main() esperamos o pressionar de uma tecla e chamamos cts.Cancel() para "sinalizar" que a operação deve parar.
Se você não checar cancellationToken.IsCancellationRequested ou não chamar ThrowIfCancellationRequested(), sua tarefa vai continuar rodando como se nada tivesse acontecido — o token é só uma bandeira informativa.
3. CancellationToken: como funciona? E um pouco de mágica
O token de cancelamento é um objeto que é fácil de passar entre métodos e tarefas. Isso dá bastante flexibilidade:
- O mesmo token pode ser usado em várias operações assíncronas e síncronas.
- Você pode organizar um cancelamento "em grupo" para todas as tarefas se várias operações usarem o token vindo de um único CancellationTokenSource.
- O token é discreto: mesmo que você o ignore, o código continua funcionando como antes.
Gerenciando cancelamento: onde e como checar o token?
Checar se a "bandeira de cancelamento" foi levantada deve ser feito onde faz sentido logicamente: dentro de loops, em cada passo de um processamento longo, na transição entre etapas, etc.
// Em qualquer ponto de checagem
if (cancellationToken.IsCancellationRequested)
{
Console.WriteLine("Operação cancelada! Saindo...");
return;
}
// Ou assim (curto e lançando exceção)
cancellationToken.ThrowIfCancellationRequested();
Geralmente se usa ThrowIfCancellationRequested() — ele lança uma exceção específica que pode ser capturada no código chamador.
4. Métodos assíncronos da biblioteca padrão
Muitos tipos e métodos do .NET (especialmente os assíncronos) suportam CancellationToken "out of the box". Você deve usar isso para parar operações de forma "correta".
Aqui vai um exemplo de leitura assíncrona de arquivo:
using System.IO;
using System.Threading;
using System.Threading.Tasks;
class FileDemo
{
public static async Task ReadFileWithCancelAsync(string filePath, CancellationToken cancellationToken)
{
using FileStream stream = File.OpenRead(filePath);
byte[] buffer = new byte[4096];
int bytesRead;
while ((bytesRead = await stream.ReadAsync(buffer, 0, buffer.Length, cancellationToken)) > 0)
{
// Processamos os dados...
// Se o token de cancelamento tiver sido solicitado, ReadAsync vai lançar OperationCanceledException por si só
}
}
}
Leia mais sobre FileStream.ReadAsync e CancellationToken na documentação oficial.
5. Dicas úteis
Timeout também é cancelamento!
Você pode cancelar operações automaticamente após um certo tempo. Para isso você pode "programar" o token de cancelamento:
// Criar CancellationTokenSource com timeout (por exemplo, 5 segundos)
CancellationTokenSource cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
Após 5 segundos o token será automaticamente "levantado" e todas as operações usando ele vão parar na próxima checagem. É útil quando você não quer esperar para sempre.
O que acontece quando ocorre o cancelamento?
Quando você chama Cancel() na fonte do token, todos os métodos que usam esse token e checam seu estado ficam sabendo da mudança. Mas se o seu código não checar o token — o cancelamento não vai acontecer.
Erro comum: esquecer de passar o token para todos os chamados assíncronos e operações longas. Aí uma parte é cancelada e outra continua rodando como se nada tivesse acontecido.
Visualização: como o cancelamento flui
sequenceDiagram
participant Main as Thread principal
participant CTS as CancellationTokenSource
participant Task as Tarefa assíncrona
Main->>CTS: cria CTS, obtém token
Main->>Task: passa token para a tarefa assíncrona
Note over Task: Tarefa checa o token periodicamente
Main->>CTS: chama Cancel()
CTS-->>Task: token recebe status "cancelado"
Task-->>Main: lança OperationCanceledException
Main->>Main: captura a exceção e finaliza
Onde o cancelamento é aplicado?
- Downloads assíncronos e requisições a servidores: dá pra cancelar com internet ruim ou usuário impaciente.
- Grandes cálculos: pode-se interromper por timeout ou a pedido do usuário.
- Operações de rede, trabalho com arquivos, processamento de grandes coleções em background.
Com isso o contato com cancelamento de operações assíncronas termina — agora seu app pode ser não só rápido, mas também cuidadoso!
6. Conselhos e erros típicos
Não esqueça de passar o token de cancelamento para todos os métodos e chamadas que suportam cancellation. Se você deixar de propagá-lo em algum lugar — a operação pode "ficar presa" e não parar.
Verifique o token regularmente — especialmente em loops longos, processamento de arquivos ou uploads/downloads grandes. Use IsCancellationRequested ou ThrowIfCancellationRequested().
Não tente "forçar" a finalização de um thread ou tarefa de fora: o token de cancelamento é um pedido para parar, não um martelo para bater no thread.
Funções da biblioteca padrão, como ReadAsync, Delay, HttpClient.SendAsync e muitas outras já suportam cancelamento via token. Use isso!
Ao tratar cancelamento capture especificamente OperationCanceledException — é a exceção que indica um cancelamento correto por solicitação.
GO TO FULL VERSION