C# ConfigureAwait (Wie es für Entwickler funktioniert)

Was ist asynchrone Programmierung?

Asynchrone Programmierung bezieht sich auf eine Methode des Schreibens von Code, die es ermöglicht, dass bestimmte Vorgänge unabhängig vom Hauptanwendungs-Thread ablaufen. Dies ist nützlich für langlaufende Aufgaben, die Wartezeiten erfordern, wie z. B. I/O-Operationen. Indem Sie diese Aufgaben ohne Blockierung des Haupt-Threads ausführen lassen, kann die Anwendung weiterlaufen, während diese Aufgaben Zeit benötigen, um abgeschlossen zu werden, was letztendlich die Leistung und Reaktionsfähigkeit der Anwendung verbessert.

Die Rolle von ConfigureAwait in asynchronem Code

ConfigureAwait ist eine Methode in der asynchronen Programmierung, die verwendet wird, um zu steuern, wie eine Fortsetzung ausgeführt wird. Die Fortsetzung ist der Code, der nach einem await-Ausdruck ausgeführt wird. Standardmäßig erfasst await den aktuellen Kontext und versucht, die Fortsetzung in diesen Kontext zurückzumarshallen, was ineffektiv sein kann. Mit ConfigureAwait können Sie festlegen, ob die Fortsetzung im erfassten Kontext ausgeführt werden soll (angegeben durch ConfigureAwait(true)) oder nicht (angegeben durch ConfigureAwait(false)).

Die Verwendung von ConfigureAwait(false) hilft, Deadlocks zu vermeiden, da man damit der Aufgabe mitteilt, den aktuellen Synchronisierungskontext nicht zu erfassen und nicht zu versuchen, im ursprünglichen Kontext fortzufahren. Dies ermöglicht dann, dass die Fortsetzung in einem Thread-Pool-Thread anstatt im ursprünglichen Kontext ausgeführt wird, wodurch verhindert wird, dass der Haupt-Thread blockiert wird.

ConfigureAwait(false) ist besonders nützlich in Bibliothekscode oder in Fällen, in denen die Wiederherstellung des ursprünglichen Kontexts nicht erforderlich ist, wodurch sichergestellt wird, dass der Code flexibel bleibt und keine Deadlocks auftreten.

Einrichten von IronPDF in Ihrem .NET-Projekt

Um mit der Verwendung von IronPDF in Ihren .NET-Projekten zu beginnen, installieren Sie das IronPDF NuGet-Paket. Dies können Sie tun, indem Sie zu Tools > NuGet-Paket-Manager > NuGet-Paket-Manager für die Lösung gehen und IronPDF suchen:

Oder alternativ den folgenden Befehl in der Paket-Manager-Konsole ausführen:

Install-Package IronPdf

Um IronPDF in Ihrem Code zu verwenden, stellen Sie sicher, dass Sie die Anweisung using IronPdf; am Anfang Ihrer Codedatei eingefügt haben. Eine ausführlichere Anleitung zur Einrichtung von IronPDF in Ihrer Umgebung finden Sie auf der Seite "Erste Schritte" .

Asynchrone PDF-Erzeugung mit IronPDF

Das asynchrone Generieren von PDF-Dateien kann besonders vorteilhaft in Situationen sein, in denen Sie große Mengen von PDF-Dateien generieren oder mehrere Vorgänge gleichzeitig ausführen müssen. Mit IronPDF können Sie PDF-bezogene Aufgaben asynchron ausführen, was folgendermaßen aussehen könnte:

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

In diesem Code haben wir in der Methode GeneratePdfAsync() asynchron ein PDF-Dokument erstellt. ChromePdfRenderer wird verwendet, um den Renderer zu erstellen, der wesentlich ist, um eine PDF-Datei aus dem HTML-Inhalt zu erzeugen. Die PdfDocument-Klasse erstellt ein PDF aus einem HTML-String, einer HTML-Datei, URL, einem Bild und mehr. Weitere Informationen zu den verschiedenen Methoden der PDF-Erzeugung mit IronPDF finden Sie im How-to-Bereich.

Arbeiten mit großen PDF-Dateien asynchron

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

Wann wird ConfigureAwait(true) vs. ConfigureAwait(false)

ConfigureAwait(false) wird am besten verwendet, wenn Sie in Bibliothekscode oder Hintergrundverarbeitung arbeiten, wo der Synchronisationskontext nicht erhalten werden muss. Typischerweise ist dies für serverseitigen Code, wo die Leistung entscheidend ist. Die Verwendung von ConfigureAwait(false) bedeutet, dass, wenn die await-Operation abgeschlossen ist, die Fortsetzung nicht unbedingt auf demselben Thread ausgeführt wird, der die asynchrone Operation gestartet hat.

Was die PDF-Verarbeitung betrifft, kann die Implementierung von ConfigureAwait(false) dabei helfen, die Leistung zu maximieren, wenn mehrere PDF-Verarbeitungsaufgaben ausgeführt werden, um Engpässe im Zusammenhang mit dem Kontextwechsel zu vermeiden. Es kann auch helfen, die Anwendung reibungslos laufen zu lassen, wenn große Mengen an PDF-Dateien verarbeitet werden, und einfach die Effizienz bei der Arbeit in Konsolenanwendungen oder Hintergrunddiensten aufrechterhalten, wo der Kontextwechsel unnötig sein könnte.

ConfigureAwait(true) wird am besten in der Benutzeroberfläche, in jedem Unit-Test für Ihren Code oder in ASP.NET-Anwendungen verwendet, wo die Fortsetzung im selben Kontext ablaufen muss, obwohl bei falscher Verwendung ein Deadlock entstehen kann. Zum Beispiel, wenn Sie die UI aktualisieren oder auf HttpContext zugreifen. ConfigureAwait(true) ist das Standardverhalten und könnte auch einfach als ConfigureAwait geschrieben werden.

Wenn es mit PDF-Verarbeitungsaufgaben verwendet wird, kann es besonders vorteilhaft in Situationen sein, wie wenn Ihr PDF-Verarbeitungscode eng mit der Benutzeroberfläche (bei der Verwendung von Benutzeroberflächenanwendungen, wie WPF, WinForms, usw.) integriert ist, wie dem Anzeigen von Fortschritten, und Sie den Synchronisationskontext erfassen müssen, um sicherzustellen, dass diese Aktualisierungen im UI-Thread stattfinden. Es ist auch vorteilhaft, wenn man mit threadsensitiven Operationen arbeitet, die aufgrund spezifischer Anforderungen an die Thread-Zugehörigkeit auf einem bestimmten Thread ausgeführt werden müssen.

Handhabung von Ausnahmen in asynchronen IronPDF-Operationen

Die Behandlung von Ausnahmen in der asynchronen Programmierung ist ein wichtiger Aspekt, den man im Auge behalten und sorgfältig abwägen muss; unbehandelte Ausnahmen können die Anwendung beenden. Try-Catch-Blöcke um asynchronen Code herum sind eine großartige Möglichkeit, um unerwartete Ausnahmen elegant zu behandeln.

Zum Beispiel:

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

Bei Verwendung von Fortsetzungsaufgaben mit ConfigureAwait(false) können Ausnahmen mithilfe von try-catch innerhalb der Fortsetzung oder mithilfe der Task.Exception- Eigenschaft behandelt werden, wenn Task.ContinueWith verwendet wird.

Ein Beispiel, wie Sie Code schreiben könnten, um dies zu tun, könnte wie folgt aussehen:

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

Schlüsselmerkmale und Vorteile von IronPDF

IronPDF ist eine leistungsfähige C# PDF-Bibliothek, die eine Vielzahl von Funktionen für alle Ihre PDF-bezogenen Aufgaben bietet. Mit voller Unterstützung für .NET 8, 7, 6, .NET Core, Standard und Framework, und der Fähigkeit, in einer Vielzahl von Umgebungen wie Windows, Linux, Mac, Docker, Azure und AWS zu laufen, können Sie das meiste aus IronPDF herausholen, egal welches Ihre bevorzugte Umgebung ist.

Mit IronPDF können Sie PDFs aus verschiedenen Datei- und Datentypen erzeugen, darunter HTML-Dateien, HTML-Strings, URLs, Bilder, DOCX und RTF, oft in nur wenigen Zeilen Code! Es kann die Formatierung Ihrer PDF-Dokumente handhaben, benutzerdefinierte Wasserzeichen anwenden, PDFs zusammenführen und aufteilen, PDF-Verschlüsselung und Sicherheit handhaben und mehr.

IronPDF's Unterstützung für asynchrone Programmierung

IronPDF bietet für viele seiner Operationen asynchrone Methoden an, sodass Entwickler die Async/Await-Muster nahtlos nutzen können. Diese Unterstützung gewährleistet, dass IronPDF in leistungskritische Anwendungen integriert werden kann, ohne die Reaktionsfähigkeit zu opfern, wodurch es zu einem unverzichtbaren PDF-Tool für Entwickler wird, die an PDF-bezogenen Aufgaben in einer asynchronen Umgebung arbeiten.

Lizenzierung

Wenn Sie IronPDF selbst ausprobieren und seine umfangreiche Palette an Funktionen erkunden möchten, können Sie dies dank seines kostenlosen Testzeitraums einfach tun. Dank seiner schnellen und einfachen Installation können Sie IronPDF in kürzester Zeit in Ihre PDF-Projekte integrieren. Möchten Sie es weiterhin verwenden und von seinen leistungsstarken Funktionen profitieren, um Ihr PDF-Projekt auf die nächste Stufe zu heben? Lizenzen gibt es schon ab $999, inklusive einer großzügigen 30-Tage-Geld-zurück-Garantie, einem ganzen Jahr Produktsupport und Updates sowie als unbefristete Lizenz (also keine lästigen wiederkehrenden Gebühren!).

Um ein PDF asynchron zu generieren, verwenden wir IronPDF, um den Code zum Rendern der HTML-Datei auszuführen und das Ergebnis zu speichern, während wir ConfigureAwait(false) verwenden, um sicherzustellen, dass die Fortsetzung nicht unnötig in den ursprünglichen Synchronisationskontext zurückwechselt.

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

In diesem Beispiel verwenden wir die asynchrone Methode, die wir erstellt haben, static async Task CreateInvoicePdfAsync(), um eine PDF-Rechnung aus der HTML-Datei zu generieren, die von der RenderHtmlFileAsPdfAsync-Methode bereitgestellt wird. Wir haben ConfigureAwait(false) verwendet, um zu verhindern, dass die Fortsetzung dieser Aufgabe im ursprünglichen Synchronisationskontext stattfindet, und damit die Leistung unserer Nicht-UI-Anwendung zu verbessern.

Wir haben auch erneut die Methode await Task.Run()) => ...) implementiert, um die Operationen asynchron auszuführen. Schließlich haben wir die neu generierte PDF-Datei mit der Methode pdf.SaveAs als "invoice.pdf" gespeichert. Der gesamte Code innerhalb der CreateInvoicePdfAsync()-Methode wurde in einen Try-Catch-Block eingebettet, um unerwartete Ausnahmen zu behandeln.

HTML-Datei

Ausgabe

Wie Sie sehen können, haben wir erfolgreich die HTML-Datei in ein PDF asynchron generiert und es hat eine klare, hochwertige PDF-Datei für uns erstellt.