UTILISATION DE LA SUITE IRON

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

Mis à jour:

Les développeurs .NET modernes travaillent souvent avec la programmation asynchrone lorsqu'ils intègrent des bibliothèques telles que IronPDF, IronOCR, IronWord, et IronXL. Ces produits exécutent fréquemment des tâches de longue durée - telles que le rendu de PDF, le traitement de contenu OCR ou la génération de feuilles de calcul volumineuses - et la bonne façon de maintenir la réactivité des applications est d'utiliser l'annulation basée sur C# CancellationToken.

Cet article explique comment utiliser les jetons d'annulation, comment une méthode accepte un jeton, comment gérer l'annulation des tâches et comment intégrer ces modèles aux bibliothèques Iron Software de manière appropriée et opportune. Nous abordons également les meilleures pratiques, la gestion des ressources et l'utilisation simultanée de plusieurs CancellationTokens.

Pourquoi les demandes d'annulation sont importantes dans les charges de travail des logiciels Iron Software

IronSoftware

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

  • Une conversion IronPDF HTML-to-PDF

  • Un IronOcr de longue haleine extraction d'OCR

  • Un document IronWord ou IronXL construit à l'intérieur des services d'arrière-plan

  • Une requête web HttpClient volumineuse avant la génération du PDF

Il peut s'agir d'opérations de longue durée qui doivent se terminer de manière élégante lorsqu'un utilisateur clique sur un bouton d'annulation, 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 CancellationToken en C

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;
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

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)
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

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

token.ThrowIfCancellationRequested();
token.ThrowIfCancellationRequested();
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

ou inspecter la propriété IsCancellationRequested :

if (token.IsCancellationRequested)
{
    Console.WriteLine("Cancellation requested.");
    return;
}
if (token.IsCancellationRequested)
{
    Console.WriteLine("Cancellation requested.");
    return;
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Il s'agit d'un modèle d'annulation coopératif dans lequel l'événement d'annulation de l'opération ne se produit que lorsque votre code vérifie le jeton.

Utilisation de CancellationToken avec IronPDF

Le rendu HTML d'IronPDF est conçu pour la programmation asynchrone, ce qui vous permet d'intégrer naturellement l'annulation.

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);
    }
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Exemple de sortie de console

Sortie de console

Ceci montre une tâche asynchrone publique qui prend en charge l'annulation à plusieurs endroits. Lorsque l'annulation se produit, la méthode génère une exception OperationCanceledException, que vous traitez dans un bloc catch.

Utilisation de CancellationToken avec IronOCR

L'opération de longue haleine d'IronOcr consistant à numériser des 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);
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

Exemple de sortie

Exemple d'utilisation d'IronOCR avec des CancellationTokens

La génération de documents IronWord et l'assemblage de feuilles de calcul IronXL fonctionnent de la même manière. Comme il s'agit d'opérations annulables, le modèle d'annulation coopératif évite de bloquer les threads de l'interface utilisateur ou les services d'arrière-plan.

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
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

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);
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

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);
    }
}
IRON VB CONVERTER ERROR developers@ironsoftware.com
$vbLabelText   $csharpLabel

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'annulation d'opération se produisent, vous libérez les ressources et rendez le contrôle à l'appelant.

Une opération de longue haleine comme IronOCR scannant des documents profondément imbriqués ou IronXL générant des feuilles de calcul massives doit transmettre 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 propose une approche d'annulation coopérative qui permet aux applications de rester réactives, efficaces et robustes. En appliquant les meilleures pratiques de programmation asynchrone, en passant des jetons aux tâches asynchrones et en vérifiant périodiquement l'annulation, vous pouvez créer des applications .NET plus rapides, plus sûres et plus faciles à maintenir, qui se terminent de manière élégante lorsque c'est nécessaire.