C# ConfigureAwait（開発者向けの仕組み）

非同期プログラミングとは何でしょうか?

非同期プログラミングとは、メインアプリケーションのスレッドと独立して特定の操作を実行できるコードの記述方法を指します。 これは、I/O操作などの待機が必要な長時間実行されるタスクに役立ちます。 これらのタスクがメインスレッドをブロックせずに実行できるようにすることで、アプリケーションはこれらのタスクが完了するまで実行を続けることができ、最終的にはアプリケーションのパフォーマンスと応答性を向上させます。

非同期コードにおけるConfigureAwaitの役割

ConfigureAwaitは、非同期プログラミングで継続がどのように実行されるかを制御するために使用されるメソッドです。 継続とは、待機式の後に実行されるコードのことで、デフォルトではawaitは現在のコンテキストをキャプチャし、そのコンテキストに継続を再利用しようとしますが、これが効果的でないことがあります。ConfigureAwaitは、継続がキャプチャされたコンテキストで実行されるべきかどうかを指定できます。キャプチャされるとConfigureAwait(true)、されないとConfigureAwait(false)となります。

ConfigureAwait(false)を使用することはデッドロックを回避するのに役立ちます。これは、現在の同期コンテキストをキャプチャしない設定をするためで、元のコンテキストに復帰することを試みません。 これにより、継続が元のコンテキストではなくスレッドプールのスレッドで実行され、メインスレッドがブロックされるのを防ぎます。

ConfigureAwait(false)は特にライブラリコードや、元のコンテキストに戻る必要のないケースで有用であり、コードが柔軟でデッドロックが発生しないことを保証します。

.NETプロジェクトでのIronPDFの設定

.NETプロジェクトでIronPDFを使用開始するには、IronPDF NuGetパッケージをインストールして開始します。 これは、[ツール > NuGetパッケージマネージャ > ソリューションのNuGetパッケージマネージャ]に移動してIronPDFを検索することで行うことができます。

または、Package Manager Consoleで次のコマンドを実行することもできます。

Install-Package IronPdf

IronPDFをコードで使用し始めるには、コードファイルの先頭にusing IronPdf;を配置したことを確認してください。IronPDFを環境にセットアップするためのより包括的なガイドについては、getting startedページを参照してください。

IronPDFを使用した非同期PDFの生成

大容量のPDFファイルを生成する必要がある場合や複数の操作を同時に実行したい場合、PDFファイルを非同期で生成することは特に有益です。 IronPDFを使用することで、非同期でPDF関連のタスクを実行できます。これは次のような非同期コードになる場合があります:

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生成のhow-toセクションを確認してください。

大容量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処理タスクを実行する際のパフォーマンスを最大化するのに役立ちます。 また、コンソールアプリケーションやバックグラウンドサービスで作業をしている場合に、コンテキストの切り替えが不要になる状況でも、アプリケーションの効率を維持するのに役立ちます。

ConfigureAwait(true)はUI環境や単体テスト時に最適ですが、不適切だとデッドロックを招く可能性があります。 たとえば、UIの更新やhttpcontextへのアクセスを行う場合などで使用されます。 ConfigureAwait(true)はデフォルトの動作で、そのままConfigureAwaitと書くこともできます。

PDF処理タスクで使用する場合、UIとしっかり統合されたケース（WPF, WinFormsなどのUIアプリケーションを使用する際）で、同期コンテキストをキャプチャしてこれらの更新が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は、すべてのPDF関連タスクに対して豊富な機能セットを提供する強力なC# 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 の機能を自分で試して、その幅広い機能を探求したい場合は、無料トライアル期間のおかげで簡単に実行できます。 インストールが簡単で迅速なので、PDFプロジェクトでIronPDFをすぐに使い始めることができます。さらにその強力な機能を活用してPDFを向上させたい方は？ ライセンスは$liteLicenseから始まり、30日間の返金保証、1年間の製品サポートとアップデート、そして永久ライセンス（煩わしい定期料金なし！）が付いてきます。

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ファイルをpdf.SaveAsメソッドを使用して"invoice.pdf"として保存しました。 CreateInvoicePdfAsync()メソッド内のすべてのコードは、予期しない例外を処理するためにtry-catchブロックにラップされています。

HTMLファイル

出力

ご覧の通り、HTMLファイルを非同期でPDFに無事変換し、きれいで高品質なPDFファイルが生成されました。