C# CancellationToken (Cómo funciona para desarrolladores)

En el desarrollo de software moderno, gestionar tareas de larga duración de manera eficiente es fundamental, especialmente en aplicaciones donde la generación de archivos PDF grandes o complejos es común. Los desarrolladores de C# a menudo confían en IronPDF para la creación fluida de PDFs, pero manejar tareas potencialmente extensas de generación de PDFs requiere una forma de gestionar interrupciones o cancelaciones por parte del usuario.

Esto es donde entra en juego el CancellationToken en C#. Al integrarlo con IronPDF, puede asegurar que sus tareas de generación de PDF sean tanto receptivas como eficientes. En este artículo, exploraremos la importancia de CancellationToken, por qué se complementa bien con IronPDF y cómo puedes implementarlo para cancelar tareas de manera elegante.

¿Qué es un CancellationToken en C#?

El CancellationToken es una parte fundamental de la programación asíncrona en C#. Permite indicar que una tarea debe cancelarse, otorgando a los desarrolladores un mayor control sobre las operaciones de larga duración. Esto puede ser especialmente útil al realizar tareas como la producción de informes o facturas, donde podrías querer generar continuamente informes dinámicos a partir de datos hasta alcanzar tu objetivo, momento en el cual puedes usar tokens de cancelación de C# para indicar que la operación debe ser cancelada, lo que termina el programa de manera elegante.

¿Cómo funciona?

En esencia, se pasa un CancellationToken a una tarea o método, que revisa periódicamente si se ha solicitado la cancelación. Si es así, la tarea puede terminar elegantemente, liberando recursos y mejorando la capacidad de respuesta de su aplicación. Esto es particularmente útil en casos como la generación de PDF, donde la creación de documentos complejos puede llevar tiempo.

Al utilizar CancellationTokens, evitas los posibles inconvenientes de las tareas que se ejecutan innecesariamente largas, como el desperdicio de recursos del sistema y una mala experiencia de usuario.

Tokens de cancelación interna

En C#, un token de cancelación interno se refiere a un token de cancelación que se crea y gestiona dentro de una clase o método específico, en lugar de ser pasado desde una fuente externa. Esto permite un control más preciso sobre la cancelación de tareas dentro del ámbito de un solo componente, permitiéndole supervisar y responder a solicitudes de cancelación que se originan internamente.

Usar un token de cancelación interno es particularmente útil en escenarios donde quieres encapsular la lógica de cancelación sin exponerla a los consumidores de tu clase, manteniendo así una interfaz limpia. Este enfoque puede mejorar la modularidad del código y facilitar la gestión de flujos de trabajo asíncronos complejos mientras se sigue aprovechando la flexibilidad que proporciona el marco más amplio de CancellationToken.

¿Por qué usar un Token de Cancelación con IronPDF?

Al generar PDFs, especialmente en aplicaciones web o sistemas de informes complejos, podrías encontrarte con situaciones donde un usuario inicia una tarea, como crear un archivo PDF grande, pero luego navega fuera o ya no requiere el resultado. En estos casos, desea tener la opción de cancelar el proceso de generación de PDF para evitar una carga innecesaria en el servidor o la interfaz de usuario.

Aquí está la razón por la que usar CancellationToken con IronPDF es crucial:

Prevenir Cargas Innecesarias

Si un usuario ya no necesita el PDF que solicitó, no hay razón para que el proceso continúe. Al utilizar CancellationToken, puedes detener la tarea de generación de PDF, evitando una carga excesiva en tus servidores y mejorando el rendimiento general de la aplicación.

2. Mejorar la experiencia del usuario

En las aplicaciones de escritorio, la generación de PDF podría ocurrir en el hilo de la interfaz de usuario, lo que podría bloquear la interfaz si la tarea es de larga duración. Al incorporar CancellationToken, los usuarios pueden cancelar la tarea y mantener la aplicación receptiva.

3. Mejorar la escalabilidad

En aplicaciones web donde numerosos usuarios generan PDFs simultáneamente, la escalabilidad es clave. CancellationToken te permite cancelar de manera segura las tareas innecesarias, liberando recursos para manejar otras solicitudes de manera eficiente.

Cómo implementar CancellationToken con IronPDF

Ahora que entendemos por qué CancellationToken es útil, veamos cómo implementarlo con IronPDF.

Paso 1: Configuración de IronPDF en tu proyecto

Para comenzar a usar IronPDF, primero necesitarás instalarlo. Si ya está instalado, puede pasar a la siguiente sección, de lo contrario, los siguientes pasos cubren cómo instalar la biblioteca IronPDF.

A través de la Consola del Administrador de Paquetes NuGet

Para instalar IronPDF usando la Consola del Administrador de Paquetes NuGet, abra Visual Studio y navegue a la Consola del Administrador de Paquetes. Luego ejecute el siguiente comando:

Install-Package IronPdf

Install-Package IronPdf

'INSTANT VB TODO TASK: The following line uses invalid syntax:
'Install-Package IronPdf

A través del Administrador de Paquetes NuGet para Solución

Abriendo Visual Studio, vaya a "herramientas -> Administrador de paquetes NuGet -> Administrar paquetes NuGet para la solución" y busque IronPDF. Desde aquí, todo lo que necesitas hacer es seleccionar tu proyecto y hacer clic en "Instalar", y IronPDF se añadirá a tu proyecto.

Una vez que hayas instalado IronPDF, todo lo que necesitas agregar para comenzar a usar IronPDF es la declaración using correcta en la parte superior de tu código:

using IronPdf;

using IronPdf;

Imports IronPdf

Paso 2: Uso de tokens de cancelación en un método de generación de PDF asincrónico

Vamos a sumergirnos en la implementación real. En este ejemplo, generaremos un PDF simple a partir de HTML usando IronPDF, pero con un CancellationToken que permite cancelar la tarea si es necesario.

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();
        // Creating our one 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();
        // Creating our one 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()
		' Creating our one 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

Salida de Consola

Salida PDF

En este ejemplo, demostramos cómo usar un CancellationToken en un programa C# para cancelar una tarea de generación de PDF de larga duración con IronPDF. El código está estructurado en dos partes: el proceso de generación de PDF (clase PdfGenerator) y la lógica principal del programa (clase Program).

• Clase PdfGenerator: Esta clase contiene un método que simula la generación de un archivo PDF mientras soporta la cancelación a través de un CancellationToken.
• Creemos nuestra fuente de token de cancelación en el método main usando CancellationTokenSource(), y luego creamos nuestro objeto token pasando la propiedad Token del CancellationTokenSource a este.
• ChromePdfRenderer se utiliza desde la biblioteca de IronPDF para renderizar contenido HTML en un documento PDF.
• El método GeneratePdfWithCancellation es asincrónico (async) y devuelve una Tarea. Este método acepta un CancellationToken (token) para manejar la cancelación de la tarea a través de la solicitud de cancelación.
• El CancellationToken nos permite cancelar de manera segura las operaciones de larga duración. Sin embargo, la cancelación es cooperativa, lo que significa que la tarea en sí debe comprobar periódicamente el estado del token.
• En este código, simulamos una tarea prolongada con verificaciones de cancelación periódicas. El punto clave es que verificamos manualmente la cancelación (token.IsCancellationRequested) durante el proceso de generación de PDF, listos para ejecutar el método de cancelación si el token se le pasa.
• Si el usuario presiona una tecla para indicar la cancelación del programa, la tarea se detiene de manera adecuada y lanza una OperationCanceledException, impidiendo la finalización de la generación del PDF de forma apropiada y oportuna.
• El PDF resultante se guarda como "output.pdf" si no se produjo ninguna cancelación para evitar que el programa ejecute el proceso completo de la tarea.

Casos de uso del mundo real de IronPDF con CancellationToken

Hay varias situaciones prácticas en las que usar uno o varios tokens de cancelación con IronPDF puede mejorar el rendimiento y la experiencia del usuario de su aplicación. He aquí algunos ejemplos:

Aplicaciones web

En una aplicación web, los usuarios a menudo inician acciones como generar informes en formato PDF. Sin embargo, si el usuario se aleja de la página o cierra el navegador, el sistema puede detectar esto y usar CancellationToken para detener el proceso de generación de PDF.

HttpContext.Response.RegisterForDispose(CancellationTokenSource);

HttpContext.Response.RegisterForDispose(CancellationTokenSource);

HttpContext.Response.RegisterForDispose(CancellationTokenSource)

Esta sencilla implementación permite a los servidores web escalar de manera más efectiva al no dedicar recursos a tareas que ya no son necesarias.

2. Informes de larga duración

En aplicaciones de informes, los usuarios pueden solicitar que grandes conjuntos de datos sean exportados como PDF. Si el usuario cambia de opinión o realiza una consulta incorrecta, CancellationToken le permite cancelar la tarea a mitad del proceso, evitando el desperdicio de recursos.

Servicios en segundo plano

En servicios en segundo plano o microservicios, las tareas que requieren una cantidad significativa de tiempo, como generar lotes grandes de PDF, pueden gestionarse de manera más eficiente utilizando CancellationToken. Cuando el servicio está a punto de cerrarse o reducirse, las tareas en progreso pueden cancelarse de manera limpia, asegurando que no se pierdan ni corrompan datos.

Conclusión

Ahora que hemos llegado al final de la discusión de hoy sobre el uso de CancellationTokens con IronPDF, ¡podrás implementarlos en tus proyectos de PDF como un profesional! Usar C# CancellationToken con IronPDF te permite construir aplicaciones más eficientes y receptivas que manejan las tareas de generación de PDF con elegancia. Este enfoque permite un modelo de cancelación cooperativa, permitiendo a las tareas verificar solicitudes de cancelación en puntos seguros durante la ejecución, en lugar de ser terminadas abruptamente.

Ya sea que estés gestionando informes de larga duración, generación de PDF bajo demanda en aplicaciones web o servicios en segundo plano, incorporar un CancellationToken, o múltiples tokens simultáneamente, asegura que las tareas innecesarias puedan ser canceladas, previniendo el desperdicio de recursos y mejorando la experiencia del usuario.

Con solo unas pocas líneas de código, puedes mejorar la escalabilidad y la capacidad de respuesta de tu aplicación, al tiempo que le das a los usuarios más control sobre sus acciones. Si aún no ha explorado IronPDF, ahora es el momento perfecto para probar la prueba gratuita y descubrir cómo sus potentes capacidades de generación de PDF pueden transformar sus proyectos en C#.