C# Token de Cancelación (Cómo Funciona para Desarrolladores)

¿Cómo funciona?

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

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

Fichas 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 fino sobre la cancelación de tareas dentro del alcance de un solo componente, permitiendo monitorear y responder a solicitudes de cancelación que se originan internamente.

Usar un token de cancelación interna es particularmente útil en escenarios donde deseas 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 asincrónicos complejos mientras sigue aprovechando la flexibilidad proporcionada por el marco CancellationToken más amplio.

1. Prevenir la carga innecesaria

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 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 de usuario 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 tareas innecesarias, liberando recursos para manejar otras solicitudes de manera eficiente.

Paso 1: Configurar IronPDF en su proyecto

Para comenzar a usar IronPDF, primero deberá 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.

Vía la Consola del Administrador de Paquetes NuGet

Para instalar IronPDF utilizando 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

Vía el Administrador de Paquetes NuGet para Solución

Abriendo Visual Studio, ve a "Herramientas -> Administrador de Paquetes NuGet -> Administrar Paquetes NuGet para Solución" y busca 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 haya instalado IronPDF, todo lo que necesita agregar para comenzar a usar IronPDF es la declaración correcta de using en la parte superior de su código:

using IronPdf;

using IronPdf;

Paso 2: Uso de tokens de cancelación en un método asíncrono de generación de PDF

Veamos la implementación real. En este ejemplo, generaremos un PDF simple desde 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();

        // 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.");
    }
}

Salida de Consola

Salida de PDF

En este ejemplo, demostramos cómo usar un CancellationToken en un programa de 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 cancelación a través de un CancellationToken.
• Creamos nuestra fuente de token de cancelación en el método main usando CancellationTokenSource(), y luego creamos nuestro objeto de token pasando la propiedad Token del CancellationTokenSource a él.
• ChromePdfRenderer se usa de la biblioteca 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 tareas mediante la solicitud de cancelación.
• El CancellationToken nos permite cancelar de manera segura operaciones de larga duración. Sin embargo, la cancelación es cooperativa, lo que significa que la propia tarea debe verificar periódicamente el estado del token.
• En este código, simulamos una tarea larga con verificaciones periódicas de cancelación. 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 cancelar si el token se pasa a él.
• Si el usuario presiona una tecla para señalar la cancelación del programa, la tarea se detiene de manera elegante y lanza una OperationCanceledException, impidiendo la finalización de la generación de PDF de manera apropiada y oportuna.
• El PDF resultante se guarda como "output.pdf" si no se produjo cancelación para evitar que el programa ejecute el proceso de tarea completo.

1. Aplicaciones web

En una aplicación web, los usuarios a menudo inician acciones como generar informes en formato PDF. Sin embargo, si el usuario navega fuera 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);

Esta implementación simple permite a los servidores web escalar más eficazmente 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 conjuntos de datos grandes para ser exportados como PDFs. Si el usuario cambia de opinión o realiza una consulta incorrecta, CancellationToken te permite cancelar la tarea a mitad de camino, previniendo el desperdicio de recursos.

3. Servicios de fondo

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