C# ConfigureAwait (Comment ça fonctionne pour les développeurs)

Qu'est-ce que la Programmation Asynchrone?

La programmation asynchrone se réfère à une méthode d'écriture de code qui permet à certaines opérations de s'exécuter indépendamment du thread principal de l'application. C'est utile pour des tâches de longue durée nécessitant de l'attente, telles que les opérations d'entrée/sortie. En permettant à ces tâches de s'exécuter sans bloquer le thread principal, l'application peut continuer à fonctionner pendant que ces tâches prennent le temps de se terminer, améliorant ainsi la performance et la réactivité de l'application.

Le Rôle de ConfigureAwait dans le Code Asynchrone

ConfigureAwait est une méthode en programmation asynchrone utilisée pour contrôler comment une continuation est exécutée. La continuation est le code qui s'exécute après une expression await, par défaut await capture le contexte actuel et essaie de transférer la continuation de nouveau à ce contexte, ce qui peut être inefficace. ConfigureAwait vous permet de spécifier si la continuation doit s'exécuter sur le contexte capturé, indiqué par ConfigureAwait(true), ou non, indiqué par ConfigureAwait(false).

En utilisant ConfigureAwait(false), vous aiderez à éviter les blocages, car cela indique à la tâche de ne pas capturer le contexte de synchronisation actuel et de ne pas tenter de reprendre le contexte d'origine. Cela permet alors à la continuation de s'exécuter sur un thread de pool de threads au lieu du contexte d'origine, prévenant ainsi le blocage du thread principal.

ConfigureAwait(false) est particulièrement utile dans le code de bibliothèque ou dans des cas où reprendre le contexte d'origine n'est pas nécessaire, assurant ainsi que le code reste flexible et exempt de blocages.

Configurer IronPDF dans Votre Projet .NET

Pour commencer à utiliser IronPDF dans vos projets .NET, commencez par installer le package NuGet IronPDF. Vous pouvez le faire en naviguant vers Outils > Gestionnaire de package NuGet > Gestionnaire de package NuGet pour la Solution et en recherchant IronPDF :

Ou, alternativement, exécuter la commande suivante dans la Console du gestionnaire de packages :

Install-Package IronPdf

Pour commencer à utiliser IronPDF dans votre code, assurez-vous d'avoir placé l'instruction using IronPdf; en haut de votre fichier de code. Pour un guide plus approfondi afin de configurer IronPDF dans votre environnement, consultez sa page de démarrage.

Générer des PDF de Manière Asynchrone avec IronPDF

Générer des fichiers PDF de façon asynchrone peut être particulièrement bénéfique dans des situations où vous avez besoin de générer de grandes quantités de fichiers PDF ou souhaitez effectuer plusieurs opérations simultanément. Avec IronPDF, vous pouvez effectuer des tâches liées aux PDF de manière asynchrone, ce qui peut ressembler au code asynchrone suivant :

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

Dans ce code, nous avons créé un document PDF de manière asynchrone dans la méthode GeneratePdfAsync(). ChromePdfRenderer est utilisé pour créer le moteur de rendu qui est essentiel pour créer un fichier PDF à partir du contenu HTML. The PdfDocument class is used to create a PDF from the provided HTML string, however, you could also use it to create the PDF from an HTML file, URL, image, and more. Pour en savoir plus sur les différentes méthodes de génération d'un PDF avec IronPDF, consultez la section comment faire sur la génération de PDFs.

Travailler avec de Grands Fichiers PDF de Manière Asynchrone

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

Quand Utiliser ConfigureAwait(true) vs. ConfigureAwait(false)

ConfigureAwait(false) est préférable lorsque vous travaillez dans le code des bibliothèques ou de traitement en arrière-plan, où le contexte de synchronisation ne doit pas être préservé. Habituellement, c'est pour le code côté serveur où la performance est essentielle. Utiliser ConfigureAwait(false) signifie que lorsque l'opération await est terminée, la continuation ne s'exécute pas nécessairement sur le même thread qui a démarré l'opération asynchrone.

En ce qui concerne le traitement des PDF, implémenter ConfigureAwait(false) peut aider à maximiser la performance lors de l'exécution de plusieurs tâches de traitement de PDF pour aider à éviter les goulets d'étranglement liés au changement de contexte. Cela peut également aider à maintenir le bon fonctionnement de l'application lors du traitement de grandes quantités de fichiers PDF, et simplement aider à maintenir l'efficacité dans les situations où vous travaillez dans des applications console ou des services d'arrière-plan, où le changement de contexte pourrait être inutile.

ConfigureAwait(true) est mieux utilisé dans l'interface utilisateur, tout test unitaire pour votre code, ou dans des applications ASP.NET où la continuation doit s'exécuter dans le même contexte, bien que mal utilisé, cela puisse conduire à un blocage. Par exemple, si vous mettiez à jour l'interface utilisateur ou accédiez à httpcontext). ConfigureAwait(true) est le comportement par défaut, et pourrait également être simplement écrit comme ConfigureAwait.

Lorsqu'il est utilisé avec des tâches de traitement de PDF, il peut être particulièrement bénéfique dans des situations telles que si votre code de traitement de PDF est étroitement intégré à l'interface utilisateur (lors de l'utilisation d'applications UI telles que WPF, WinForms, etc.), comme l'affichage de la progression, et que vous avez besoin de capturer le contexte de synchronisation pour assurer ces mises à jour sur le thread de l'interface utilisateur. Il est également bénéfique lorsque vous travaillez avec des opérations sensibles au thread, qui doivent être exécutées sur un thread spécifique en raison d'exigences d'affinité de thread.

Gérer les Exceptions dans les Opérations Asynchrones d'IronPDF

Gérer les exceptions en programmation asynchrone est un aspect important à garder à l'esprit et nécessite une considération attentive, car les exceptions non gérées peuvent entraîner l'arrêt de l'application. Utiliser des blocs try-catch autour du code asynchrone est un excellent moyen de gérer gracieusement toute exception inattendue.

Par exemple :

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

Lors de l'utilisation de tâches de continuation avec ConfigureAwait(false), les exceptions peuvent être gérées à l'aide de try-catch dans la continuation, ou par la propriété Task.Exception si vous utilisez Task.ContinueWith.

Un exemple de comment vous pourriez écrire du code pour faire cela pourrait ressembler à :

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

Principales Caractéristiques et Avantages d'IronPDF

IronPDF est une puissante bibliothèque PDF C# qui offre un riche ensemble de fonctionnalités pour toutes vos tâches liées aux PDF. Avec un support complet pour .NET 8, 7, 6, .NET Core, Standard, et Framework, et capable de fonctionner dans une gamme d'environnements applicatifs tels que Windows, Linux, Mac, Docker, Azure et AWS, vous serez en mesure d'obtenir le meilleur d'IronPDF quel que soit votre environnement préféré.

With IronPDF, you can generate PDFs from various file and data types; including HTML files, HTML string, URLs, images, DOCX, and RTF, often in just a few lines of code! It can handle the formatting of your PDF documents, apply custom watermarks, merge and split PDFs, handle PDF encryption and security, and more.

Support d'IronPDF pour la Programmation Asynchrone

IronPDF offre des méthodes asynchrones pour bon nombre de ses opérations, permettant aux développeurs de tirer parti des modèles async/await en toute transparence. Ce support assure qu'IronPDF peut être intégré dans des applications où la performance est cruciale sans sacrifier la réactivité, en faisant un outil PDF inestimable pour les développeurs travaillant sur des tâches liées aux PDF dans un environnement asynchrone.

Licences

Si vous souhaitez essayer IronPDF par vous-même et explorer sa large gamme de fonctionnalités, vous pouvez facilement le faire grâce à sa période d' essai gratuit. Avec une installation rapide et facile, vous serez en mesure d'avoir IronPDF opérationnel dans vos projets PDF en un rien de temps. Vous voulez continuer à l'utiliser et profiter de ses puissantes fonctionnalités pour améliorer votre expérience avec les PDFs? Les licences commencent à seulement $799, et sont accompagnées d'une généreuse garantie de remboursement de 30 jours, d'une année entière de support produit et de mises à jour, et viennent sous forme de licence perpétuelle (Donc, pas de frais récurrents ennuyeux!)

Pour générer un PDF de manière asynchrone, nous utiliserons IronPDF pour exécuter le code de rendu du fichier HTML, et enregistrer le résultat, tout en utilisant ConfigureAwait(false) pour garantir que la continuation ne revient pas inutilement au contexte de synchronisation d'origine.

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

Dans cet exemple, nous utilisons la méthode async que nous avons créée, static async Task CreateInvoicePdfAsync(), pour générer une facture PDF à partir du fichier HTML fourni par la méthode RenderHtmlFileAsPdfAsync. Nous avons utilisé ConfigureAwait(false) pour empêcher la continuation de cette tâche dans le contexte de synchronisation d'origine, améliorant ainsi la performance de notre application non-UI.

Nous avons également implémenté à nouveau la méthode await Task.Run()) => ...) pour exécuter les opérations de manière asynchrone. Enfin, nous avons enregistré le fichier PDF nouvellement généré sous le nom "invoice.pdf" en utilisant la méthode pdf.SaveAs. L'ensemble du code dans la méthode CreateInvoicePdfAsync() a été enveloppé dans un bloc try-catch pour gérer toute exception inattendue.

Fichier HTML

Sortie

Comme vous pouvez le voir, nous avons réussi à générer le fichier HTML en PDF de manière asynchrone, et cela a créé un fichier PDF clair et de haute qualité pour nous.