C# ConfigureAwait (Como funciona para desenvolvedores)

O que é programação assíncrona?

A programação assíncrona refere-se a um método de escrita de código que permite que certas operações sejam executadas independentemente da thread principal da aplicação. Isso é útil para tarefas de longa duração que exigem espera, como operações de entrada/saída. Ao permitir que essas tarefas sejam executadas sem bloquear a thread principal, o aplicativo pode continuar em execução enquanto essas tarefas levam tempo para serem concluídas, melhorando, em última análise, o desempenho e a capacidade de resposta do aplicativo.

O papel do ConfigureAwait no código assíncrono

ConfigureAwait é um método em programação assíncrona usado para controlar como uma continuação é executada. A continuação é o código que é executado após uma expressão await. Por padrão, await captura o contexto atual e tenta redirecionar a continuação de volta para esse contexto, o que pode ser ineficaz. ConfigureAwait permite especificar se a continuação deve ser executada no contexto capturado, indicado por ConfigureAwait(true), ou não, indicado por ConfigureAwait(false).

O uso de ConfigureAwait(false) ajuda a evitar impasses (deadlocks), pois, ao utilizá-lo, você está instruindo a tarefa a não capturar o contexto de sincronização atual e a não tentar retomar a execução no contexto original. Isso permite que a continuação seja executada em uma thread do pool de threads em vez do contexto original, evitando assim que a thread principal seja bloqueada.

ConfigureAwait(false) é especialmente útil em código de biblioteca ou em casos onde retomar o contexto original é desnecessário, garantindo assim que o código permaneça flexível e livre de impasses.

Configurando o IronPDF em seu projeto .NET

Para começar a usar o IronPDF em seus projetos .NET , instale o pacote NuGet do IronPDF . Você pode fazer isso navegando até Ferramentas > Gerenciador de Pacotes NuGet > Gerenciador de Pacotes NuGet para a Solução e pesquisando por IronPDF:

Ou, alternativamente, execute o seguinte comando no Console do Gerenciador de Pacotes:

Install-Package IronPdf

Para começar a usar o IronPDF no seu código, certifique-se de ter inserido a declaração using IronPdf; no início do arquivo de código. Para um guia mais detalhado sobre como configurar o IronPDF no seu ambiente, consulte a página de primeiros passos .

Geração assíncrona de PDFs usando o IronPDF

A geração assíncrona de arquivos PDF pode ser especialmente benéfica em situações onde você precisa gerar grandes quantidades de arquivos PDF ou deseja executar várias operações simultaneamente. Com o IronPDF, você pode executar tarefas relacionadas a PDFs de forma assíncrona, o que poderia ser algo como o seguinte código assí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!");
    }
}

Imports IronPdf
Imports System.Threading.Tasks

Friend Class Program
	Shared Async Function Main(ByVal args() As String) As Task
		Await GeneratePdfAsync()
	End Function

	Private Shared Async Function GeneratePdfAsync() As Task
		' Create a new instance of ChromePdfRenderer.
		Dim renderer As New ChromePdfRenderer()

		' Example HTML content to be converted into a PDF.
		Dim htmlContent As String = "<h1>Hello World!</h1>"

		' Asynchronously render the HTML content as a PDF document.
		Dim pdf As PdfDocument = Await renderer.RenderHtmlAsPdfAsync(htmlContent)

		' Asynchronously save the PDF document to a file.
		Await Task.Run(Function() pdf.SaveAs("outputAsync.pdf"))

		Console.WriteLine("Working!")
	End Function
End Class

Neste código, criamos um documento PDF de forma assíncrona no método GeneratePdfAsync(). O ChromePdfRenderer é usado para criar o renderizador, que é essencial para gerar um arquivo PDF a partir do conteúdo HTML. A classe PdfDocument é usada para criar um PDF a partir da string HTML fornecida; no entanto, você também pode usá-la para criar o PDF a partir de um arquivo HTML , URL , imagem e muito mais. Para mais informações sobre os diferentes métodos de geração de PDFs com o IronPDF, consulte a seção de instruções sobre como gerar PDFs.

Trabalhando com arquivos PDF grandes de forma assí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}");
        }
    }
}

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

Friend Class Program
	Shared Async Function Main(ByVal args() As String) As Task
		Await LongPdfTask()
	End Function

	Private Shared Async Function LongPdfTask() As Task
		Try
			' Initialize IronPDF's PdfDocument asynchronously.
			Dim pdf As PdfDocument = Await Task.Run(Function() PdfDocument.FromFile("Sample.pdf")).ConfigureAwait(False)

			' Extract text from PDF asynchronously with ConfigureAwait to prevent context capture.
			Dim text As String = Await Task.Run(Function() pdf.ExtractAllText()).ConfigureAwait(False)

			' Write the extracted text to a file asynchronously.
			Await Task.Run(Sub() File.WriteAllText("extractedText.txt", text)).ConfigureAwait(False)

			Console.WriteLine("Extraction complete!")
		Catch ex As Exception
			Console.WriteLine($"Error in LongPdfTask: {ex.Message}")
		End Try
	End Function
End Class

Quando usar ConfigureAwait(true) em vez de ConfigureAwait(false)

ConfigureAwait(false) é mais adequado quando você está trabalhando em código de biblioteca ou processamento em segundo plano, onde o contexto de sincronização não precisa ser preservado. Normalmente, isso se aplica a código do lado do servidor, onde o desempenho é crucial. Usar ConfigureAwait(false) significa que, quando a operação de espera for concluída, a continuação não será necessariamente executada na mesma thread que iniciou a operação assíncrona.

No que diz respeito ao processamento de PDFs, a implementação de ConfigureAwait(false) pode ajudar a maximizar o desempenho ao executar várias tarefas de processamento de PDFs, evitando gargalos relacionados à troca de contexto. Também pode ajudar a manter o aplicativo funcionando sem problemas ao processar grandes quantidades de arquivos PDF, além de contribuir para a eficiência em situações em que você está trabalhando com aplicativos de console ou serviços em segundo plano, onde a troca de contexto pode ser desnecessária.

ConfigureAwait(true) é mais indicado para uso em interfaces de usuário, testes unitários de código ou aplicações ASP.NET onde a continuação deve ser executada no mesmo contexto, embora, se usado incorretamente, possa levar a um deadlock. Por exemplo, se você estivesse atualizando a interface do usuário ou acessando o contexto HTTP. ConfigureAwait(true) é o comportamento padrão e também poderia ser escrito apenas como ConfigureAwait .

Quando usado em tarefas de processamento de PDF, pode ser especialmente benéfico em situações como, por exemplo, quando o código de processamento de PDF está fortemente integrado à interface do usuário (ao usar aplicativos de interface do usuário como WPF, WinForms, etc.), como na exibição do progresso, e você precisa capturar o contexto de sincronização para garantir que essas atualizações ocorram na thread da interface do usuário. Também é vantajoso ao trabalhar com operações que dependem de threads, as quais devem ser executadas em uma thread específica devido a requisitos de afinidade de threads.

Tratamento de exceções em operações assíncronas do IronPDF

O tratamento de exceções na programação assíncrona é um aspecto importante a ser considerado e requer atenção cuidadosa, pois exceções não tratadas podem encerrar a aplicação. Utilizar blocos try-catch em torno de código assíncrono é uma ótima maneira de lidar de forma elegante com quaisquer exceções inesperadas.

Por exemplo:

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

Public Async Function SafeGeneratePdfAsync() As Task
	Try
		Dim renderer As New ChromePdfRenderer()

		' Asynchronously render HTML as PDF and do not capture the context
		Dim pdf As PdfDocument = Await renderer.RenderHtmlAsPdfAsync("<h1>Error Handling</h1>").ConfigureAwait(False)

		' Asynchronously save PDF to file
		Await Task.Run(Function() pdf.SaveAs("output.pdf")).ConfigureAwait(False)
	Catch ex As Exception
		Console.WriteLine($"An error occurred: {ex.Message}")
	End Try
End Function

Ao usar tarefas de continuação com ConfigureAwait(false), as exceções podem ser tratadas usando try-catch dentro da continuação ou pela propriedade Task.Exception se estiver usando Task.ContinueWith .

Um exemplo de como você poderia escrever o código para fazer isso seria:

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);
    }
}

Friend Class Program
	Public Shared Async Function Main(ByVal args() As String) As Task
		Await ProcessPdfWithContinuationAsync()
	End Function

	Private Shared Function ProcessPdfWithContinuationAsync() As Task
		Return Task.Run(Function() PdfDocument.FromFile("Sample.pdf")).ContinueWith(Sub(pdfTask)
				If pdfTask.IsFaulted Then
					' Handle exceptions from loading the PDF
					Console.WriteLine($"Error loading PDF: {pdfTask.Exception?.GetBaseException().Message}")
					Return
				End If
				Dim pdf = pdfTask.Result
				' Extract text asynchronously with exception handling
				Task.Run(Function() pdf.ExtractAllText()).ContinueWith(Sub(extractTask)
						If extractTask.IsFaulted Then
							' Handle exceptions from extracting text
							Console.WriteLine($"Error extracting text: {extractTask.Exception?.GetBaseException().Message}")
							Return
						End If
						' Proceed if text extraction is successful
						Console.WriteLine("Extracted text:")
						Console.WriteLine(extractTask.Result)
				End Sub, TaskContinuationOptions.OnlyOnRanToCompletion)
		End Sub, TaskContinuationOptions.OnlyOnRanToCompletion)
	End Function
End Class

Principais características e vantagens do IronPDF

IronPDF é uma poderosa biblioteca C# para PDF que oferece um conjunto abrangente de recursos para todas as suas tarefas relacionadas a PDFs. Com suporte completo for .NET 8, 7, 6, .NET Core, Standard e Framework, e capaz de ser executado em diversos ambientes de aplicativos, como Windows, Linux, Mac, Docker, Azure e AWS, você poderá aproveitar ao máximo o IronPDF, independentemente do ambiente de sua preferência.

Com o IronPDF, você pode gerar PDFs a partir de diversos tipos de arquivos e dados, incluindo arquivos HTML , strings HTML , URLs , imagens , DOCX e RTF , muitas vezes com apenas algumas linhas de código! Ele pode lidar com a formatação de seus documentos PDF, aplicar marcas d'água personalizadas , mesclar e dividir PDFs , lidar com criptografia e segurança de PDFs e muito mais.

Suporte do IronPDF para programação assíncrona

O IronPDF oferece métodos assíncronos para muitas de suas operações, permitindo que os desenvolvedores aproveitem os padrões async/await de forma integrada. Esse suporte garante que o IronPDF possa ser integrado a aplicativos com desempenho crítico sem sacrificar a capacidade de resposta, tornando-o uma ferramenta de PDF indispensável para desenvolvedores que trabalham em tarefas relacionadas a PDF em um ambiente assíncrono.

Licenciamento

Se você quiser experimentar o IronPDF e explorar sua ampla gama de recursos, poderá fazê-lo facilmente graças ao período de teste gratuito . Com sua instalação rápida e fácil, você poderá ter o IronPDF funcionando em seus projetos de PDF em pouco tempo. Quer continuar usando e aproveitando seus recursos poderosos para aprimorar seus projetos de PDF? As licenças começam a partir de apenas $799 e incluem uma generosa garantia de reembolso de 30 dias, um ano inteiro de suporte e atualizações do produto, além de serem licenças perpétuas (sem taxas recorrentes incômodas!).

Para gerar um PDF de forma assíncrona, usaremos o IronPDF para executar o código de renderização do arquivo HTML e salvar o resultado, utilizando ConfigureAwait(false) para garantir que a continuação não retorne desnecessariamente ao contexto de sincronização 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;
        }
    }
}

Imports IronPdf
Imports System.Threading.Tasks
Imports System

Friend Class Program
	Public Shared Async Function Main(ByVal args() As String) As Task
		Await CreateInvoicePdfAsync()
	End Function

	Private Shared Async Function CreateInvoicePdfAsync() As Task(Of String)
		' Instance of ChromePdfRenderer to convert HTML to PDF
		Dim renderer As New ChromePdfRenderer()
		Try
			' Render HTML file as a PDF asynchronously without capturing the context.
			Dim pdf = Await renderer.RenderHtmlFileAsPdfAsync("example.html").ConfigureAwait(False)

			' Save the generated PDF asynchronously.
			Await Task.Run(Function() pdf.SaveAs("invoice.pdf")).ConfigureAwait(False)

			Return "invoice.pdf"
		Catch ex As Exception
			Console.WriteLine($"Error generating PDF: {ex.Message}")
			Return Nothing
		End Try
	End Function
End Class

Neste exemplo, estamos usando o método assíncrono que criamos, static async Task. CreateInvoicePdfAsync() , para gerar uma fatura em PDF a partir do arquivo HTML fornecido pelo método RenderHtmlFileAsPdfAsync . Usamos ConfigureAwait(false) para impedir a continuação desta tarefa no contexto de sincronização original, melhorando o desempenho do nosso aplicativo não relacionado à interface do usuário.

Implementamos também o método await Task.Run() => ...) novamente para executar as operações de forma assíncrona. Por fim, salvamos o arquivo PDF recém-gerado como "invoice.pdf" usando o método pdf.SaveAs . Todo o código dentro do método CreateInvoicePdfAsync() foi envolvido em um bloco try-catch para lidar com quaisquer exceções inesperadas.

Arquivo HTML

Saída

Como podem ver, geramos com sucesso o arquivo HTML em PDF de forma assíncrona, e isso criou um arquivo PDF nítido e de alta qualidade.