C# ConfigureAwait (Cómo Funciona para Desarrolladores)

¿Qué es la programación asíncrona?

La programación asíncrona se refiere a un método de escritura de código que permite que ciertas operaciones se ejecuten independientemente del hilo principal de la aplicación. Esto es útil para tareas de larga duración que requieren espera, como operaciones de I/O. Al permitir que estas tareas se ejecuten sin bloquear el hilo principal, la aplicación puede continuar ejecutándose mientras estas tareas tardan en completarse, mejorando en última instancia el rendimiento y la capacidad de respuesta de la aplicación.

El papel de ConfigureAwait en el código asíncrono

ConfigureAwait es un método en la programación asíncrona utilizado para controlar cómo se ejecuta una continuación. La continuación es el código que se ejecuta después de una expresión await, por defecto await captura el contexto actual e intenta manejar la continuación de regreso a ese contexto, lo cual puede ser ineficaz. ConfigureAwait te permite especificar si la continuación debe ejecutarse en el contexto capturado, indicado como ConfigureAwait(true), o no, indicado por ConfigureAwait(false).

Usar ConfigureAwait(false) ayuda a evitar bloqueos, esto se debe a que cuando lo usas, le dices a la tarea que no capture el contexto de sincronización actual y que no intente reanudar en el contexto original. Esto permite que la continuación se ejecute en un hilo del grupo de hilos en lugar del contexto original, por lo tanto, evitando que el hilo principal se bloquee.

ConfigureAwait(false) es especialmente útil en el código de biblioteca o en casos donde reanudar el contexto original no es necesario, asegurando así que el código permanezca flexible y libre de bloqueos.

Cómo configurar IronPDF en su proyecto .NET

Para comenzar a usar IronPDF en tus proyectos .NET, empieza instalando el paquete NuGet de IronPDF. Puedes hacer esto navegando a Herramientas > Administrador de Paquetes NuGet > Administrador de Paquetes NuGet para la Solución y buscando IronPDF:

O, alternativamente, ejecutando el siguiente comando en la Consola del Administrador de Paquetes:

Install-Package IronPdf

Para comenzar a usar IronPDF en tu código, asegúrate de haber colocado la declaración using IronPdf; en la parte superior de tu archivo de código. Para una guía más detallada sobre cómo configurar IronPDF en tu entorno, consulta su página de comienzo.

Generación asíncrona de archivos PDF con IronPDF

Generar archivos PDF asíncronamente puede ser especialmente beneficioso en situaciones donde necesitas generar grandes cantidades de archivos PDF o quieres realizar múltiples operaciones simultáneamente. Con IronPDF, puedes realizar tareas relacionadas con PDF asíncronamente, lo que podría parecerse al siguiente código asíncrono:

using IronPdf;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        await GeneratePdfAsync();
    }

    static async Task GeneratePdfAsync()
    {
        // Create a new instance of ChromePdfRenderer.
        ChromePdfRenderer renderer = new ChromePdfRenderer();

        // Example HTML content to be converted into a PDF.
        string htmlContent = "<h1>Hello World!</h1>";

        // Asynchronously render the HTML content as a PDF document.
        PdfDocument pdf = await renderer.RenderHtmlAsPdfAsync(htmlContent);

        // Asynchronously save the PDF document to a file.
        await Task.Run(() => pdf.SaveAs("outputAsync.pdf"));

        Console.WriteLine("Working!");
    }
}

using IronPdf;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        await GeneratePdfAsync();
    }

    static async Task GeneratePdfAsync()
    {
        // Create a new instance of ChromePdfRenderer.
        ChromePdfRenderer renderer = new ChromePdfRenderer();

        // Example HTML content to be converted into a PDF.
        string htmlContent = "<h1>Hello World!</h1>";

        // Asynchronously render the HTML content as a PDF document.
        PdfDocument pdf = await renderer.RenderHtmlAsPdfAsync(htmlContent);

        // Asynchronously save the PDF document to a file.
        await Task.Run(() => pdf.SaveAs("outputAsync.pdf"));

        Console.WriteLine("Working!");
    }
}

En este código, hemos creado un documento PDF asíncronamente en el método GeneratePdfAsync(). ChromePdfRenderer se usa para crear el renderizador que es vital en la creación de un archivo PDF a partir del contenido HTML. La clase PdfDocument se utiliza para crear un PDF a partir de la cadena HTML proporcionada, sin embargo, también podrías usarla para crear el PDF a partir de un archivo HTML, URL, imagen, y más. Para más información sobre los diferentes métodos de generación de un PDF con IronPDF, consulta la sección de cómo sobre la generación de PDFs.

Trabajar con archivos PDF de gran tamaño de forma asíncrona

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

class Program
{
    static async Task Main(string[] args)
    {
        await LongPdfTask();
    }

    static async Task LongPdfTask()
    {
        try
        {
            // Initialize IronPDF's PdfDocument asynchronously.
            PdfDocument pdf = await Task.Run(() => PdfDocument.FromFile("Sample.pdf")).ConfigureAwait(false);

            // Extract text from PDF asynchronously with ConfigureAwait to prevent context capture.
            string text = await Task.Run(() => pdf.ExtractAllText()).ConfigureAwait(false);

            // Write the extracted text to a file asynchronously.
            await Task.Run(() => File.WriteAllText("extractedText.txt", text)).ConfigureAwait(false);

            Console.WriteLine("Extraction complete!");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error in LongPdfTask: {ex.Message}");
        }
    }
}

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

class Program
{
    static async Task Main(string[] args)
    {
        await LongPdfTask();
    }

    static async Task LongPdfTask()
    {
        try
        {
            // Initialize IronPDF's PdfDocument asynchronously.
            PdfDocument pdf = await Task.Run(() => PdfDocument.FromFile("Sample.pdf")).ConfigureAwait(false);

            // Extract text from PDF asynchronously with ConfigureAwait to prevent context capture.
            string text = await Task.Run(() => pdf.ExtractAllText()).ConfigureAwait(false);

            // Write the extracted text to a file asynchronously.
            await Task.Run(() => File.WriteAllText("extractedText.txt", text)).ConfigureAwait(false);

            Console.WriteLine("Extraction complete!");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error in LongPdfTask: {ex.Message}");
        }
    }
}

Cuándo utilizar ConfigureAwait(true) frente a ConfigureAwait(false)

ConfigureAwait(false) es mejor usarlo cuando estás trabajando en código de biblioteca o procesamiento en segundo plano, donde el contexto de sincronización no necesita conservarse. Típicamente, esto es para código del lado del servidor donde el rendimiento es crítico. Usar ConfigureAwait(false) significa que cuando la operación await se completa, la continuación no necesariamente se ejecuta en el mismo hilo que inició la operación asíncrona.

Cuando se trata de procesamiento de PDF, implementar ConfigureAwait(false) puede ayudar a maximizar el rendimiento al ejecutar múltiples tareas de procesamiento de PDF para ayudar a evitar cuellos de botella en relación con el cambio de contexto. También puede ayudar a mantener la aplicación funcionando sin problemas al procesar grandes cantidades de archivos PDF, y solo ayudar a mantener la eficiencia en situaciones en las que estás trabajando en aplicaciones de consola o servicios en segundo plano, donde el cambio de contexto podría ser innecesario.

ConfigureAwait(true) es mejor usado en la interfaz de usuario, cualquier prueba de unidad para tu código, o aplicaciones ASP.NET donde la continuación debe ejecutarse en el mismo contexto, aunque si se usa mal puede llevar a un bloqueo. Por ejemplo, si estuvieras actualizando la interfaz de usuario o accediendo a un contexto HTTP). ConfigureAwait(true) es el comportamiento predeterminado, y también podría escribirse simplemente como ConfigureAwait.

Cuando se usa con tareas de procesamiento de PDF, puede ser especialmente beneficioso en situaciones como si tu código de procesamiento de PDF está estrechamente integrado con la interfaz de usuario (cuando se usan aplicaciones de interfaz de usuario como WPF, WinForms, etc.), como mostrar el progreso, y necesitas capturar el contexto de sincronización para asegurar que estas actualizaciones sucedan en el hilo de la interfaz de usuario. También es beneficioso cuando se trabaja con operaciones sensibles al hilo, que deben ejecutarse en un hilo específico debido a los requisitos de afinidad del hilo.

Manejo de excepciones en operaciones asíncronas de IronPDF

Manejar excepciones en programación asíncrona es un aspecto importante a tener en cuenta y requiere una consideración cuidadosa y excepciones no manejadas pueden terminar la aplicación. Usar bloques try-catch alrededor del código asíncrono es una excelente manera de manejar con elegancia cualquier excepción inesperada.

Por ejemplo:

public async Task SafeGeneratePdfAsync()
{
    try
    {
        ChromePdfRenderer renderer = new ChromePdfRenderer();

        // Asynchronously render HTML as PDF and do not capture the context
        PdfDocument pdf = await renderer.RenderHtmlAsPdfAsync("<h1>Error Handling</h1>").ConfigureAwait(false);

        // Asynchronously save PDF to file
        await Task.Run(() => pdf.SaveAs("output.pdf")).ConfigureAwait(false);
    }
    catch (Exception ex)
    {
        Console.WriteLine($"An error occurred: {ex.Message}");
    }
}

public async Task SafeGeneratePdfAsync()
{
    try
    {
        ChromePdfRenderer renderer = new ChromePdfRenderer();

        // Asynchronously render HTML as PDF and do not capture the context
        PdfDocument pdf = await renderer.RenderHtmlAsPdfAsync("<h1>Error Handling</h1>").ConfigureAwait(false);

        // Asynchronously save PDF to file
        await Task.Run(() => pdf.SaveAs("output.pdf")).ConfigureAwait(false);
    }
    catch (Exception ex)
    {
        Console.WriteLine($"An error occurred: {ex.Message}");
    }
}

Cuando se usan tareas de continuación con ConfigureAwait(false), las excepciones pueden manejarse usando try-catch dentro de la continuación, o por la propiedad Task.Exception si se usa Task.ContinueWith.

Un ejemplo de cómo podrías escribir código para hacer esto podría parecer:

class Program
{
    public static async Task Main(string[] args)
    {
        await ProcessPdfWithContinuationAsync();
    }

    static Task ProcessPdfWithContinuationAsync()
    {
        return Task.Run(() => PdfDocument.FromFile("Sample.pdf"))
            .ContinueWith(pdfTask =>
            {
                if (pdfTask.IsFaulted)
                {
                    // Handle exceptions from loading the PDF
                    Console.WriteLine($"Error loading PDF: {pdfTask.Exception?.GetBaseException().Message}");
                    return;
                }
                var pdf = pdfTask.Result;
                // Extract text asynchronously with exception handling
                Task.Run(() => pdf.ExtractAllText())
                    .ContinueWith(extractTask =>
                    {
                        if (extractTask.IsFaulted)
                        {
                            // Handle exceptions from extracting text
                            Console.WriteLine($"Error extracting text: {extractTask.Exception?.GetBaseException().Message}");
                            return;
                        }
                        // Proceed if text extraction is successful
                        Console.WriteLine("Extracted text:");
                        Console.WriteLine(extractTask.Result);
                    }, TaskContinuationOptions.OnlyOnRanToCompletion);
            }, TaskContinuationOptions.OnlyOnRanToCompletion);
    }
}

class Program
{
    public static async Task Main(string[] args)
    {
        await ProcessPdfWithContinuationAsync();
    }

    static Task ProcessPdfWithContinuationAsync()
    {
        return Task.Run(() => PdfDocument.FromFile("Sample.pdf"))
            .ContinueWith(pdfTask =>
            {
                if (pdfTask.IsFaulted)
                {
                    // Handle exceptions from loading the PDF
                    Console.WriteLine($"Error loading PDF: {pdfTask.Exception?.GetBaseException().Message}");
                    return;
                }
                var pdf = pdfTask.Result;
                // Extract text asynchronously with exception handling
                Task.Run(() => pdf.ExtractAllText())
                    .ContinueWith(extractTask =>
                    {
                        if (extractTask.IsFaulted)
                        {
                            // Handle exceptions from extracting text
                            Console.WriteLine($"Error extracting text: {extractTask.Exception?.GetBaseException().Message}");
                            return;
                        }
                        // Proceed if text extraction is successful
                        Console.WriteLine("Extracted text:");
                        Console.WriteLine(extractTask.Result);
                    }, TaskContinuationOptions.OnlyOnRanToCompletion);
            }, TaskContinuationOptions.OnlyOnRanToCompletion);
    }
}

Características principales y ventajas de IronPDF

IronPDF es una poderosa biblioteca PDF de C# que ofrece un rico conjunto de características para todas tus tareas relacionadas con PDF. Con soporte completo para .NET 8, 7, 6, .NET Core, Standard, y Framework, y capaz de ejecutarse en una variedad de entornos de aplicación como Windows, Linux, Mac, Docker, Azure, y AWS, podrás sacar el máximo provecho de IronPDF sin importar cuál sea tu entorno preferido.

Con IronPDF, puedes generar PDFs a partir de varios tipos de archivo y datos; incluyendo archivos HTML, cadenas HTML, URLs, imágenes, DOCX, y RTF, a menudo en solo unas pocas líneas de código. Puede manejar el formato de tus documentos PDF, aplicar marcas de agua personalizadas, fusionar y dividir PDFs, manejar cifrado de PDF y seguridad, y más.

Soporte de IronPDF para la programación asíncrona

IronPDF proporciona métodos asíncronos para muchas de sus operaciones, permitiendo a los desarrolladores aprovechar los patrones async/await sin problemas. Este soporte garantiza que IronPDF pueda integrarse en aplicaciones críticas para el rendimiento sin sacrificar la capacidad de respuesta, convirtiéndolo en una herramienta de PDF invaluable para desarrolladores que trabajan en tareas relacionadas con PDF en un entorno asíncrono.

Licencias

Si quieres probar IronPDF por ti mismo y explorar su amplia gama de características, puedes hacerlo fácilmente gracias a su período de prueba gratuita. Con su instalación rápida y sencilla, podrás tener IronPDF en funcionamiento en tus proyectos PDF en poco tiempo. ¿Quieres seguir usándolo y aprovechando sus poderosas características para mejorar tu juego de PDF? Las licencias comienzan desde solo $799, y vienen con una generosa garantía de devolución de dinero de 30 días, un año entero de soporte de producto y actualizaciones, y vienen como una licencia perpetua (¡Así que no hay molestos cargos recurrentes!)

Para generar un PDF asíncronamente, usaremos IronPDF para ejecutar código para renderizar el archivo HTML y guardar el resultado, mientras usamos ConfigureAwait(false) para asegurarnos de que la continuación no cambie innecesariamente de regreso al contexto de sincronización original.

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

class Program
{
    public static async Task Main(string[] args)
    {
        await CreateInvoicePdfAsync();
    }

    static async Task<string> CreateInvoicePdfAsync()
    {
        // Instance of ChromePdfRenderer to convert HTML to PDF
        ChromePdfRenderer renderer = new ChromePdfRenderer();
        try
        {
            // Render HTML file as a PDF asynchronously without capturing the context.
            var pdf = await renderer.RenderHtmlFileAsPdfAsync("example.html").ConfigureAwait(false);

            // Save the generated PDF asynchronously.
            await Task.Run(() => pdf.SaveAs("invoice.pdf")).ConfigureAwait(false);

            return "invoice.pdf";
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error generating PDF: {ex.Message}");
            return null;
        }
    }
}

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

class Program
{
    public static async Task Main(string[] args)
    {
        await CreateInvoicePdfAsync();
    }

    static async Task<string> CreateInvoicePdfAsync()
    {
        // Instance of ChromePdfRenderer to convert HTML to PDF
        ChromePdfRenderer renderer = new ChromePdfRenderer();
        try
        {
            // Render HTML file as a PDF asynchronously without capturing the context.
            var pdf = await renderer.RenderHtmlFileAsPdfAsync("example.html").ConfigureAwait(false);

            // Save the generated PDF asynchronously.
            await Task.Run(() => pdf.SaveAs("invoice.pdf")).ConfigureAwait(false);

            return "invoice.pdf";
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error generating PDF: {ex.Message}");
            return null;
        }
    }
}

En este ejemplo, estamos usando el método asíncrono que creamos, static async TaskCreateInvoicePdfAsync(), para generar una factura PDF a partir del archivo HTML proporcionado por el método RenderHtmlFileAsPdfAsync. Hemos usado ConfigureAwait(false) para prevenir que la continuación de esta tarea se realice en el contexto de sincronización original, mejorando el rendimiento de nuestra aplicación no UI.

También hemos implementado el método await Task.Run()) => ...) nuevamente para ejecutar las operaciones asíncronamente. Finalmente, hemos guardado el archivo PDF recién generado como "invoice.pdf" usando el método pdf.SaveAs. Todo el código dentro del método CreateInvoicePdfAsync() ha sido envuelto dentro de un bloque try-catch para manejar cualquier excepción inesperada.

Archivo HTML

Resultado

Como puedes ver, generamos exitosamente el archivo HTML en un PDF asíncronamente, y creó un archivo PDF claro y de alta calidad para nosotros.