O problema não é apenas executar uma operação, mas saber quando parar
Nem todo processamento iniciado precisa chegar ao fim.

Quando desenvolvemos uma API, normalmente pensamos em como iniciar e concluir uma operação.
Por exemplo:
Receber uma requisição.
Consultar o banco de dados.
Processar as informações.
Devolver uma resposta.
Mas existe uma situação que nem sempre consideramos: e se aquela operação deixar de ser necessária antes de terminar?
Imagine que você faça um pedido em uma pizzaria. Enquanto o pedido está sendo preparado, percebe que informou o endereço errado e decide cancelar.
Não faria sentido continuar preparando uma pizza que ninguém pretende receber, certo?
Nas aplicações acontece algo parecido. Uma operação pode começar normalmente, mas, durante sua execução, deixar de ser necessária.
É justamente para lidar com situações assim que existe o CancellationToken.
O que é CancellationToken?
O CancellationToken é um mecanismo do .NET que permite sinalizar que uma operação deve ser cancelada.
Mas existe um detalhe importante: ele não interrompe qualquer código à força.
Em vez disso, funciona como um aviso compartilhado. As operações que recebem esse aviso podem verificar se devem continuar trabalhando ou interromper sua execução.
Voltando ao exemplo da pizzaria, imagine que você ligue para avisar que deseja cancelar o pedido.
O aviso precisa chegar até quem está preparando a pizza. Se ninguém receber essa informação, o preparo continuará normalmente.
Em uma aplicação, a lógica é semelhante.
Uma requisição começa no Controller, passa por um Service e pode chegar até o banco de dados. Se o processamento precisar ser cancelado, esse aviso pode acompanhar todo o caminho.
Isso significa que não basta saber que uma operação foi cancelada. As partes envolvidas também precisam estar preparadas para respeitar esse cancelamento.
Aplicando em uma API real
Imagine um endpoint responsável por consultar os pedidos de um cliente.
Uma implementação simplificada poderia ser:
[HttpGet("{customerId}/orders")]
public async Task<IActionResult> GetOrders(
int customerId,
CancellationToken cancellationToken)
{
var orders = await orderService.GetByCustomerAsync(
customerId,
cancellationToken
);
return Ok(orders);
}Perceba que não precisamos criar manualmente o token.
No ASP.NET Core, quando um CancellationToken é recebido como parâmetro de uma action, ele é associado ao HttpContext.RequestAborted.
Isso significa que o framework fornece um sinal de cancelamento relacionado à interrupção da requisição HTTP.
Por exemplo, se o cliente fechar a conexão ou abandonar a requisição, o ASP.NET Core poderá sinalizar que aquela operação foi cancelada.
Agora precisamos propagar esse token para o serviço.
public async Task<List<Order>> GetByCustomerAsync(
int customerId,
CancellationToken cancellationToken)
{
return await context.Orders
.Where(order => order.CustomerId == customerId)
.ToListAsync(cancellationToken);
}Aqui estamos utilizando Entity Framework Core.
O método ToListAsync() recebe o token e pode interromper a operação de consulta quando o cancelamento é solicitado e o provedor de banco de dados oferece suporte a essa operação.
Observe que o token percorreu toda a estrutura:
Controller → Service → Banco de dados.
Se esquecermos de passá-lo em algum ponto, podemos perder a capacidade de propagar o cancelamento para aquela operação.
É como avisar a primeira pessoa sobre o cancelamento do pedido, mas esquecer de avisar quem está preparando a pizza.
E quando trabalhamos com APIs externas?
O mesmo conceito vale para integrações.
Imagine que sua aplicação precise consultar um serviço externo para complementar as informações de um pedido.
public async Task<Product?> GetProductAsync(
int productId,
CancellationToken cancellationToken)
{
var response = await httpClient.GetAsync(
$"products/{productId}",
cancellationToken
);
response.EnsureSuccessStatusCode();
return await response.Content.ReadFromJsonAsync<Product>(
cancellationToken: cancellationToken
);
}Nesse exemplo, o token acompanha tanto a requisição HTTP quanto a leitura do conteúdo da resposta.
Assim, se o cancelamento for solicitado, essas operações terão a oportunidade de interromper o trabalho.
Isso é especialmente importante quando trabalhamos com várias integrações.
Imagine que uma única requisição dependa de três serviços externos diferentes. Se o usuário abandonar a operação, não faz sentido continuar consumindo recursos tentando obter informações que não serão mais utilizadas.
Propagar o token permite que essas operações também reconheçam o cancelamento.
Mas e se eu estiver executando uma operação própria?
Nem todo processamento utiliza métodos que recebem um CancellationToken.
Imagine uma rotina que percorre milhares de registros e realiza algum cálculo para cada um deles.
Nesse caso, podemos verificar manualmente se o processamento deve continuar:
public async Task ProcessOrdersAsync(
IEnumerable<Order> orders,
CancellationToken cancellationToken)
{
foreach (var order in orders)
{
cancellationToken.ThrowIfCancellationRequested();
await ProcessOrderAsync(order, cancellationToken);
}
}O método ThrowIfCancellationRequested() verifica se o cancelamento foi solicitado.
Caso tenha sido, ele lança uma OperationCanceledException, interrompendo o fluxo normal da execução.
Mas observe que também estamos passando o token para ProcessOrderAsync().
Isso é importante porque, se o processamento de um pedido for demorado, ele também precisa ter a oportunidade de reconhecer o cancelamento.
Pense novamente na busca por um documento.
Uma pessoa recebe a tarefa e pede ajuda a outra, que vai até o arquivo procurar o documento.
Se você desistir da busca, não adianta avisar apenas quem recebeu a tarefa inicialmente. Quem está executando o trabalho também precisa receber o aviso.
É essa a importância de propagar o token pelas diferentes etapas do processamento.
Um cuidado importante: cancelar não é tratar qualquer erro
Outro ponto importante é entender que cancelamentos e falhas são situações diferentes.
Imagine que você esteja esperando uma encomenda e receba uma destas notificações:
A entrega foi cancelada porque você desistiu do pedido.
A entrega não aconteceu porque houve um problema com o veículo.
Nos dois casos, a encomenda não chegou, mas os motivos são completamente diferentes.
Em uma aplicação acontece algo parecido.
Um erro bastante comum é capturar todas as exceções indiscriminadamente:
try
{
await ProcessOrdersAsync(orders, cancellationToken);
}
catch (Exception)
{
return false;
}O problema é que uma operação cancelada também pode resultar em uma exceção derivada de Exception.
Ao capturar tudo e transformar em false, podemos esconder a diferença entre uma falha real e um cancelamento solicitado.
Quando precisamos tratar cancelamentos explicitamente, podemos fazer:
try
{
await ProcessOrdersAsync(orders, cancellationToken);
}
catch (OperationCanceledException)
{
throw;
}
catch (Exception ex)
{
logger.LogError(ex, "Erro ao processar pedidos.");
throw;
}Dessa forma, preservamos o comportamento do cancelamento e tratamos as falhas reais separadamente.
Vale lembrar que nem sempre precisamos capturar OperationCanceledException. Se não houver necessidade de realizar algum tratamento específico, podemos simplesmente deixar a exceção ser propagada.
Em aplicações ASP.NET Core, também é importante evitar transformar um cancelamento causado pelo encerramento da requisição em uma resposta de erro genérica.
Quando devemos utilizar CancellationToken?
O CancellationToken é especialmente útil em situações como:
Consultas demoradas ao banco de dados.
Integrações com APIs externas.
Processamento de arquivos.
Operações assíncronas demoradas.
Rotinas que percorrem grandes volumes de dados.
Processamentos que dependem de outras operações canceláveis.
Mas isso não significa que precisamos adicionar verificações indiscriminadamente em qualquer método.
O importante é propagar o token pelas operações que podem se beneficiar do cancelamento.
Também precisamos entender uma limitação: solicitar o cancelamento não garante que tudo será interrompido imediatamente.
O mecanismo depende da cooperação das operações envolvidas e do suporte das bibliotecas utilizadas.
Se uma operação não verificar o token ou não oferecer suporte ao cancelamento, ela poderá continuar executando mesmo depois de o cancelamento ter sido solicitado.
Para finalizar
Uma aplicação bem estruturada não precisa apenas saber como executar uma tarefa. Ela também precisa reconhecer quando aquela tarefa deixou de fazer sentido.
O CancellationToken ajuda a evitar trabalho desnecessário, melhora o controle sobre operações assíncronas e permite construir fluxos mais conscientes.
No fim, a ideia é simples: se alguém desistiu de uma operação, não faz sentido continuar gastando recursos para concluí-la quando ela já não é mais necessária.
Não basta saber iniciar um processamento. Também precisamos saber quando ele não precisa mais continuar.
Projetos
Precisa desenvolver ou melhorar uma aplicação?
Conheça meus projetos ou entre em contato para conversar sobre sua necessidade.