WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / C#

OperationCanceledException – Abbruch einer Operation signalisieren

OperationCanceledException signalisiert, dass eine Operation abgebrochen wurde. Erfahre, wie die Ausnahme mit CancellationToken zusammenarbeitet, was ThrowIfCancellationRequested() bewirkt und worin sich eine Abbruchanforderung von ihrer Behandlung unterscheidet.

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

Syntax

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

OperationCanceledException im Namespace System signalisiert den Abbruch einer Operation. Abbruch erfolgt kooperativ: CancellationTokenSource.Cancel() fordert den Abbruch an, unterbricht aber nicht selbst den gerade ausgeführten Code. Die Operation muss die Anforderung erkennen und ihre Arbeit beenden.

Der bevorzugte Prüfpunkt ist token.ThrowIfCancellationRequested(): Die Methode löst nur dann eine Ausnahme aus, wenn ein Abbruch angefordert wurde, und fügt das Token hinzu. Das entspricht der Prüfung von token.IsCancellationRequested und der Ausführung von throw new OperationCanceledException(token);. Anhand der Eigenschaft CancellationToken der Ausnahme lässt sich das zugehörige Token ermitteln.

TaskCanceledException erbt von OperationCanceledException, daher deckt das Abfangen der Basisklasse beide Typen ab. Behandle erwarteten Abbruch an einer geeigneten Operationsgrenze; der Filter im Beispiel prüft sowohl die Identität des Tokens als auch die Abbruchanforderung, statt jede Ausnahme dieses Typs zu ignorieren.

Wird bei einer Überladung von Task.Run(..., token) für synchrone Delegaten der Delegat ausgeführt und löst er diese Ausnahme aus, wechselt der Task nur dann in den Zustand Canceled, wenn das Token der Ausnahme mit dem übergebenen Token übereinstimmt und für dieses Token ein Abbruch angefordert wurde. Andernfalls wechselt der Task in den Zustand Faulted. Kehrt der Delegat normal zurück, ist der Zustand RanToCompletion.

Bei einem async-Delegaten, der einen Task zurückgibt, kann eine nicht abgefangene OperationCanceledException den inneren Task auch dann abbrechen, wenn das Token der Ausnahme vom an Task.Run übergebenen Token abweicht oder kein Abbruch angefordert wurde. Der von Task.Run zurückgegebene Proxy-Task übernimmt den Endzustand des inneren Tasks. Das synchrone Beispiel zeigt den Mechanismus ohne zeitliche Wettläufe und benötigt keine Sprachfunktionen der Preview-Version.

Beispiele

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");
}

Ergebnis

Canceled

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen