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. Eine 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ückzuführen, was ineffizient sein kann. ConfigureAwait erlaubt Ihnen zu spezifizieren, ob die Fortsetzung im erfassten Kontext ausgeführt werden soll, was durch ConfigureAwait(true) angezeigt wird, oder nicht, was durch ConfigureAwait(false) angezeigt wird.

Die Verwendung von ConfigureAwait(false) hilft, Deadlocks zu vermeiden, da Sie dem Task dadurch mitteilen, den aktuellen Synchronisationskontext nicht zu erfassen und nicht zu versuchen, auf den ursprünglichen Kontext zurückzukehren. 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 ein Fortsetzen im ursprünglichen Kontext nicht erforderlich ist, um sicherzustellen, dass der Code flexibel und deadlock-frei bleibt.

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 Code-Datei eingefügt haben. Für eine detailliertere Anleitung zur Einrichtung von IronPDF in Ihrer Umgebung schauen Sie sich die Erste Schritte-Seite an.

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

In diesem Code haben wir ein PDF-Dokument asynchron in der Methode GeneratePdfAsync() 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}");
        }
    }
}

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

Wenn Fortsetzungsaufgaben mit ConfigureAwait(false) verwendet werden, können Ausnahmen entweder innerhalb der Fortsetzung mit Try-Catch behandelt werden, oder durch die Task.Exception-Eigenschaft, 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);
    }
}

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 beginnen ab nur $799 und bieten eine großzügige 30-Tage-Geld-zurück-Garantie, ein ganzes Jahr Produktunterstützung und Updates und werden als dauerhafte Lizenz angeboten (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;
        }
    }
}

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.