Utilisation de CancellationToken en C# avec les bibliothèques Iron Software

Pourquoi les demandes d'annulation importent dans les charges de travail d'Iron Software

Iron Software Les outils logiciels exécutent souvent des opérations asynchrones - par exemple :

• Une conversion HTML-à-PDF avec IronPDF HTML-to-PDF
• Une extraction OCR de longue durée avec IronOCR OCR extraction
• Une construction de document IronWord ou IronXL à l'intérieur de services en arrière-plan
• Une requête web HttpClient volumineuse avant la génération du PDF

Ceux-ci peuvent être des opérations de longue durée qui doivent se terminer gracieusement lorsqu'un utilisateur clique sur un bouton Annuler, navigue ailleurs, ou lorsque le code appelant émet une CancellationRequest.

L'utilisation de jetons d'annulation garantit :

• Applications réactives
• Meilleure gestion des ressources
• Libération contrôlée de ressources non gérées
• Un modèle d'annulation coopératif propre

Comprendre les bases de C# CancellationToken

C# fournit la classe CancellationTokenSource, qui crée un jeton CancellationToken. Un CTS new CancellationTokenSource() peut créer un jeton qui est transmis aux méthodes asynchrones.

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

Un jeton est transmis à l'aide d'un paramètre de méthode :

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

Dans la méthode, vous vérifiez périodiquement :

token.ThrowIfCancellationRequested();

token.ThrowIfCancellationRequested();

token.ThrowIfCancellationRequested()

ou inspecter la propriété 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

Cela fournit un modèle d'annulation coopérative où l'événement d'opération annulée se produit uniquement lorsque votre code vérifie le token.

Utilisation de CancellationToken avec IronPDF

Le rendu HTML d'IronPDF est conçu pour la programmation asynchrone, vous pouvez donc intégrer l'annulation de manière naturelle.

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

Utilisation de CancellationToken avec IronOCR

L'opération de longue durée d'IronOCR de numérisation d'images bénéficie également d'un CancellationToken interne :

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

Vérification périodique de l'annulation dans les opérations longues

Un modèle courant consiste à faire des boucles et à vérifier l'annulation :

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

Cela permet de garantir que les demandes d'annulation sont traitées de manière appropriée et opportune, et que le système ne gaspille pas de cycles.

Utilisation de CancellationToken avec HttpClient avant le rendu IronPDF

Lorsque vous effectuez une requête web pour récupérer du HTML avant de générer un PDF, transmettez toujours le jeton :

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

Cela permet de s'assurer que si l'utilisateur navigue ailleurs, le HttpClient s'annule en temps voulu.

Annulation dans les services d'arrière-plan de .NET Core

les services d'arrière-plan .NET Core incluent un CancellationToken interne automatiquement transmis à la méthode ExecuteAsync. À utiliser lors de l'exécution des outils d'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

Il s'agit d'un modèle général pour les tâches de longue durée côté serveur.

Bonnes pratiques pour l'utilisation de jetons d'annulation avec Iron Software

• Passez toujours CancellationToken dans les méthodes asynchrones.

• Utilisez ThrowIfCancellationRequested à l'intérieur des boucles.

• Préférez l'attente Task.Delay aux boucles serrées.

• Combinez les tokens avec LinkedTokenSource.

• Traitez toujours l'exception OperationCanceledException.

• Utilisez l'annulation pour une meilleure gestion des ressources et des applications réactives.

• N'oubliez pas que le C# est un langage de programmation orienté objet, alors concevez votre méthode d'annulation et votre logique d'annulation proprement.

Considérations avancées pour l'annulation de tâches

Pour s'assurer que cet article est utile à tout développeur .NET, voici une brève section supplémentaire qui incorpore la terminologie pertinente restante tout en renforçant les meilleures pratiques.

L'annulation des tâches en C# n'est pas automatique ; cela dépend de la logique d'annulation mise en œuvre dans votre méthode. La propriété token doit être vérifiée, et le token renvoyé aux consommateurs doit leur permettre de déterminer si l'opération a été annulée ou terminée avec succès. Si une demande ne peut pas être traitée, le système doit quand même s'arrêter de manière appropriée et opportune.

Si une interface utilisateur déclenche un bouton d'annulation, la méthode cancel de votre CancellationTokenSource signalera l'annulation, et votre code devra périodiquement vérifier via token.IsCancellationRequested. Lorsque des événements d'opération annulée se produisent, vous libérez les ressources et retournez le contrôle à l'appelant.

Une opération de longue durée comme la numérisation IronOCR de documents profondément imbriqués ou la génération par IronXL de feuilles de calcul massives devrait passer le CancellationToken à travers chaque couche. Lorsque l'utilisateur quitte la page, l'opération doit se terminer proprement.

Les produits Iron Software facilitent cette tâche car ils suivent nativement le modèle de programmation asynchrone de .NET. Lorsque vous écrivez vos propres bibliothèques, pensez à suivre les mêmes bonnes pratiques afin que vos consommateurs puissent annuler des opérations en temps voulu sans fuite de mémoire ni rétention de ressources non gérées.

Conclusion

L'utilisation de C# CancellationToken avec IronPDF, IronOCR, IronWord, et IronXL fournit une approche coopérative d'annulation qui garde les applications réactives, efficaces et robustes. En appliquant les meilleures pratiques de programmation asynchrone, en passant des tokens aux tâches asynchrones et en vérifiant périodiquement l'annulation, vous pouvez construire des applications .NET plus rapides, plus sûres et plus maintenables qui se terminent gracieusement lorsque besoin est.