C# Cancellationtoken（對開發者如何理解其工作）

它是如何運作的？

本質上，CancellationToken 被傳遞給任務或方法，該方法會定期檢查是否已請求取消。 如果是，任務可以優雅地終止，釋放資源並提高應用程序的響應能力。 這在像 PDF 生成這樣的情況中特別有用，因為複雜的文檔可能需要時間來創建。

通過使用 CancellationTokens，您可以避免任務不必要長時間運行的潛在缺點，例如浪費系統資源和糟糕的用戶體驗。

內部取消代幣

在 C# 中，內部取消代幣是指在特定類或方法內創建和管理的取消代幣，而不是從外部來源傳遞進來的。 這允許在單個組件的範圍內更精細地控制任務取消，並能夠監控和響應由內部源發出的取消請求。

使用內部取消代幣特別有用於需要在不暴露給類的使用者的情況下封裝取消邏輯的場景，從而保持界面的整潔。 這種方法可以提高代碼模塊化，同時仍然利用更廣泛的 CancellationToken 框架提供的靈活性，更容易管理複雜的非同步工作流程。

1. 防止不必要的負荷

如果用戶不再需要他們請求的 PDF，則沒有理由讓該過程繼續下去。 通過利用 CancellationToken，您可以中止 PDF 生成任務，防止超載伺服器並提高整體應用程序性能。

2. 提高用戶體驗

在桌面應用程序中，PDF 生成可能在 UI 執行緒上進行，如果任務運行時間過長，這可能會鎖定用戶界面。 通過結合 CancellationToken，用戶可以取消任務並保持應用程序的響應性。

3. 改善擴展性

在眾多用戶同時生成PDF的 Web 應用中，可擴展性是關鍵。 取消代幣讓您得以安全地取消不必要的任務，釋放資源來有效地處理其他請求。

步驟 1：在您的專案中設置 IronPDF

要開始使用 IronPDF，您首先需要安裝它。 如果它已安裝，您可以跳到下一部分； 否則，以下步驟將說明如何安裝 IronPDF 程式庫。

通過 NuGet 套件管理器控制台

要使用 NuGet 套件管理器控制台 安裝 IronPDF，打開 Visual Studio 並導航到套件管理器控制台。 然後運行以下命令：

Install-Package IronPdf

通過 NuGet 套件管理器為解決方案

在 Visual Studio 中，前往"工具 -> NuGet 套件管理器 -> 管理解決方案的 NuGet 套件"，然後搜索 IronPDF。 從這裡，您只需選擇您的專案並單擊"安裝"，IronPDF 將被添加到您的專案中。

一旦您安裝了 IronPDF，您只需在代碼頂部添加正確的 using 語句即可開始使用 IronPDF：

using IronPdf;

using IronPdf;

步驟 2：在非同步 PDF 生成方法中使用取消代幣

讓我們深入實際的實施。 在此範例中，我們將使用 IronPDF 從 HTML 生成簡單的 PDF，但允許使用取消代幣來根據需要取消任務。

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 類) 和主程序邏輯 (Program 類)。

• 類 PdfGenerator： 此類別包含一個方法，該方法模擬生成 PDF 文件並支持通過 CancellationToken 進行取消。
• 我們在 main 方法中使用 CancellationTokenSource() 創建我們的取消代幣來源，然後通過傳遞 CancellationTokenSource 的 Token 屬性來創建我們的 Token 對象。
• ChromePdfRenderer 來自 IronPDF 程式庫，用於將 HTML 內容渲染為 PDF 文件。
• GeneratePdfWithCancellation 方法是非同步的 (async) 並返回一個任務。 此方法接受一個 CancellationToken (token) 來處理通過取消請求進行的任務取消。
• CancellationToken 允許我們安全地取消長時間運行的操作。 然而，取消是合作的，這意味著任務本身必須定期檢查代幣狀態。
• 在此代碼中，我們模擬了一個定期檢查消檢代幣的長任務。 關鍵點是，我們在 PDF 生成過程中手動檢查取消 (token.IsCancellationRequested)，如果通過了代幣，準備執行取消方法。
• 如果用戶按下鍵以指示程序的取消，任務會優雅地停止並引發 OperationCanceledException，防止 PDF 生成的完成。
• 如果沒有發生取消，則生成的 PDF 會以"output.pdf" 的形式保存，以防止程序運行完整的任務過程。

1. Web 應用

在 Web 應用中，使用者經常會啟動生成 PDF 格式報告等動作。 然而，如果用戶導航離開頁面或關閉瀏覽器，系統可以檢測到這一點並使用 CancellationToken 來停止 PDF 生成過程。

HttpContext.Response.RegisterForDispose(CancellationTokenSource);

HttpContext.Response.RegisterForDispose(CancellationTokenSource);

這簡單的實施允許 Web 伺服器更有效地擴展，不必將資源用於不再需要的任務上。

2. 長時間運行的報告

在報告應用中，用戶可能要求將大型數據集導出為 PDF。 若用戶改變主意或執行錯誤的查詢，CancellationToken 讓您能夠在過程中途取消任務，防止資源浪費。

3. 背景服務

在背景服務或微服務中，像生成大型 PDF 批次這樣耗時的任務，可以使用 CancellationToken 更有效地管理。 當服務即將關閉或被縮小時，進行中的任務可以被乾淨地取消，確保沒有數據丟失或損壞。