C# 取消令牌（開發者使用方法）

如何運作？

本質上，CancellationToken 會傳給任務或方法，而任務或方法會定期檢查是否有人要求取消。 如果是這樣的話，任務可以優雅地終止，從而釋放資源並提昇應用程式的反應能力。 這對於像產生 PDF 的情況特別有用，因為複雜的文件可能需要花時間來建立。

透過使用 CancellationTokens，您可以避免因任務執行時間過長而造成的潛在弊端，例如浪費系統資源和不佳的使用者體驗。

內部取消代幣

在 C# 中，內部取消標記指的是在特定類別或方法中建立和管理的取消標記，而非從外部來源傳入。 這允許在單一元件的範圍內對任務取消進行更精細的控制，使其能夠監控和回應源自內部的取消請求。

在您想要封裝取消邏輯的情況下，使用內部取消標記特別有用，因為您不需要將取消邏輯暴露給您類別的消費者，因此可以維持乾淨的介面。 此方法可增強程式碼模組化，並使複雜的異步工作流程更容易管理，同時仍可利用更廣泛的 CancellationToken 框架所提供的彈性。

1.防止不必要的負載。

如果使用者不再需要他們所要求的 PDF，就沒有理由繼續這個過程。 透過使用 CancellationToken，您可以停止 PDF 生成任務，防止伺服器負載過重，並改善整體應用程式效能。

2.增強使用者體驗。

在桌面應用程式中，PDF 的產生可能會發生在 UI 線程上，如果任務長時間執行，可能會鎖住使用者介面。 透過結合 CancellationToken，使用者可以取消任務，並保持應用程式的反應速度。

3. 增強可擴展性。

在眾多使用者同時產生 PDF 的網路應用程式中，可擴充性是關鍵。 CancellationToken 可讓您安全地取消不必要的任務，騰出資源來有效率地處理其他請求。

步驟 1：在專案中設定 IronPDF

若要開始使用 IronPDF，您首先需要安裝它。 如果已安裝，則可跳至下一節； 另外，以下步驟涵蓋了如何安裝 IronPdf 函式庫。

透過 NuGet 套件管理員控制台

要使用 NuGet Package Manager Console 安裝 IronPdf，請開啟 Visual Studio 並導航至 Package Manager Console。 然後執行以下指令：

Install-Package IronPdf

透過解決方案的 NuGet 套件管理員

打開 Visual Studio，進入"工具 -> NuGet 套件管理員 -> 管理解決方案的 NuGet 套件"，搜尋 IronPdf。 在這裡，您只需選擇專案並點選"安裝"，IronPDF 即會加入您的專案中。

安裝 IronPDF 之後，您只需在程式碼頂端加上正確的 using statement 即可開始使用 IronPDF：

using IronPdf;

using IronPdf;

步驟 2：在異步 PDF 產生方法中使用取消代幣

讓我們深入瞭解實際的執行方式。 在這個範例中，我們將使用 IronPDF 從 HTML 產生一個簡單的 PDF，但會加入一個 CancellationToken，允許在必要時取消任務。

using IronPdf;
using System;
using System.Threading;
using System.Threading.Tasks;

public class PdfGenerator
{
    public async Task GeneratePdfWithCancellation(CancellationToken token)
    {
        var Renderer = new ChromePdfRenderer();
        try
        {
            // Check for cancellation before starting
            token.ThrowIfCancellationRequested();

            // Simulating a long task that can be checked for cancellation periodically
            for (int i = 0; i < 10; i++)
            {
                // Simulating a piece of work (this could be part of a larger HTML rendering)
                await Task.Delay(500); // Simulate chunk processing

                // Periodically check for cancellation in long-running operations
                if (token.IsCancellationRequested)
                {
                    Console.WriteLine("Cancellation requested. Throwing exception.");
                    token.ThrowIfCancellationRequested();  // This will trigger an OperationCanceledException
                }
            }

            // Simulate PDF creation after the long process
            var pdf = await Renderer.RenderHtmlAsPdfAsync("<h1>Hello, PDF!</h1>");

            // Save the PDF after ensuring no cancellation occurred
            pdf.SaveAs("output.pdf");
            Console.WriteLine("PDF generated successfully.");
        }
        catch (OperationCanceledException)
        {
            // Handle task cancellation
            Console.WriteLine("PDF generation was canceled.");
        }
        catch (Exception ex)
        {
            // Handle other exceptions
            Console.WriteLine($"An error occurred: {ex.Message}");
        }
    }
}

public class Program
{
    public static async Task Main(string[] args)
    {
        // Create a CancellationTokenSource
        var cancellationTokenSource = new CancellationTokenSource();

        // Create our cancellation token
        var token = cancellationTokenSource.Token;

        // Start the PDF generation task
        var pdfGenerator = new PdfGenerator();
        Task pdfTask = pdfGenerator.GeneratePdfWithCancellation(token);

        // Simulate a cancellation scenario
        Console.WriteLine("Press any key to cancel PDF generation...");
        Console.ReadKey();

        // Cancel the task by calling Cancel() on the CancellationTokenSource
        cancellationTokenSource.Cancel();

        try
        {
            // Await the task to handle any exceptions, such as cancellation
            await pdfTask;
        }
        catch (OperationCanceledException)
        {
            // Confirm the cancellation
            Console.WriteLine("The PDF generation was canceled.");
        }
        finally
        {
            cancellationTokenSource.Dispose();
        }

        Console.WriteLine("Program finished.");
    }
}

using IronPdf;
using System;
using System.Threading;
using System.Threading.Tasks;

public class PdfGenerator
{
    public async Task GeneratePdfWithCancellation(CancellationToken token)
    {
        var Renderer = new ChromePdfRenderer();
        try
        {
            // Check for cancellation before starting
            token.ThrowIfCancellationRequested();

            // Simulating a long task that can be checked for cancellation periodically
            for (int i = 0; i < 10; i++)
            {
                // Simulating a piece of work (this could be part of a larger HTML rendering)
                await Task.Delay(500); // Simulate chunk processing

                // Periodically check for cancellation in long-running operations
                if (token.IsCancellationRequested)
                {
                    Console.WriteLine("Cancellation requested. Throwing exception.");
                    token.ThrowIfCancellationRequested();  // This will trigger an OperationCanceledException
                }
            }

            // Simulate PDF creation after the long process
            var pdf = await Renderer.RenderHtmlAsPdfAsync("<h1>Hello, PDF!</h1>");

            // Save the PDF after ensuring no cancellation occurred
            pdf.SaveAs("output.pdf");
            Console.WriteLine("PDF generated successfully.");
        }
        catch (OperationCanceledException)
        {
            // Handle task cancellation
            Console.WriteLine("PDF generation was canceled.");
        }
        catch (Exception ex)
        {
            // Handle other exceptions
            Console.WriteLine($"An error occurred: {ex.Message}");
        }
    }
}

public class Program
{
    public static async Task Main(string[] args)
    {
        // Create a CancellationTokenSource
        var cancellationTokenSource = new CancellationTokenSource();

        // Create our cancellation token
        var token = cancellationTokenSource.Token;

        // Start the PDF generation task
        var pdfGenerator = new PdfGenerator();
        Task pdfTask = pdfGenerator.GeneratePdfWithCancellation(token);

        // Simulate a cancellation scenario
        Console.WriteLine("Press any key to cancel PDF generation...");
        Console.ReadKey();

        // Cancel the task by calling Cancel() on the CancellationTokenSource
        cancellationTokenSource.Cancel();

        try
        {
            // Await the task to handle any exceptions, such as cancellation
            await pdfTask;
        }
        catch (OperationCanceledException)
        {
            // Confirm the cancellation
            Console.WriteLine("The PDF generation was canceled.");
        }
        finally
        {
            cancellationTokenSource.Dispose();
        }

        Console.WriteLine("Program finished.");
    }
}

控制台輸出

PDF輸出

在本範例中，我們將示範如何在 C# 程式中使用 CancellationToken 來取消 IronPDF 長時間執行的 PDF 生成任務。 程式碼分為兩部分：PDF 生成過程 (PdfGenerator class) 和主要程式邏輯 (Program class)。

• Class PdfGenerator： 此類包含一個模擬產生 PDF 檔案的方法，同時透過 CancellationToken 支援取消。
• 我們在 main 方法中使用 CancellationTokenSource() 建立我們的取消令牌來源，然後透過傳入 CancellationTokenSource 的Token 屬性來建立我們的令牌物件。
• ChromePdfRenderer用來自 IronPDF 函式庫，將 HTML 內容渲染成 PDF 文件。
• GeneratePdfWithCancellation 方法是異步的（async），並返回一個 Task。 此方法接受 CancellationToken（token），以透過取消請求處理任務取消。
• CancellationToken 可讓我們安全地取消長時間執行的作業。 然而，取消是合作性的，這意味著任務本身必須定期檢查標記狀態。
• 在此程式碼中，我們模擬一項長時間的任務，並定期進行取消檢查。 關鍵的一點是，我們在 PDF 生成過程中會手動檢查取消 (token.IsCancellationRequested)，如果將 token 傳給它，就準備好執行取消方法。
• 如果使用者按下按鍵以示取消程式，任務會優雅地停止，並發出 OperationCanceledException，阻止以適當且及時的方式完成 PDF 的產生。
• 如果沒有發生取消的情況，產生的 PDF 會儲存為 "output.pdf" 以防止程式執行完整的任務流程。

1.網路應用程式。

在 Web 應用程式中，使用者經常會啟動一些動作，例如產生 PDF 格式的報告。 但是，如果使用者導航離開頁面或關閉瀏覽器，系統可以偵測到這一情況，並使用 CancellationToken 停止 PDF 生成程序。

HttpContext.Response.RegisterForDispose(CancellationTokenSource);

HttpContext.Response.RegisterForDispose(CancellationTokenSource);

這個簡單的實作可以讓網頁伺服器更有效地擴充，不需要將資源用在不再需要的任務上。

2.長時間執行的報表。

在報告應用程式中，使用者可能會要求將大型資料集匯出成 PDF。 如果使用者改變主意或進行錯誤的查詢，CancellationToken 可讓您中途取消任務，避免資源浪費。

3.背景服務。

在背景服務或微服務中，耗費大量時間的任務，例如產生大量 PDF 批次，可以使用 CancellationToken 更有效率地管理。 當服務即將關閉或縮減規模時，可以乾淨地取消正在進行中的任務，確保資料不會遺失或損毀。