CKTIS / C#
OperationCanceledException — segnalare l’annullamento di un’operazione
OperationCanceledException segnala che un’operazione è stata annullata. Scopri come funziona con CancellationToken, cosa fa ThrowIfCancellationRequested() e quale differenza c’è tra richiedere l’annullamento e prenderne atto.
Versione: .NET 10; repository net10.0 and LangVersion=preview; feature versions require per-entry verification
Sintassi
token.ThrowIfCancellationRequested();
throw new OperationCanceledException(token);
catch (OperationCanceledException ex) when (ex.CancellationToken == token && token.IsCancellationRequested) { /* handle expected cancellation */ }OperationCanceledException, nello spazio dei nomi System, segnala l’annullamento di un’operazione. L’annullamento è cooperativo: CancellationTokenSource.Cancel() richiede l’annullamento, ma non interrompe da solo il codice in esecuzione. L’operazione deve rilevare la richiesta e interrompere il proprio lavoro.
Il punto di controllo consigliato è token.ThrowIfCancellationRequested(): genera un’eccezione solo se è stato richiesto l’annullamento e include il token. Equivale a controllare token.IsCancellationRequested ed eseguire throw new OperationCanceledException(token);. La proprietà CancellationToken dell’eccezione consente di identificare il token associato.
TaskCanceledException deriva da OperationCanceledException, quindi intercettare la classe base copre entrambi i tipi. Gestisci l’annullamento previsto in un punto appropriato dell’operazione; il filtro dell’esempio controlla sia l’identità del token sia la richiesta di annullamento, invece di ignorare tutte le eccezioni di questo tipo.
Negli overload di Task.Run(..., token) che accettano un delegato sincrono, se il delegato viene eseguito e genera questa eccezione, l’attività passa allo stato Canceled solo se il token dell’eccezione coincide con quello fornito e per quel token è stato richiesto l’annullamento. In caso contrario passa allo stato Faulted. Se il delegato termina normalmente, lo stato è RanToCompletion.
Nel caso di un delegato async che restituisce un’attività, una OperationCanceledException non intercettata nel delegato può annullare l’attività interna anche se il token dell’eccezione è diverso da quello passato a Task.Run o se non è stato richiesto l’annullamento. L’attività proxy restituita da Task.Run riflette l’esito di quella interna. L’esempio sincrono mostra il meccanismo senza gare temporali e non richiede funzionalità del linguaggio in versione preview.
Esempi
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");
}
Risultato
Canceled
Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.