IRON SUITEの使用

C# CancellationTokenをIron Softwareライブラリで使用する

公開日:

現代の.NET開発者は、IronPDF、IronOCR、IronWord、IronXLのようなライブラリを統合する際に、非同期プログラミングで作業することがよくあります。 これらの製品は、PDFのレンダリング、OCRコンテンツの処理、または大規模なスプレッドシートの生成など、長時間実行されるタスクを頻繁に実行し、アプリケーションの応答性を維持する正しい方法は、C# CancellationTokenベースのキャンセルを使用することです。

この記事では、キャンセル・トークンの使用方法、メソッドがトークンを受け入れる方法、タスク・キャンセルの処理方法、これらのパターンを適切かつタイムリーにIron Softwareライブラリと統合する方法について説明します。 また、ベストプラクティス、リソース管理、複数のCancellationTokensを同時に使用する方法についても説明します。

なぜ Iron Software のワークロードでキャンセル要求が重要なのか

IronSoftware。

Iron Softwareのツールは、非同期処理を実行することがよくあります：

これらは、ユーザーがキャンセルボタンをクリックしたり、ナビゲートしたり、呼び出し元のコードがCancellationRequestを発行したときに、優雅に終了する必要がある長い実行操作である可能性があります。

キャンセルトークンを使用することで、確実になります：

  • レスポンシブアプリケーション

  • リソース管理の改善

  • 管理されていないリソースの制御されたリリース

  • クリーンな協調キャンセルモデル

C#のCancellationTokenの基礎を理解する

C# は、CancellationToken トークンを作成する CancellationTokenSource クラスを提供します。 CTS new CancellationTokenSource() は、非同期メソッドに渡されるトークンを作成できます。

var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;
var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

トークンは、メソッドのパラメータを使用して渡されます：

public async Task ProcessPdfAsync(string html, CancellationToken token)
public async Task ProcessPdfAsync(string html, CancellationToken token)
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

メソッド内では、定期的にチェックを行います：

token.ThrowIfCancellationRequested();
token.ThrowIfCancellationRequested();
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

または、IsCancellationRequested プロパティを調べてください：

if (token.IsCancellationRequested)
{
    Console.WriteLine("Cancellation requested.");
    return;
}
if (token.IsCancellationRequested)
{
    Console.WriteLine("Cancellation requested.");
    return;
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

これは、あなたのコードがトークンをチェックしたときにのみ操作がキャンセルされたイベントが発生する協調キャンセルパターンを提供します。

CancellationTokenをIronPDFで使用する

IronPdfのHTMLレンダリングは非同期プログラミングのために設計されているので、キャンセルを自然に統合することができます。

public async Task<PdfDocument> BuildPdfAsync(string html, CancellationToken token)
    {
        Console.WriteLine("\n[Generator] Starting PDF rendering process...");
        var renderer = new ChromePdfRenderer();

        token.ThrowIfCancellationRequested();

        Console.WriteLine("[Generator] Simulating a 2-second delay...");
        await Task.Delay(2000, token);

        token.ThrowIfCancellationRequested();

        Console.WriteLine("[Generator] Delay complete. Starting actual rendering...");

        // This is the working overload for your library version
        return await renderer.RenderHtmlAsPdfAsync(html);
    }
public async Task<PdfDocument> BuildPdfAsync(string html, CancellationToken token)
    {
        Console.WriteLine("\n[Generator] Starting PDF rendering process...");
        var renderer = new ChromePdfRenderer();

        token.ThrowIfCancellationRequested();

        Console.WriteLine("[Generator] Simulating a 2-second delay...");
        await Task.Delay(2000, token);

        token.ThrowIfCancellationRequested();

        Console.WriteLine("[Generator] Delay complete. Starting actual rendering...");

        // This is the working overload for your library version
        return await renderer.RenderHtmlAsPdfAsync(html);
    }
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

コンソール出力の例

コンソール出力。

これは、複数のポイントでキャンセルをサポートするパブリック非同期タスクを示しています。 キャンセルが発生すると、メソッドは OperationCanceledException をスローします。

IronOCRでCancellationTokenを使う

IronOCRの画像をスキャンするという長期間の運用は、内部のCancellationTokenからも恩恵を受けています：

public class OcrProcessor
{
    private readonly IronOcr.IronTesseract ocr = new IronOcr.IronTesseract();

    public async Task<string> ExtractTextAsync(string path, CancellationToken token)
    {
        // Check for cancellation immediately upon entering the method.
        token.ThrowIfCancellationRequested();

        // Run the synchronous OCR method on a background thread.
        // This is the correct pattern for cancellable synchronous wrappers.
        return await Task.Run(() => ocr.Read(path).Text, token);
    }
}
public class OcrProcessor
{
    private readonly IronOcr.IronTesseract ocr = new IronOcr.IronTesseract();

    public async Task<string> ExtractTextAsync(string path, CancellationToken token)
    {
        // Check for cancellation immediately upon entering the method.
        token.ThrowIfCancellationRequested();

        // Run the synchronous OCR method on a background thread.
        // This is the correct pattern for cancellable synchronous wrappers.
        return await Task.Run(() => ocr.Read(path).Text, token);
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

出力例

IronOCRとCancellationTokensの使用例。

IronWord ドキュメント生成と IronXL スプレッドシート・アセンブリーも同じように機能します。 これらはすべてキャンセル可能な操作であるため、協調キャンセルパターンはUIスレッドやBackground Servicesのブロックを回避します。

長い操作のキャンセルを定期的にチェックする

よくあるパターンは、ループとキャンセルチェックです：

public async Task LongRunningOperation(CancellationToken token)
{
    for (int i = 0; i < 1000; i++)
    {
        token.ThrowIfCancellationRequested();
        await Task.Delay(10, token); // await Task.Delay helps cooperative cancellation
    }
}
public async Task LongRunningOperation(CancellationToken token)
{
    for (int i = 0; i < 1000; i++)
    {
        token.ThrowIfCancellationRequested();
        await Task.Delay(10, token); // await Task.Delay helps cooperative cancellation
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

これにより、キャンセル要求が適切かつタイムリーに処理され、システムがサイクルを無駄にすることがなくなります。

IronPDFレンダリングの前にCancellationTokenをHttpClientで使う

PDF を生成する前に HTML を取得する Web リクエストを実行するときは、常にトークンを渡してください：

var client = new HttpClient();

public async Task<string> FetchHtmlAsync(string url, CancellationToken token)
{
    var response = await client.GetAsync(url, token);

    if (!response.IsSuccessStatusCode)
        throw new Exception("Error occurred while requesting content.");

    return await response.Content.ReadAsStringAsync(token);
}
var client = new HttpClient();

public async Task<string> FetchHtmlAsync(string url, CancellationToken token)
{
    var response = await client.GetAsync(url, token);

    if (!response.IsSuccessStatusCode)
        throw new Exception("Error occurred while requesting content.");

    return await response.Content.ReadAsStringAsync(token);
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

これによって、ユーザーがナビゲートして離れても、HttpClientがタイムリーにキャンセルされるようにします。

.NETコアのバックグラウンド サービスにおけるキャンセル

.NET Coreバックグラウンドサービスには、ExecuteAsyncメソッドに自動的に渡される内部CancellationTokenが含まれています。 Ironソフトウェアのツールを実行するときに使用してください：

protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
    while (!stoppingToken.IsCancellationRequested)
    {
        await ProcessPdfAsync("<h1>Hello</h1>", stoppingToken);
        await Task.Delay(5000, stoppingToken);
    }
}
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
    while (!stoppingToken.IsCancellationRequested)
    {
        await ProcessPdfAsync("<h1>Hello</h1>", stoppingToken);
        await Task.Delay(5000, stoppingToken);
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

これは、サーバーサイドの長時間実行タスクの一般的なパターンです。

Ironソフトウェアでキャンセルトークンを使用するためのベストプラクティス

  • 常に CancellationToken を非同期メソッドに渡してください。

  • ループ内で ThrowIfCancellationRequested を使用してください。

  • タイトなループではなく、Task.Delay待ちを優先してください。

  • LinkedTokenSource でトークンを結合します。

  • 常にOperationCanceledExceptionを処理すること。

  • より良いリソース管理と応答性の高いアプリケーションのためにキャンセルを使用してください。

  • C#はオブジェクト指向プログラミング言語であることを忘れずに、キャンセルメソッドとキャンセルロジックをきれいに設計してください。

タスク キャンセルのための高度な考慮事項

.NET開発者にとって良い記事となるように、ベストプラクティスを強化しながら、関連する用語の補足を簡単に説明します。

C#のタスクキャンセルは自動的ではありません； メソッド内部に実装されているキャンセルロジックに依存します。 トークンプロパティをチェックし、コンシューマに返されるトークンによって、操作がキャンセルされたのか、正常に完了したのかを判断できるようにする必要があります。 リクエストが終了できない場合でも、システムは適切かつタイムリーな方法で優雅に終了する必要があります。

ユーザー・インタフェースがキャンセル・ボタンをトリガーする場合、CancellationTokenSourceのcancelメソッドがキャンセルのシグナルとなり、コードはtoken.IsCancellationRequestedを介して定期的にチェックする必要があります。 操作がキャンセルされたイベントが発生すると、リソースを解放し、呼び出し元に制御を戻します。

IronOCRスキャン深くネストされたドキュメントやIronXL生成巨大なスプレッドシートのような長時間実行されるオペレーションは、すべてのレイヤを通してCancellationTokenを渡す必要があります。 ユーザーがページから移動するときは、操作がきれいに終了する必要があります。

Iron Softwareの製品は、.NETの非同期プログラミングモデルにネイティブに準拠しているため、翻訳が容易です。 独自のライブラリを書く際には、同じベストプラクティスに従うことを検討してください。そうすることで、コンシューマは、メモリをリークしたり、管理されていないリソースを保持したりすることなく、タイムリーに操作をキャンセルすることができます。

結論

IronPDF、IronOCR、IronWord、およびIronXLでC# CancellationTokenを使用すると、アプリケーションの応答性、効率性、および堅牢性を維持する協調的なキャンセル・アプローチを提供します。非同期プログラミングのベストプラクティスを適用し、トークンを非同期タスクに渡し、定期的にキャンセルをチェックすることで、必要なときに優雅に終了する、より高速で安全で保守性の高い.NETアプリケーションを構築することができます。