USANDO IRON SUITE

Uso de CancellationToken en C# con las bibliotecas de Iron Software

Publicado:

Los desarrolladores .NET modernos suelen trabajar con programación asíncrona al integrar bibliotecas como IronPDF, IronOCR, IronWord y IronXL. Estos productos ejecutan con frecuencia tareas de larga duración -como la renderización de PDF, el procesamiento de contenido OCR o la generación de grandes hojas de cálculo- y la forma correcta de mantener la capacidad de respuesta de las aplicaciones es utilizar la cancelación basada en C# CancellationToken.

Este artículo explica cómo utilizar tokens de cancelación, cómo un método acepta un token, cómo gestionar la cancelación de tareas y cómo integrar estos patrones con las bibliotecas de Iron Software de forma adecuada y oportuna. También cubrimos las mejores prácticas, la gestión de recursos y cómo utilizar varios CancellationTokens simultáneamente.

Por qué importan las solicitudes de cancelación en las cargas de trabajo de Iron Software

IronSoftware

Las herramientas de Iron Software suelen ejecutar operaciones asíncronas, por ejemplo:

  • Una conversión IronPDF HTML a PDF

  • Un IronOCR de larga duración Extracción deOCR

  • Un documento IronWord o IronXL creado dentro de Background Services

  • Una gran solicitud web HttpClient antes de la generación del PDF

Puede tratarse de operaciones de larga duración que deben finalizar cuando el usuario hace clic en un botón Cancelar, se aleja o cuando el código de llamada emite una CancellationRequest.

El uso de tokens de cancelación garantiza:

  • Aplicaciones con capacidad de respuesta

  • Mejor gestión de recursos

  • Liberación controlada de recursos no gestionados

  • Un modelo limpio de cancelación cooperativa

Comprensión de los conceptos básicos de CancellationToken en C

C# proporciona la clase CancellationTokenSource, que crea un token CancellationToken. Un CTS new CancellationTokenSource() puede crear un token que se pasa a métodos asíncronos.

var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;
var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Un token se transmite mediante un parámetro de método:

public async Task ProcessPdfAsync(string html, CancellationToken token)
public async Task ProcessPdfAsync(string html, CancellationToken token)
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Dentro del método, se comprueba periódicamente:

token.ThrowIfCancellationRequested();
token.ThrowIfCancellationRequested();
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

o inspeccionar la propiedad IsCancellationRequested:

if (token.IsCancellationRequested)
{
    Console.WriteLine("Cancellation requested.");
    return;
}
if (token.IsCancellationRequested)
{
    Console.WriteLine("Cancellation requested.");
    return;
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Esto proporciona un patrón de cancelación cooperativo en el que el evento de operación cancelada se produce sólo cuando su código comprueba el token.

Uso de CancellationToken con IronPDF

La representación HTML de IronPDF está diseñada para programación asíncrona, por lo que puede integrar la cancelación de forma natural.

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);
    }
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Ejemplo de salida de la consola

Salida de la consola

Aquí se muestra una tarea pública asíncrona que admite la cancelación en varios puntos. Cuando se produce una cancelación, el método lanza una excepción OperationCanceledException, que se maneja en un bloque catch.

Uso de CancellationToken con IronOCR

La operación de larga duración de IronOCR de escanear imágenes también se beneficia de un 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);
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Ejemplo de resultado

Ejemplo de uso de IronOCR con CancellationTokens

La generación de documentos IronWord y el montaje de hojas de cálculo IronXL funcionan de la misma manera. Dado que se trata de operaciones cancelables, el patrón de cancelación cooperativa evita el bloqueo de hilos de la interfaz de usuario o de servicios en segundo plano.

Comprobación periódica de cancelación en operaciones largas

Un patrón común es hacer bucles y comprobar la cancelación:

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
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Esto garantiza que las solicitudes de cancelación se gestionen de forma adecuada y oportuna, y que el sistema no desperdicie ciclos.

Uso de CancellationToken con HttpClient antes de la renderización de IronPDF

Al realizar una solicitud web para obtener HTML antes de generar un PDF, pase siempre el 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);
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Esto garantiza que si el usuario se aleja, el HttpClient se cancele en el momento oportuno.

Cancelación en .NET Core Servicios de fondo

los servicios de fondo de .NET Core incluyen un CancellationToken interno que se pasa automáticamente al método ExecuteAsync. Utilícela cuando ejecute herramientas de 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);
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Este es el patrón general para las tareas de larga duración del lado del servidor.

Mejores prácticas para el uso de tokens de cancelación con Iron Software

  • Pase siempre CancellationToken a los métodos asíncronos.

  • Utilice ThrowIfCancellationRequested dentro de bucles.

  • Preferir await Task.Delay en lugar de bucles cerrados.

  • Combine tokens con LinkedTokenSource.

  • Maneje siempre OperationCanceledException.

  • Utilice la cancelación para una mejor gestión de recursos y aplicaciones con capacidad de respuesta.

  • Recuerde que C# es un lenguaje de programación orientado a objetos, así que diseñe su método de cancelación y su lógica de cancelación de forma limpia.

Consideraciones avanzadas para la cancelación de tareas

Para asegurarnos de que este es un buen artículo para cualquier desarrollador .NET, aquí hay una breve sección complementaria que incorpora la terminología relevante restante a la vez que refuerza las mejores prácticas.

La cancelación de tareas en C# no es automática; depende de la lógica de cancelación implementada dentro de su método. La propiedad token debe comprobarse, y el token devuelto a los consumidores debe permitirles determinar si la operación se ha cancelado o completado con éxito. Si no se puede finalizar una solicitud, el sistema debe terminar de manera adecuada y oportuna.

Si una interfaz de usuario activa un botón de cancelación, el método cancel de su CancellationTokenSource señalará la cancelación, y su código deberá comprobar periódicamente a través de token.IsCancellationRequested. Cuando se producen eventos de operación cancelada, se liberan recursos y se devuelve el control a la persona que llama.

Una operación de larga duración como escaneo IronOCR de documentos profundamente anidados o generación IronXL de hojas de cálculo masivas debe pasar el CancellationToken a través de cada capa. Cuando el usuario sale de la página, la operación debe terminar limpiamente.

Los productos de Iron Software facilitan esta tarea porque siguen de forma nativa el modelo de programación asíncrona de .NET. Cuando escriba sus propias bibliotecas, considere la posibilidad de seguir las mismas prácticas recomendadas para que sus consumidores puedan cancelar las operaciones en el momento oportuno sin fugas de memoria ni retención de recursos no gestionados.

Conclusión

El uso de C# CancellationToken con IronPDF, IronOCR, IronWord, y IronXL proporciona un enfoque de cancelación cooperativo que mantiene las aplicaciones receptivas, eficientes y robustas. Aplicando las mejores prácticas de programación asíncrona, pasando tokens a las tareas asíncronas y comprobando periódicamente la cancelación, puede crear aplicaciones .NET más rápidas, seguras y fáciles de mantener que terminan con gracia cuando es necesario.