Używanie C# CancellationToken z bibliotekami Iron Software

Dłączego prośby o anulowanie są ważne w obciążeniach Iron Software

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

• Konwersja HTML do PDF w IronPDF HTML-to-PDF conversion
• Długotrwała ekstrakcja OCR w IronOCR OCR extraction
• Tworzenie dokumentu IronWord lub IronXL wewnątrz usług w tle IronWord lub IronXL document
• Duże żądanie sieciowe HttpClient przed generacją PDF

Mogą to być operacje długotrwałe, które muszą się łagodnie zakończyć, gdy użytkownik kliknie przycisk Anuluj, nawigacja przestanie być możliwa lub gdy kod wywołujący wyda żą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

Zrozumienie podstaw 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

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

W ramach tej metody należy okresowo sprawdzać:

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

Zapewnia to wzorzec anulowania opartego na współpracy, w którym zdarzenie anulowania operacji występuje tylko wtedy, gdy kod sprawdza token.

Korzystanie z CancellationToken w IronPDF

Renderowanie HTML w IronPDF jest zaprojektowane z myślą o programowaniu asynchronicznym, dzięki czemu można w naturalny sposób zintegrować funkcję anulowania.

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

Korzystanie z CancellationToken w IronOCR

Długotrwałe działanie IronOCR związane ze skanowaniem obrazów również 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

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

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

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

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 wystąpią zdarzenia anulowania operacji, zwalniasz zasoby i zwracasz kontrolę do wywołującego.

Długotrwała operacja, taka jak skanowanie głęboko zagnieżdżonych dokumentów przez IronOCR lub generowanie ogromnych arkuszy kalkulacyjnych przez IronXL, powinna przekazywać token anulowania (CancellationToken) na każdym poziomie. 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

Wykorzystanie C# CancellationToken z IronPDF, IronOCR, IronWord i IronXL zapewnia kooperacyjne podejście do anulowania, które sprawia, że aplikacje są responsywne, wydajne i solidne. Stosując najlepsze praktyki w programowaniu asynchronicznym, przekazując tokeny do zadań asynchronicznych i okresowo sprawdzając, czy nie nastąpiło anulowanie, można tworzyć szybsze, bezpieczniejsze i łatwiejsze w utrzymaniu aplikacje .NET, które w razie potrzeby kończą działanie w sposób płynny.