Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / C#

OperationCanceledException — signaler l’annulation d’une opération

OperationCanceledException signale qu’une opération a été annulée. Découvrez son fonctionnement avec CancellationToken, le rôle de ThrowIfCancellationRequested() et la différence entre demander une annulation et la prendre en compte.

Version : .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification

Syntaxe

token.ThrowIfCancellationRequested();
throw new OperationCanceledException(token);
catch (OperationCanceledException ex) when (ex.CancellationToken == token && token.IsCancellationRequested) { /* handle expected cancellation */ }

OperationCanceledException, dans l’espace de noms System, signale l’annulation d’une opération. L’annulation est coopérative : CancellationTokenSource.Cancel() demande l’annulation, mais n’interrompt pas à lui seul le code en cours d’exécution. L’opération doit observer la demande et arrêter son travail.

Le point de contrôle recommandé est token.ThrowIfCancellationRequested() : il lève une exception uniquement si une annulation a été demandée et inclut le jeton. Cela équivaut à vérifier token.IsCancellationRequested puis à exécuter throw new OperationCanceledException(token);. La propriété CancellationToken de l’exception permet d’identifier le jeton qui lui est associé.

TaskCanceledException dérive de OperationCanceledException ; intercepter la classe de base couvre donc les deux types. Traitez l’annulation attendue à une limite appropriée de l’opération ; le filtre de l’exemple vérifie à la fois l’identité du jeton et la demande d’annulation, au lieu d’ignorer toutes les exceptions de ce type.

Pour les surcharges de Task.Run(..., token) qui prennent un délégué synchrone, si le délégué s’exécute et lève cette exception, la tâche ne passe à l’état Canceled que si le jeton de l’exception correspond au jeton fourni et qu’une annulation a été demandée pour ce jeton. Sinon, la tâche passe à l’état Faulted. Un retour normal du délégué produit l’état RanToCompletion.

Dans le cas d’un délégué async qui renvoie une tâche, une OperationCanceledException non interceptée dans le délégué peut annuler la tâche interne, même si le jeton de l’exception diffère de celui fourni à Task.Run ou si aucune annulation n’a été demandée. La tâche proxy renvoyée par Task.Run reflète l’issue de la tâche interne. L’exemple synchrone illustre le mécanisme sans risque de course temporelle et ne nécessite aucune fonctionnalité de langage en version preview.

Exemples

using System;
using System.Threading;

using var source = new CancellationTokenSource();
CancellationToken token = source.Token;
source.Cancel();

try
{
    token.ThrowIfCancellationRequested();
    Console.WriteLine("Completed");
}
catch (OperationCanceledException ex)
    when (ex.CancellationToken == token && token.IsCancellationRequested)
{
    Console.WriteLine("Canceled");
}

Résultat

Canceled

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources