Token de cancelamento em C# (Como funciona para desenvolvedores)

Como funciona?

Em essência, um CancellationToken é passado para uma tarefa ou método, que verifica periodicamente se o cancelamento foi solicitado. Nesse caso, a tarefa pode ser encerrada normalmente, liberando recursos e melhorando a capacidade de resposta do seu aplicativo. Isso é particularmente útil em casos como a geração de PDFs, onde documentos complexos podem levar tempo para serem criados.

Ao usar CancellationTokens , você evita as possíveis desvantagens de tarefas que demoram desnecessariamente, como o desperdício de recursos do sistema e uma experiência ruim para o usuário.

Tokens de cancelamento interno

Em C#, um token de cancelamento interno refere-se a um token de cancelamento que é criado e gerenciado dentro de uma classe ou método específico, em vez de ser passado de uma fonte externa. Isso permite um controle mais preciso sobre o cancelamento de tarefas dentro do escopo de um único componente, possibilitando o monitoramento e a resposta a solicitações de cancelamento originadas internamente.

Utilizar um token de cancelamento interno é particularmente útil em cenários onde se deseja encapsular a lógica de cancelamento sem expô-la aos consumidores da classe, mantendo assim uma interface limpa. Essa abordagem pode aprimorar a modularidade do código e facilitar o gerenciamento de fluxos de trabalho assíncronos complexos, ao mesmo tempo que aproveita a flexibilidade oferecida pela estrutura mais ampla do CancellationToken .

1. Evitar sobrecarga desnecessária

Se o usuário não precisar mais do PDF que solicitou, não há motivo para o processo continuar. Ao utilizar o CancellationToken , você pode interromper a tarefa de geração de PDF, evitando sobrecarga em seus servidores e melhorando o desempenho geral do aplicativo.

2. Melhorar a experiência do usuário

Em aplicações de desktop, a geração de PDFs pode ocorrer na thread da interface do usuário, o que pode travar a interface se a tarefa for demorada. Ao incorporar o CancellationToken , os usuários podem cancelar a tarefa e manter o aplicativo responsivo.

3. Melhorar a escalabilidade

Em aplicações web onde inúmeros usuários geram PDFs simultaneamente, a escalabilidade é fundamental. O CancellationToken permite cancelar tarefas desnecessárias com segurança, liberando recursos para lidar com outras solicitações de forma eficiente.

Passo 1: Configurando o IronPDF em seu projeto

Para começar a usar o IronPDF , primeiro você precisará instalá-lo. Se já estiver instalado, você pode pular para a próxima seção; Caso contrário, os passos seguintes explicam como instalar a biblioteca IronPDF .

Através do console do Gerenciador de Pacotes NuGet

Para instalar o IronPDF usando o Console do Gerenciador de Pacotes NuGet , abra o Visual Studio e navegue até o Console do Gerenciador de Pacotes. Em seguida, execute o seguinte comando:

Install-Package IronPdf

Por meio do Gerenciador de Pacotes NuGet para Soluções

Ao abrir o Visual Studio, acesse "Ferramentas -> Gerenciador de Pacotes NuGet -> Gerenciar Pacotes NuGet para a Solução" e procure por IronPDF. A partir daqui, basta selecionar o seu projeto e clicar em "Instalar", e o IronPDF será adicionado ao seu projeto.

Após instalar o IronPDF, tudo o que você precisa adicionar para começar a usá IronPDF é a instrução using correta no início do seu código:

using IronPdf;

using IronPdf;

Imports IronPdf

Etapa 2: Utilizando tokens de cancelamento em um método de geração de PDF assíncrono

Vamos analisar a implementação propriamente dita. Neste exemplo, vamos gerar um PDF simples a partir de HTML usando o IronPDF , mas com um CancellationToken que permite que a tarefa seja cancelada, se necessário.

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

public class PdfGenerator
{
    public async Task GeneratePdfWithCancellation(CancellationToken token)
    {
        var Renderer = new ChromePdfRenderer();
        try
        {
            // Check for cancellation before starting
            token.ThrowIfCancellationRequested();

            // Simulating a long task that can be checked for cancellation periodically
            for (int i = 0; i < 10; i++)
            {
                // Simulating a piece of work (this could be part of a larger HTML rendering)
                await Task.Delay(500); // Simulate chunk processing

                // Periodically check for cancellation in long-running operations
                if (token.IsCancellationRequested)
                {
                    Console.WriteLine("Cancellation requested. Throwing exception.");
                    token.ThrowIfCancellationRequested();  // This will trigger an OperationCanceledException
                }
            }

            // Simulate PDF creation after the long process
            var pdf = await Renderer.RenderHtmlAsPdfAsync("<h1>Hello, PDF!</h1>");

            // Save the PDF after ensuring no cancellation occurred
            pdf.SaveAs("output.pdf");
            Console.WriteLine("PDF generated successfully.");
        }
        catch (OperationCanceledException)
        {
            // Handle task cancellation
            Console.WriteLine("PDF generation was canceled.");
        }
        catch (Exception ex)
        {
            // Handle other exceptions
            Console.WriteLine($"An error occurred: {ex.Message}");
        }
    }
}

public class Program
{
    public static async Task Main(string[] args)
    {
        // Create a CancellationTokenSource
        var cancellationTokenSource = new CancellationTokenSource();

        // Create our cancellation token
        var token = cancellationTokenSource.Token;

        // Start the PDF generation task
        var pdfGenerator = new PdfGenerator();
        Task pdfTask = pdfGenerator.GeneratePdfWithCancellation(token);

        // Simulate a cancellation scenario
        Console.WriteLine("Press any key to cancel PDF generation...");
        Console.ReadKey();

        // Cancel the task by calling Cancel() on the CancellationTokenSource
        cancellationTokenSource.Cancel();

        try
        {
            // Await the task to handle any exceptions, such as cancellation
            await pdfTask;
        }
        catch (OperationCanceledException)
        {
            // Confirm the cancellation
            Console.WriteLine("The PDF generation was canceled.");
        }
        finally
        {
            cancellationTokenSource.Dispose();
        }

        Console.WriteLine("Program finished.");
    }
}

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

public class PdfGenerator
{
    public async Task GeneratePdfWithCancellation(CancellationToken token)
    {
        var Renderer = new ChromePdfRenderer();
        try
        {
            // Check for cancellation before starting
            token.ThrowIfCancellationRequested();

            // Simulating a long task that can be checked for cancellation periodically
            for (int i = 0; i < 10; i++)
            {
                // Simulating a piece of work (this could be part of a larger HTML rendering)
                await Task.Delay(500); // Simulate chunk processing

                // Periodically check for cancellation in long-running operations
                if (token.IsCancellationRequested)
                {
                    Console.WriteLine("Cancellation requested. Throwing exception.");
                    token.ThrowIfCancellationRequested();  // This will trigger an OperationCanceledException
                }
            }

            // Simulate PDF creation after the long process
            var pdf = await Renderer.RenderHtmlAsPdfAsync("<h1>Hello, PDF!</h1>");

            // Save the PDF after ensuring no cancellation occurred
            pdf.SaveAs("output.pdf");
            Console.WriteLine("PDF generated successfully.");
        }
        catch (OperationCanceledException)
        {
            // Handle task cancellation
            Console.WriteLine("PDF generation was canceled.");
        }
        catch (Exception ex)
        {
            // Handle other exceptions
            Console.WriteLine($"An error occurred: {ex.Message}");
        }
    }
}

public class Program
{
    public static async Task Main(string[] args)
    {
        // Create a CancellationTokenSource
        var cancellationTokenSource = new CancellationTokenSource();

        // Create our cancellation token
        var token = cancellationTokenSource.Token;

        // Start the PDF generation task
        var pdfGenerator = new PdfGenerator();
        Task pdfTask = pdfGenerator.GeneratePdfWithCancellation(token);

        // Simulate a cancellation scenario
        Console.WriteLine("Press any key to cancel PDF generation...");
        Console.ReadKey();

        // Cancel the task by calling Cancel() on the CancellationTokenSource
        cancellationTokenSource.Cancel();

        try
        {
            // Await the task to handle any exceptions, such as cancellation
            await pdfTask;
        }
        catch (OperationCanceledException)
        {
            // Confirm the cancellation
            Console.WriteLine("The PDF generation was canceled.");
        }
        finally
        {
            cancellationTokenSource.Dispose();
        }

        Console.WriteLine("Program finished.");
    }
}

Imports IronPdf
Imports System
Imports System.Threading
Imports System.Threading.Tasks

Public Class PdfGenerator
	Public Async Function GeneratePdfWithCancellation(ByVal token As CancellationToken) As Task
		Dim Renderer = New ChromePdfRenderer()
		Try
			' Check for cancellation before starting
			token.ThrowIfCancellationRequested()

			' Simulating a long task that can be checked for cancellation periodically
			For i As Integer = 0 To 9
				' Simulating a piece of work (this could be part of a larger HTML rendering)
				Await Task.Delay(500) ' Simulate chunk processing

				' Periodically check for cancellation in long-running operations
				If token.IsCancellationRequested Then
					Console.WriteLine("Cancellation requested. Throwing exception.")
					token.ThrowIfCancellationRequested() ' This will trigger an OperationCanceledException
				End If
			Next i

			' Simulate PDF creation after the long process
			Dim pdf = Await Renderer.RenderHtmlAsPdfAsync("<h1>Hello, PDF!</h1>")

			' Save the PDF after ensuring no cancellation occurred
			pdf.SaveAs("output.pdf")
			Console.WriteLine("PDF generated successfully.")
		Catch e1 As OperationCanceledException
			' Handle task cancellation
			Console.WriteLine("PDF generation was canceled.")
		Catch ex As Exception
			' Handle other exceptions
			Console.WriteLine($"An error occurred: {ex.Message}")
		End Try
	End Function
End Class

Public Class Program
	Public Shared Async Function Main(ByVal args() As String) As Task
		' Create a CancellationTokenSource
		Dim cancellationTokenSource As New CancellationTokenSource()

		' Create our cancellation token
		Dim token = cancellationTokenSource.Token

		' Start the PDF generation task
		Dim pdfGenerator As New PdfGenerator()
		Dim pdfTask As Task = pdfGenerator.GeneratePdfWithCancellation(token)

		' Simulate a cancellation scenario
		Console.WriteLine("Press any key to cancel PDF generation...")
		Console.ReadKey()

		' Cancel the task by calling Cancel() on the CancellationTokenSource
		cancellationTokenSource.Cancel()

		Try
			' Await the task to handle any exceptions, such as cancellation
			Await pdfTask
		Catch e1 As OperationCanceledException
			' Confirm the cancellation
			Console.WriteLine("The PDF generation was canceled.")
		Finally
			cancellationTokenSource.Dispose()
		End Try

		Console.WriteLine("Program finished.")
	End Function
End Class

Saída do console

Saída em PDF

Neste exemplo, demonstramos como usar um CancellationToken em um programa C# para cancelar uma tarefa de geração de PDF de longa duração com o IronPDF. O código está estruturado em duas partes: o processo de geração do PDF (PdfGenerator class) e a lógica principal do programa (Program class).

• Classe PdfGenerator: Esta classe contém um método que simula a geração de um arquivo PDF, permitindo o cancelamento por meio de um CancellationToken .
• Criamos nossa fonte de token de cancelamento no método principal usando CancellationTokenSource() , e então criamos nosso objeto de token passando a propriedade Token do CancellationTokenSource para ele.
• O ChromePdfRenderer da biblioteca IronPDF é usado para renderizar conteúdo HTML em um documento PDF.
• O método GeneratePdfWithCancellation é assíncrono (async) e retorna uma Task. Este método aceita um CancellationToken (token) para lidar com o cancelamento da tarefa por meio da solicitação de cancelamento.
• O CancellationToken permite cancelar com segurança operações de longa duração. No entanto, o cancelamento é cooperativo, o que significa que a própria tarefa deve verificar periodicamente o status do token.
• Neste código, simulamos uma tarefa longa com verificações periódicas de cancelamento. O ponto principal é que verificamos manualmente o cancelamento (token.IsCancellationRequested) durante o processo de geração do PDF, estando prontos para executar o método de cancelamento caso o token seja passado para ele.
• Se o usuário pressionar uma tecla para sinalizar o cancelamento do programa, a tarefa será interrompida normalmente e lançará uma exceção OperationCanceledException , impedindo a conclusão da geração do PDF de maneira adequada e oportuna.
• O PDF resultante é salvo como " output.pdf" caso não tenha ocorrido nenhum cancelamento que impedisse o programa de executar o processo completo da tarefa.

1. Aplicações Web

Em uma aplicação web, os usuários frequentemente iniciam ações como gerar relatórios em formato PDF. No entanto, se o usuário sair da página ou fechar o navegador, o sistema pode detectar isso e usar o CancellationToken para interromper o processo de geração do PDF.

HttpContext.Response.RegisterForDispose(CancellationTokenSource);

HttpContext.Response.RegisterForDispose(CancellationTokenSource);

HttpContext.Response.RegisterForDispose(CancellationTokenSource)

Essa implementação simples permite que os servidores web sejam dimensionados de forma mais eficaz, evitando alocar recursos para tarefas que não são mais necessárias.

2. Relatórios de longa duração

Em aplicações de geração de relatórios, os usuários podem solicitar que grandes conjuntos de dados sejam exportados como PDFs. Caso o usuário mude de ideia ou faça uma consulta incorreta, o CancellationToken permite cancelar a tarefa no meio do processo, evitando o desperdício de recursos.

3. Serviços em segundo plano

Em serviços em segundo plano ou microsserviços, tarefas que consomem muito tempo, como a geração de grandes lotes de PDFs, podem ser gerenciadas de forma mais eficiente usando o CancellationToken . Quando o serviço está prestes a ser desativado ou reduzido, as tarefas em andamento podem ser canceladas sem problemas, garantindo que nenhum dado seja perdido ou corrompido.