C# ConfigureAwait（對開發者如何理解的工作）

什麼是非同步編程？

非同步編程指的是一種寫程式碼的方法，允許某些操作獨立於主應用程式執行緒執行。 這對於需要等待的長時間運行的任務（如I/O操作）特別有用。 允許這些任務在不阻塞主執行緒的情況下運行，應用程式可以在這些任務需要一定時間完成時繼續運行，從而最終提高應用程式的性能和回應速度。

在非同步程式碼中，ConfigureAwait的角色

ConfigureAwait是一種在非同步編程中用於控制如何執行連續操作的方法。 連續操作是await表達式之後運行的程式碼，預設情況下ConfigureAwait(false)。

使用ConfigureAwait(false)可以避免死鎖，因為當您使用它時，您是在告訴任務不要捕捉當前同步上下文，也不應該試圖在原始上下文中恢復。 這樣就可以讓連續操作在執行緒池執行緒上運行，而不是原始上下文上，從而防止主執行緒被阻塞。

ConfigureAwait(false)特別適用於程式庫程式碼或在不需要恢復到原上下文的情況下確保程式碼保持彈性且無死鎖。

在.NET專案中設置IronPDF

要在您的.NET專案中開始使用IronPDF，請首先安裝IronPDF NuGet包。 您可以通過導航到工具 > NuGet包管理員 > NuGet包管理員解決方案，然後搜尋IronPDF來安裝：

或者，您可以在包管理控制台中運行以下命令：

Install-Package IronPdf

在程式碼中開始使用IronPDF之前，請確保您在程式碼檔案的開頭放置了using IronPdf;語句。 有關在您的環境中設置IronPDF的更深入指南，請查看快速入門頁面。

使用IronPDF非同步生成PDF文件

在需要生成大量PDF文件或希望同時執行多個操作的情況下，非同步生成PDF文件尤其有用。 使用IronPDF，您可以進行非同步的PDF相關任務，這可能看起來像以下的async程式碼：

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

在此程式碼中，我們在GeneratePdfAsync()方法中非同步創建了PDF文件。 ChromePdfRenderer用於創建渲染器，這在從HTML內容創建PDF文件時非常重要。 PdfDocument類用於從提供的HTML字串創建PDF，然而，您也可以使用它從HTML檔案、URL、圖片等創建PDF。 關於使用IronPDF創建PDF的不同方法，請查看如何操作部分。

非同步處理大型PDF文件

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

何時使用ConfigureAwait(true)與ConfigureAwait(false)

ConfigureAwait(false)最適合於程式庫程式碼或背景處理，因為在這裡不需要保留同步上下文。 通常，這用於伺服器端程式碼，其中性能是關鍵。 使用ConfigureAwait(false)表示當await操作完成後，連續操作不一定在開始非同步操作的相同線程上運行。

在PDF處理方面，實施ConfigureAwait(false)有助於在運行多個PDF處理任務以避免與上下文切換相關的瓶頸。 它還可以幫助應用程式在處理大量PDF文件時保持平穩運行，並在您在主控台應用程式或背景服務中工作時增強效能，而不需要上下文切換。

ConfigureAwait(true)最適合用於UI、程式碼的單元測試或必須在同一上下文中運行連續操作的ASP.NET應用程式，儘管如果使用錯誤可能會導致死鎖。 例如，如果您正在更新UI或存取httpcontext）。 ConfigureAwait(true)是預設行為，也可以寫成簡單的ConfigureAwait。

當用於PDF處理任務時，在UI應用程式（如WPF，WinForms等）緊密集成中，這可能尤其有益，如顯示進度，並且您需要捕獲同步上下文以確保這些更新在UI執行緒上進行。 當處理需要特定線程的由於線程親和性要求的線程敏感操作時也非常有用。

在IronPDF非同步操作中處理例外情況

在非同步程式中處理例外情況是重要的方面，需要仔細考慮，未處理的例外情況可能會終止應用程式。 在非同步程式碼周圍使用try-catch塊是一種優雅的處理任何意外例外情況的好方法。

例如：

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

當使用帶有ConfigureAwait(false)的連續任務時，例外情況可以使用連續中的try-catch處理，或者使用Task.ContinueWith時通過Task.Exception屬性處理。

一個可以這樣書寫的程式碼示例可能是：

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

IronPDF的關鍵功能和優勢

IronPDF是一個強大的C# PDF程式庫，提供了一套豐富的功能以滿足您所有與PDF相關的任務。 完全支持.NET 8、7、6、.NET Core、Standard與Framework，能夠運行於眾多應用程式環境中，比如Windows、Linux、Mac、Docker、Azure和AWS，無論您的偏好的環境是什麼，您都能充分利用IronPDF。

使用IronPDF，您可以從各種文件和資料類型生成PDF；包括HTML文件、HTML字串、URL、圖片、DOCX和RTF，通常只需幾行程式碼！ 它可以處理您的PDF文件的格式設定、應用自訂水印、合併和拆分PDF、處理PDF加密及安全性，等等。

IronPDF對非同步編程的支持

IronPDF為許多操作提供了非同步方法，允許開發者無縫地運用async/await模式。 這一支持確保IronPDF能夠集成到性能要求高的應用程式中而不影響回應性，使其成為在非同步環境中工作於PDF相關任務的開發者的寶貴PDF工具。

授權

如果您想親自嘗試IronPDF並探索其廣泛的功能，您可以輕鬆做到，因為它提供了一個免費試用期。 藉由快速簡便的安裝，您將能在不久的未來將IronPDF配置並運行在您的PDF項目中。想繼續使用它並利用其強大的功能提升您的PDF效果嗎？ 授權僅需$799，並附帶慷慨的30天退款保證，一整年的產品支持與更新，同時也提供永久授權（所以不會有麻煩的定期費用！）

要非同步生成PDF，我們將使用IronPDF執行用於渲染HTML文件並保存結果的程式碼，同時使用ConfigureAwait(false)以確保連續不會不必要地切換回原始同步上下文。

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

在此範例中，我們使用創建的非同步方法，static async Task CreateInvoicePdfAsync()，從RenderHtmlFileAsPdfAsync方法提供的HTML文件中生成PDF發票。 我們使用了ConfigureAwait(false)來防止此任務的連續在原上下文中繼續，從而提高我們非UI應用程式的性能。

我們還實現了await Task.Run()) => ...)方法再次運行操作非同步。 最後，我們使用pdf.SaveAs方法將新生成的PDF文件保存為"invoice.pdf"。 整個在CreateInvoicePdfAsync()方法中的程式碼已經包裹在try-catch塊中以處理任何意外的例外情況。

HTML文件

輸出

正如您所見，我們成功地將HTML文件非同步生成為PDF，併為我們創建了一個清晰、高品質的PDF文件。