C# Cancellationtoken（开发者用法）

它如何工作？

本质上，一个 CancellationToken 被传递给任务或方法，后者定期检查是否已经请求取消。 如果是这样，任务可以优雅地终止，释放资源并提高应用程序的响应能力。 这在诸如 PDF 生成等情况下特别有用，因为复杂文档可能需要时间来创建。

通过使用 CancellationTokens，可以避免那些运行时间不必要长的任务所带来的潜在缺点，例如系统资源的浪费和糟糕的用户体验。

内部取消令牌

在 C# 中，内部取消令牌是指在特定类或方法内部创建和管理的取消令牌，而不是从外部来源传入的。 这允许在单个组件的范围内更好地控制任务取消，从而能够监控和响应源自内部的取消请求。

在不向类的消费者暴露取消逻辑的情况下，使用内部取消令牌特别有用，从而保持界面的整洁。 这种方法可以增强代码的模块化，使管理复杂异步工作流更容易，同时仍然可以利用更广泛的 CancellationToken 框架提供的灵活性。

1. 防止不必要的负载

如果用户不再需要他们请求的 PDF，则没有理由继续该过程。 通过利用 CancellationToken，您可以停止 PDF 生成任务，防止对服务器产生额外负载，并提高整个应用程序的性能。

2. 增强用户体验

在桌面应用程序中，PDF 生成可能发生在 UI 线程上，如果任务长时间运行，则可能会锁定用户界面。 通过集成 CancellationToken，用户可以取消任务以保持应用程序响应迅速。

3. 提高可扩展性

在许多用户同时生成 PDF 的 Web 应用程序中，可扩展性是关键。 CancellationToken 允许您安全地取消不必要的任务，从而释放资源以高效处理其他请求。

步骤 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，但允许使用 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 类) 和主程序逻辑 (Program 类)。

• 类 PdfGenerator： 该类包含一个模拟生成 PDF 文件的方法，该方法支持通过 CancellationToken 进行取消。
• 我们在 main 方法中使用 CancellationTokenSource() 创建取消令牌源，然后将 CancellationTokenSource 的 Token 属性传递给令牌对象以创建它。
• 从 IronPDF 库中使用 ChromePdfRenderer 将 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 更有效地进行管理。 当服务将要关闭或缩减规模时，正在进行的任务可以被清理地取消，确保数据不会丢失或损坏。