Utilizando CancellationToken em C# com as bibliotecas Iron Software

Por que Pedidos de Cancelamento Importam em Workloads da Iron Software

Ferramentas da Iron Software frequentemente executam operações assíncronas — por exemplo:

• Uma conversão de HTML para PDF IronPDF
• Uma extração de OCR de longa duração IronOCR
• Uma construção de documento IronWord ou IronXL dentro de Serviços de Segundo Plano
• Uma requisição web HttpClient grande antes da geração de PDF

Estas podem ser operações de longa duração que devem ser terminadas de maneira graciosa quando um usuário clica em um botão Cancelar, navega para fora ou quando o código chamador emite um CancellationRequest.

Usar tokens de cancelamento garante:

• Aplicativos responsivos
• Melhor gestão de recursos
• Liberação controlada de recursos não gerenciados
• Um modelo de cancelamento cooperativo limpo

Compreendendo o básico do CancellationToken em C

C# fornece a classe CancellationTokenSource, que cria um token CancellationToken. Um novo CTS por CancellationTokenSource() pode criar um token que é passado para métodos assíncronos.

var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;

var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;

Um token é passado usando um parâmetro de método:

public async Task ProcessPdfAsync(string html, CancellationToken token)

public async Task ProcessPdfAsync(string html, CancellationToken token)

Dentro do método, você verifica periodicamente:

token.ThrowIfCancellationRequested();

token.ThrowIfCancellationRequested();

ou inspeciona a propriedade IsCancellationRequested:

if (token.IsCancellationRequested)
{
    Console.WriteLine("Cancellation requested.");
    return;
}

if (token.IsCancellationRequested)
{
    Console.WriteLine("Cancellation requested.");
    return;
}

Isso fornece um padrão de cancelamento cooperativo onde o evento de operação cancelada ocorre apenas quando seu código verifica o token.

Usando CancellationToken com IronPDF

A renderização HTML do IronPDF é projetada para programação assíncrona, então você pode integrar o cancelamento naturalmente.

public async Task<PdfDocument> BuildPdfAsync(string html, CancellationToken token)
    {
        Console.WriteLine("\n[Generator] Starting PDF rendering process...");
        var renderer = new ChromePdfRenderer();

        token.ThrowIfCancellationRequested();

        Console.WriteLine("[Generator] Simulating a 2-second delay...");
        await Task.Delay(2000, token);

        token.ThrowIfCancellationRequested();

        Console.WriteLine("[Generator] Delay complete. Starting actual rendering...");

        // This is the working overload for your library version
        return await renderer.RenderHtmlAsPdfAsync(html);
    }

public async Task<PdfDocument> BuildPdfAsync(string html, CancellationToken token)
    {
        Console.WriteLine("\n[Generator] Starting PDF rendering process...");
        var renderer = new ChromePdfRenderer();

        token.ThrowIfCancellationRequested();

        Console.WriteLine("[Generator] Simulating a 2-second delay...");
        await Task.Delay(2000, token);

        token.ThrowIfCancellationRequested();

        Console.WriteLine("[Generator] Delay complete. Starting actual rendering...");

        // This is the working overload for your library version
        return await renderer.RenderHtmlAsPdfAsync(html);
    }

Usando CancellationToken com IronOCR

A operação de longa duração do IronOCR de escaneamento de imagens também se beneficia de um CancellationToken interno:

public class OcrProcessor
{
    private readonly IronOcr.IronTesseract ocr = new IronOcr.IronTesseract();

    public async Task<string> ExtractTextAsync(string path, CancellationToken token)
    {
        // Check for cancellation immediately upon entering the method.
        token.ThrowIfCancellationRequested();

        // Run the synchronous OCR method on a background thread.
        // This is the correct pattern for cancellable synchronous wrappers.
        return await Task.Run(() => ocr.Read(path).Text, token);
    }
}

public class OcrProcessor
{
    private readonly IronOcr.IronTesseract ocr = new IronOcr.IronTesseract();

    public async Task<string> ExtractTextAsync(string path, CancellationToken token)
    {
        // Check for cancellation immediately upon entering the method.
        token.ThrowIfCancellationRequested();

        // Run the synchronous OCR method on a background thread.
        // This is the correct pattern for cancellable synchronous wrappers.
        return await Task.Run(() => ocr.Read(path).Text, token);
    }
}

Verificando Periodicamente o Cancelamento em Operações Longas

Um padrão comum é fazer loop e verificar o cancelamento:

public async Task LongRunningOperation(CancellationToken token)
{
    for (int i = 0; i < 1000; i++)
    {
        token.ThrowIfCancellationRequested();
        await Task.Delay(10, token); // await Task.Delay helps cooperative cancellation
    }
}

public async Task LongRunningOperation(CancellationToken token)
{
    for (int i = 0; i < 1000; i++)
    {
        token.ThrowIfCancellationRequested();
        await Task.Delay(10, token); // await Task.Delay helps cooperative cancellation
    }
}

Isso garante que solicitações de cancelamento sejam tratadas de maneira apropriada e oportuna, e o sistema não desperdice ciclos.

Usando CancellationToken com HttpClient Antes de Renderizar IronPDF

Ao realizar uma solicitação na web para buscar HTML antes de gerar um PDF, sempre passe o token:

var client = new HttpClient();

public async Task<string> FetchHtmlAsync(string url, CancellationToken token)
{
    var response = await client.GetAsync(url, token);

    if (!response.IsSuccessStatusCode)
        throw new Exception("Error occurred while requesting content.");

    return await response.Content.ReadAsStringAsync(token);
}

var client = new HttpClient();

public async Task<string> FetchHtmlAsync(string url, CancellationToken token)
{
    var response = await client.GetAsync(url, token);

    if (!response.IsSuccessStatusCode)
        throw new Exception("Error occurred while requesting content.");

    return await response.Content.ReadAsStringAsync(token);
}

Isso garante que se o usuário navegar para outro lugar, o HttpClient será cancelado de maneira oportuna.

Cancelamento em Serviços em Segundo Plano do .NET Core

Os Serviços em Segundo Plano do .NET Core incluem um CancellationToken interno passado automaticamente ao método ExecuteAsync. Use-o ao executar ferramentas da Iron Software:

protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
    while (!stoppingToken.IsCancellationRequested)
    {
        await ProcessPdfAsync("<h1>Hello</h1>", stoppingToken);
        await Task.Delay(5000, stoppingToken);
    }
}

protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
    while (!stoppingToken.IsCancellationRequested)
    {
        await ProcessPdfAsync("<h1>Hello</h1>", stoppingToken);
        await Task.Delay(5000, stoppingToken);
    }
}

Este é o padrão geral para tarefas de longa duração no lado do servidor.

Melhores Práticas para Usar Tokens de Cancelamento com Iron Software

• Sempre passe CancellationToken para métodos assíncronos.

• Use ThrowIfCancellationRequested dentro dos loops.

• Prefira await Task.Delay em vez de loops apertados.

• Combine tokens com LinkedTokenSource.

• Sempre lide com OperationCanceledException.

• Use cancelamento para melhor gestão de recursos e aplicativos responsivos.

• Lembre-se que C# é uma linguagem de programação orientada a objetos, então projete seu método de cancelamento e lógica de cancelamento de maneira limpa.

Considerações Avançadas para Cancelamento de Tarefas

Para garantir que este seja um bom artigo para qualquer desenvolvedor .NET, aqui está uma breve seção suplementar que incorpora terminologia relevante restante enquanto reforça as melhores práticas.

O cancelamento de tarefas em C# não é automático; ele depende da lógica de cancelamento implementada dentro do seu método. A propriedade do token deve ser verificada, e o token retornado aos consumidores deve permitir que eles determinem se a operação foi cancelada ou concluída com sucesso. Se uma solicitação não puder ser concluída, o sistema ainda deve encerrar de forma apropriada e oportuna.

Se uma interface de usuário aciona um botão de cancelamento, o método de cancelamento em seu CancellationTokenSource sinalizará o cancelamento, e seu código deve periodicamente verificar via token.IsCancellationRequested. Quando eventos de operação cancelada ocorrem, você libera recursos e retorna o controle ao chamador.

Uma operação de longa duração como escaneamento IronOCR de documentos profundamente aninhados ou geração IronXL de planilhas massivas deve passar o CancellationToken através de cada camada. Quando o usuário navega para fora da página, a operação deve terminar de forma limpa.

Os produtos da Iron Software tornam isso mais fácil porque seguem o modelo de programação assíncrona do .NET nativamente. Ao escrever suas próprias bibliotecas, considere seguir as mesmas melhores práticas para que seus consumidores possam cancelar operações de maneira oportuna, sem consumir memória ou reter recursos não gerenciados.

Conclusão

Usar CancellationToken do C# com IronPDF, IronOCR, IronWord e IronXL fornece uma abordagem cooperativa de cancelamento que mantém as aplicações responsivas, eficientes e robustas. Aplicando as melhores práticas em programação assíncrona, passando tokens para tarefas assíncronas e verificando periodicamente o cancelamento, você pode construir aplicações .NET mais rápidas, seguras e mais fáceis de manter, que terminam de forma elegante quando necessário.