跳至页脚内容
.NET 帮助

C# Cancellationtoken(开发者用法)

在现代软件开发中,尤其是在需要生成大型或复杂 PDF 文件的应用程序中,高效管理长时间运行的任务至关重要。 C# 开发人员经常依赖于 IronPDF 进行无缝的 PDF 创建,但处理可能冗长的 PDF 生成任务需要一种管理用户中断或取消的方法。

这就是 C# 中 CancellationToken 发挥作用的地方。 通过将其与 IronPDF 集成,可以确保 PDF 生成任务响应迅速且高效。 在本文中,我们将探讨 CancellationToken 的重要性,为什么它与 IronPDF 搭配良好,以及如何实现它以优雅地取消任务。

C# 中的 CancellationToken 是什么?

CancellationToken 是 C# 中异步编程的基本组成部分。 它允许您发出任务应被取消的信号,从而让开发人员对长时间运行的操作有更大的控制力。 当执行生成报告或发票等任务时,这尤其有帮助,因为您可能希望在达到目标数量之前从数据中持续生成动态报告,然后可以使用 C# 取消令牌来指示应取消操作,这样可以优雅地结束程序。

它如何工作?

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

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

内部取消令牌

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

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

为什么与 IronPDF 一起使用取消令牌?

在生成 PDF 时,尤其是在 Web 应用程序或复杂的报告系统中,您可能会遇到这种情况:用户启动了一个任务,例如创建一个大 PDF 文件,但随后离开或不再需要结果。 在这些情况下,您希望能够取消 PDF 生成过程,以避免对服务器或用户界面的不必要负载。

以下是使用 CancellationTokenIronPDF 至关重要的原因:

1. 防止不必要的负载

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

2. 增强用户体验

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

3. 提高可扩展性

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

如何使用 IronPDF 实现 CancellationToken

现在我们知道 CancellationToken 是多么有用,让我们来看看如何将其与 IronPDF 结合实现。

步骤 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;
Imports IronPdf
$vbLabelText   $csharpLabel

步骤 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.");
    }
}
Imports IronPdf
Imports System
Imports System.Threading
Imports System.Threading.Tasks

Public Class PdfGenerator
	Public Async Function GeneratePdfWithCancellation(ByVal token As CancellationToken) As Task
		Dim Renderer = New ChromePdfRenderer()
		Try
			' Check for cancellation before starting
			token.ThrowIfCancellationRequested()

			' Simulating a long task that can be checked for cancellation periodically
			For i As Integer = 0 To 9
				' 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 Then
					Console.WriteLine("Cancellation requested. Throwing exception.")
					token.ThrowIfCancellationRequested() ' This will trigger an OperationCanceledException
				End If
			Next i

			' Simulate PDF creation after the long process
			Dim 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 e1 As OperationCanceledException
			' Handle task cancellation
			Console.WriteLine("PDF generation was canceled.")
		Catch ex As Exception
			' Handle other exceptions
			Console.WriteLine($"An error occurred: {ex.Message}")
		End Try
	End Function
End Class

Public Class Program
	Public Shared Async Function Main(ByVal args() As String) As Task
		' Create a CancellationTokenSource
		Dim cancellationTokenSource As New CancellationTokenSource()

		' Create our cancellation token
		Dim token = cancellationTokenSource.Token

		' Start the PDF generation task
		Dim pdfGenerator As New PdfGenerator()
		Dim pdfTask As Task = 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 e1 As OperationCanceledException
			' Confirm the cancellation
			Console.WriteLine("The PDF generation was canceled.")
		Finally
			cancellationTokenSource.Dispose()
		End Try

		Console.WriteLine("Program finished.")
	End Function
End Class
$vbLabelText   $csharpLabel

控制台输出

C# Cancellationtoken(对开发人员的工作原理):图 2 - 控制台输出

PDF 输出

C# Cancellationtoken(对开发人员的工作原理):图 3 - 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",以防止程序执行完整的任务过程。

IronPDF 与 CancellationToken 的真实用例

在许多实际情况下,使用一个或多个取消令牌与 IronPDF 可以提升应用程序的性能和用户体验。 以下是一些示例:

1. Web 应用程序

在 Web 应用程序中,用户经常会发起生成 PDF 格式报告的操作。 然而,如果用户离开页面或关闭浏览器,系统可以检测到这一点并使用 CancellationToken 来停止 PDF 生成过程。

HttpContext.Response.RegisterForDispose(CancellationTokenSource);
HttpContext.Response.RegisterForDispose(CancellationTokenSource);
HttpContext.Response.RegisterForDispose(CancellationTokenSource)
$vbLabelText   $csharpLabel

这一简单实现使 Web 服务器能够更有效地扩展,而不必将资源分配给不再需要的任务。

2. 长时间运行的报告

在报告应用程序中,用户可能会请求将大型数据集导出为 PDF。 如果用户改变主意或查询错误,CancellationToken 允许您在中途取消任务,从而防止资源浪费。

3. 后台服务

在后台服务或微服务中,生成大型 PDF 批次等耗时任务可以通过 CancellationToken 更有效地进行管理。 当服务将要关闭或缩减规模时,正在进行的任务可以被清理地取消,确保数据不会丢失或损坏。

结论

现在我们已经结束了今天关于使用 IronPDF 的取消令牌的讨论,您将能够像专业人士一样将其实现到您的 PDF 项目中! 使用 C# CancellationTokenIronPDF,让您构建出更高效和响应迅速的应用程序,能够优雅地处理 PDF 生成任务。 这种方法使得协作取消模型成为可能,允许任务在执行过程中的安全点检查取消请求,而不是被突然终止。

无论您是在管理长时间运行的报告、按需 PDF 生成的 Web 应用程序,还是后台服务,结合 CancellationToken 或同时使用多个令牌,确保不必要的任务可以被取消,从而防止资源浪费并增强用户体验。

只需编写几行代码,您就可以提高应用程序的可扩展性和响应能力,同时赋予用户对其操作的更多控制。 如果您还没有探索过 IronPDF,现在正是尝试免费试用版的绝佳时机,看看其强大的 PDF 生成功能如何改变您的 C# 项目。

常见问题解答

如何在 C# 中使用 CancellationToken 管理长时间运行的任务?

您可以通过将 CancellationToken 集成到您的长时间运行的任务中,通过将其传递给任务并定期检查是否已请求取消。这样可以优雅地终止任务,释放资源并维护应用程序的响应能力。

为什么 CancellationToken 在 PDF 生成中很重要?

在 PDF 生成中,CancellationToken 通过允许取消那些变得不必要的任务(例如当用户离开页面时)来有效地管理资源。这可以防止过多的服务器负载并提升用户体验。

如何在 C# PDF 生成任务中实现 CancellationToken?

要在 C# PDF 生成任务中实现 CancellationToken,您需要将该令牌传递给您的方法,并在执行过程中定期检查取消请求。如果检测到取消,则可以优雅地终止任务。

在 PDF 生成中使用异步方法与 CancellationToken 的目的是什么?

在 PDF 生成中使用带有 CancellationToken 的异步方法允许任务异步运行,改善应用程序响应能力,并在任务不再需要时进行取消。

CancellationToken 如何改善网络应用程序中的用户体验?

通过利用 CancellationToken,网络应用程序可以在用户离开时取消 PDF 生成等任务,防止不必要的处理,并保持应用程序响应性,从而改善用户体验。

在异步 PDF 创建中 ChromePdfRenderer 的作用是什么?

来自 IronPDF 的 ChromePdfRenderer 用于将 HTML 内容转换为 PDF 文档。它支持异步操作,允许您使用 CancellationToken 有效管理任务的生命周期和响应能力。

如果在 PDF 生成过程中发出取消请求,会发生什么?

如果在 PDF 生成过程中发出取消请求,任务将检查 CancellationToken 的状态。如果检测到取消,它将抛出一个 OperationCanceledException,停止进程以节省资源。

CancellationToken 如何增强应用程序的可扩展性?

CancellationToken 通过允许应用程序取消不必要的任务(如生成 PDF)来增强可扩展性,从而减少资源消耗并改进应用程序的整体性能。

在后台服务中使用 CancellationToken 的好处是什么?

在后台服务中,使用 CancellationToken 可通过允许在服务关闭或进行缩放操作时对批处理 PDF 处理等长时间运行的任务进行取消来进行管理。

将 CancellationToken 与 IronPDF 集成如何提高应用程序效率?

将 CancellationToken 与 IronPDF 集成允许通过取消不必要的 PDF 生成任务实现更好的资源管理,从而提高应用程序效率和响应性,同时减少服务器负载。

Curtis Chau
技术作家

Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。

除了开发之外,Curtis 对物联网 (IoT) 有浓厚的兴趣,探索将硬件和软件集成的新方法。在空闲时间,他喜欢玩游戏和构建 Discord 机器人,将他对技术的热爱与创造力相结合。