Używanie C# CancellationToken z bibliotekami Iron Software

Współcześni deweloperzy .NET często pracują z programowaniem asynchronicznym podczas integracji bibliotek takich jak IronPDF, IronOCR, IronWord oraz IronXL. Te produkty często wykonują długotrwałe zadania—takie jak renderowanie PDF, przetwarzanie zawartości OCR, czy generowanie dużych arkuszy kalkulacyjnych—i poprawnym sposobem utrzymania responsywności aplikacji jest użycie opartej na C# CancellationToken anulacji.

Ten artykuł wyjaśnia, jak używać tokenów anulowania, jak metoda akceptuje token, jak obsługiwać anulowanie zadania oraz jak zintegrować te wzorce z bibliotekami Iron Software w odpowiedni i terminowy sposób. Omówimy również najlepsze praktyki, zarządzanie zasobami oraz jak używać wielu CancellationTokens jednocześnie.

Dlaczego prośby o anulację mają znaczenie w obciążeniach Iron Software

Narzędzia Iron Software często wykonują operacje asynchroniczne - na przykład:

• Konwersja HTML na PDF w IronPDF konwersja HTML do PDF
• Długotrwała ekstrakcja OCR w IronOCR ekstrakcja OCR
• Budowanie dokumentu IronWord lub IronXL wewnątrz usług działających w tle
• Duże żądanie sieciowe HttpClient przed generacją PDF

Są to operacje długotrwałe, które muszą być elegancko zakończone, gdy użytkownik kliknie przycisk Anuluj, opuści stronę lub gdy wywołujący kod wydaje żądanie anulowania.

Użycie tokenów anulowania zapewnia:

• Responsywne aplikacje
• Lepsze zarządzanie zasobami
• Kontrolowane zwalnianie zasobów nieskładowanych
• Czysty model współpracującego anulowania

Podstawy C# CancellationToken

Język C# udostępnia klasę CancellationTokenSource, która tworzy token CancellationToken. Nowa metoda CTS CancellationTokenSource() może utworzyć token, który jest przekazywany do metod asynchronicznych.

var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;

var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;

Dim cts As New CancellationTokenSource()
Dim token As CancellationToken = cts.Token

Dim cts As New CancellationTokenSource()
Dim token As CancellationToken = cts.Token

Token jest przekazywany za pomocą parametru metody:

public async Task ProcessPdfAsync(string html, CancellationToken token)

public async Task ProcessPdfAsync(string html, CancellationToken token)

Public Async Function ProcessPdfAsync(html As String, token As CancellationToken) As Task

Public Async Function ProcessPdfAsync(html As String, token As CancellationToken) As Task

W ramach tej metody należy okresowo sprawdzać:

token.ThrowIfCancellationRequested();

token.ThrowIfCancellationRequested();

token.ThrowIfCancellationRequested()

token.ThrowIfCancellationRequested()

lub sprawdzić właściwość IsCancellationRequested:

if (token.IsCancellationRequested)
{
    Console.WriteLine("Cancellation requested.");
    return;
}

if (token.IsCancellationRequested)
{
    Console.WriteLine("Cancellation requested.");
    return;
}

If token.IsCancellationRequested Then
    Console.WriteLine("Cancellation requested.")
    Return
End If

If token.IsCancellationRequested Then
    Console.WriteLine("Cancellation requested.")
    Return
End If

Zapewnia to wzorzec kooperacyjnej anulacji, gdzie zdarzenie anulacji operacji występuje tylko wtedy, gdy twój kod sprawdza token.

Korzystanie z CancellationToken w IronPDF

Renderowanie HTML w IronPDF jest zaprojektowane do programowania asynchronicznego, więc możesz naturalnie zintegrować anulowanie.

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);
    }

Imports System
Imports System.Threading
Imports System.Threading.Tasks

Public Class PdfGenerator
    Public Async Function BuildPdfAsync(html As String, token As CancellationToken) As Task(Of PdfDocument)
        Console.WriteLine(vbCrLf & "[Generator] Starting PDF rendering process...")
        Dim renderer As 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)
    End Function
End Class

Imports System
Imports System.Threading
Imports System.Threading.Tasks

Public Class PdfGenerator
    Public Async Function BuildPdfAsync(html As String, token As CancellationToken) As Task(Of PdfDocument)
        Console.WriteLine(vbCrLf & "[Generator] Starting PDF rendering process...")
        Dim renderer As 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)
    End Function
End Class

Przykładowy wynik konsoli

Poniżej przedstawiono publiczną klasę async Task, która obsługuje anulowanie w wielu punktach. W przypadku anulowania metoda zgłasza wyjątek OperationCanceledException, który należy obsłużyć w bloku catch.

Korzystanie z CancellationToken w IronOCR

Długotrwała operacja skanowania obrazów w IronOCR także korzysta z wewnętrznego 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);
    }
}

Imports System.Threading
Imports System.Threading.Tasks
Imports IronOcr

Public Class OcrProcessor
    Private ReadOnly ocr As New IronTesseract()

    Public Async Function ExtractTextAsync(path As String, token As CancellationToken) As Task(Of String)
        ' 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(Function() ocr.Read(path).Text, token)
    End Function
End Class

Imports System.Threading
Imports System.Threading.Tasks
Imports IronOcr

Public Class OcrProcessor
    Private ReadOnly ocr As New IronTesseract()

    Public Async Function ExtractTextAsync(path As String, token As CancellationToken) As Task(Of String)
        ' 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(Function() ocr.Read(path).Text, token)
    End Function
End Class

Przykładowy wynik

Generowanie dokumentów w IronWord i tworzenie arkuszy kalkulacyjnych w IronXL działa w ten sam sposób. Ponieważ wszystkie te operacje można anulować, wzorzec kooperacyjnego anulowania pozwala uniknąć blokowania wątków interfejsu użytkownika lub usług działających w tle.

Okresowe sprawdzanie, czy długotrwałe operacje nie zostały anulowane

Typowym wzorcem jest pętla i sprawdzanie anulowania:

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
    }
}

Imports System.Threading
Imports System.Threading.Tasks

Public Async Function LongRunningOperation(token As CancellationToken) As Task
    For i As Integer = 0 To 999
        token.ThrowIfCancellationRequested()
        Await Task.Delay(10, token) ' Await Task.Delay helps cooperative cancellation
    Next
End Function

Imports System.Threading
Imports System.Threading.Tasks

Public Async Function LongRunningOperation(token As CancellationToken) As Task
    For i As Integer = 0 To 999
        token.ThrowIfCancellationRequested()
        Await Task.Delay(10, token) ' Await Task.Delay helps cooperative cancellation
    Next
End Function

Dzięki temu wnioski o anulowanie są rozpatrywane w odpowiedni i terminowy sposób, a system nie marnuje zasobów.

Korzystanie z CancellationToken w HttpClient przed renderowaniem w IronPDF

Podczas wysyłania żądania sieciowego w celu pobrania kodu HTML przed wygenerowaniem pliku PDF należy zawsze przekazać 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);
}

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);
}

Imports System.Net.Http
Imports System.Threading
Imports System.Threading.Tasks

Dim client As New HttpClient()

Public Async Function FetchHtmlAsync(url As String, token As CancellationToken) As Task(Of String)
    Dim response = Await client.GetAsync(url, token)

    If Not response.IsSuccessStatusCode Then
        Throw New Exception("Error occurred while requesting content.")
    End If

    Return Await response.Content.ReadAsStringAsync(token)
End Function

Imports System.Net.Http
Imports System.Threading
Imports System.Threading.Tasks

Dim client As New HttpClient()

Public Async Function FetchHtmlAsync(url As String, token As CancellationToken) As Task(Of String)
    Dim response = Await client.GetAsync(url, token)

    If Not response.IsSuccessStatusCode Then
        Throw New Exception("Error occurred while requesting content.")
    End If

    Return Await response.Content.ReadAsStringAsync(token)
End Function

Dzięki temu, jeśli użytkownik opuści stronę, HttpClient zostanie anulowany w odpowiednim czasie.

Anulowanie w usługach działających w tle .NET Core

Usługi działające w tle .NET Core zawierają wewnętrzny token CancellationToken, który jest automatycznie przekazywany do metody ExecuteAsync. Używaj go podczas korzystania z narzędzi Iron Software:

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);
    }
}

Protected Overrides Async Function ExecuteAsync(stoppingToken As CancellationToken) As Task
    While Not stoppingToken.IsCancellationRequested
        Await ProcessPdfAsync("<h1>Hello</h1>", stoppingToken)
        Await Task.Delay(5000, stoppingToken)
    End While
End Function

Protected Overrides Async Function ExecuteAsync(stoppingToken As CancellationToken) As Task
    While Not stoppingToken.IsCancellationRequested
        Await ProcessPdfAsync("<h1>Hello</h1>", stoppingToken)
        Await Task.Delay(5000, stoppingToken)
    End While
End Function

Jest to ogólny wzorzec dla długotrwałych zadań po stronie serwera.

Najlepsze praktyki dotyczące korzystania z tokenów anulowania w oprogramowaniu Iron Software

• Zawsze przekazuj CancellationToken do metod asynchronicznych.

• Używaj ThrowIfCancellationRequested wewnątrz pętli.

• Zamiast ciasnych pętli zaleca się stosowanie await Task.Delay.

• Połącz tokeny z LinkedTokenSource.

• Zawsze należy obsługiwać wyjątek OperationCanceledException.

• Wykorzystaj funkcję anulowania, aby zapewnić lepsze zarządzanie zasobami i responsywność aplikacji.

• Pamiętaj, że C# jest językiem programowania obiektowego, więc zaprojektuj swoją metodę anulowania i logikę anulowania w przejrzysty sposób.

Zaawansowane kwestie dotyczące anulowania zadania

Aby zapewnić, że jest to dobry artykuł dla każdego programisty .NET, poniżej znajduje się krótka sekcja uzupełniająca, która zawiera pozostałą istotną terminologię, jednocześnie podkreślając najlepsze praktyki.

Anulowanie zadania w języku C# nie następuje automatycznie; To zależy od logiki anulowania zaimplementowanej w Twojej metodzie. Należy sprawdzić właściwość tokenu, a token zwracany konsumentom powinien umożliwiać im ustalenie, czy operacja została anulowana, czy pomyślnie zakończona. Jeśli żądanie nie może zostać zakończone, system powinien mimo to zakończyć działanie w odpowiedni i terminowy sposób.

Jeśli interfejs użytkownika uruchomi przycisk anulowania, metoda cancel w CancellationTokenSource zasygnalizuje anulowanie, a kod powinien okresowo sprawdzać to za pomocą token.IsCancellationRequested. Gdy zdarzenia anulacji operacji występują, uwalniasz zasoby i zwracasz kontrolę do wywołującego.

Długotrwała operacja, taka jak skanowanie IronOCR głęboko zagnieżdżonych dokumentów czy generowanie IronXL masywnych arkuszy kalkulacyjnych, powinna przekazywać CancellationToken przez każdą warstwę. Gdy użytkownik opuści stronę, operacja powinna zakończyć się poprawnie.

Produkty Iron Software ułatwiają to zadanie, ponieważ natywnie obsługują model programowania asynchronicznego .NET. Tworząc własne biblioteki, warto stosować te same najlepsze praktyki, aby użytkownicy mogli w odpowiednim czasie anulować operacje bez utraty pamięci lub zatrzymywania zasobów niezarządzanych.

Wnioski

Używanie C# CancellationToken z IronPDF, IronOCR, IronWord i IronXL dostarcza kooperacyjne podejście do anulacji, które utrzymuje aplikacje responsywne, wydajne i solidne. Stosując najlepsze praktyki w programowaniu asynchronicznym, przekazując tokeny do zadań asynchronicznych i okresowo sprawdzając anulację, można tworzyć szybsze, bezpieczniejsze i bardziej łatwe do utrzymania aplikacje .NET, które elegancko kończą działanie w razie potrzeby.