CancellationToken in C#

Users close tabs, timeouts expire, servers shut down. When nobody wants the result any more, continuing to work wastes CPU, database connections, memory and money.

.NET uses cooperative cancellation. One side requests cancellation; the code doing the work notices the request and stops at a safe point. Nothing is killed from the outside. The old way, Thread.Abort, could stop a thread in the middle of anything (half-written files, held locks) and it is not supported at all on modern .NET: calling it throws PlatformNotSupportedException.

The four types you will meet

A console app downloads pages one by one. The user can press C to stop. Step through it line by line and watch the source, the token and the console.

using var cts = new CancellationTokenSource();
Task work = DownloadAllAsync(urls, cts.Token);

Console.WriteLine("Press C to cancel");
if (Console.ReadKey(true).Key == ConsoleKey.C)
    await cts.CancelAsync();

try
{
    await work;
    Console.WriteLine("All done");
}
catch (OperationCanceledException)
{
    Console.WriteLine("Canceled by user");
}

static async Task DownloadAllAsync(string[] urls, CancellationToken ct)
{
    using var http = new HttpClient();
    foreach (var url in urls)
    {
        ct.ThrowIfCancellationRequested();
        string html = await http.GetStringAsync(url, ct);
        await File.WriteAllTextAsync(NameFor(url), html, ct);
    }
}

The four golden rules from this example

1. Whoever creates the source owns it: they cancel it and they dispose it (using var).
2. Pass the token, not the source. Methods take a CancellationToken as their last parameter.
3. Forward the token to every async call that accepts one. That is what makes the stop fast.
4. Catch OperationCanceledException at the top, where you decide what “canceled” means for the user. Don’t treat it as an error.

This is a faithful model of how a CancellationTokenSource behaves. Try odd sequences: register after cancel, reset after cancel, cancel after dispose.

A token is useless unless someone looks at it. There are three ways to observe it, and real code mixes them.

await Task.Delay(TimeSpan.FromSeconds(5), ct);
var user = await db.Users.FindAsync([id], ct);
await stream.CopyToAsync(output, ct);

foreach (var row in rows)
{
    ct.ThrowIfCancellationRequested();
    Crunch(row);
}

if (ct.IsCancellationRequested)
    return Partial(resultsSoFar);

using var reg = ct.Register(() => process.Kill(entireProcessTree: true));
await legacyApi.WaitUntilDoneAsync();

// sync code that must block:
ct.WaitHandle.WaitOne(TimeSpan.FromSeconds(10));

Simulator: how often should you check?

A worker processes 30 items of CPU work, each taking about 180 ms. Start it, press Cancel part-way through, and compare how quickly each strategy actually stops.

Every public member you will use, with the version it arrived in where it matters.

CancellationTokenSource class · IDisposable

CancellationToken readonly struct

CancellationTokenRegistration struct · IDisposable · IAsyncDisposable

Related types & helpers

Real operations have several “off switches” at once: the user, a deadline, and the app shutting down. CreateLinkedTokenSource merges them into one token.

app.MapGet("/export", async (ExportService exporter, IHostApplicationLifetime lifetime,
                             CancellationToken requestAborted) =>
{
    using var timeoutCts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
    using var linked = CancellationTokenSource.CreateLinkedTokenSource(
        requestAborted, timeoutCts.Token, lifetime.ApplicationStopping);

    try
    {
        var csv = await exporter.RunAsync(linked.Token);
        return Results.File(csv, "text/csv");
    }
    catch (OperationCanceledException) when (timeoutCts.IsCancellationRequested)
    {
        return Results.StatusCode(StatusCodes.Status504GatewayTimeout);
    }
    catch (OperationCanceledException) when (lifetime.ApplicationStopping.IsCancellationRequested)
    {
        return Results.StatusCode(StatusCodes.Status503ServiceUnavailable);
    }
    // requestAborted: let it bubble up - nobody is listening for a response
});

A timeout is just cancellation triggered by a clock. There are several ways to set one, and one important trap.

// 1. Constructor: starts the clock now
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));

// 2. CancelAfter: start or move the deadline later
cts.CancelAfter(TimeSpan.FromSeconds(30));

// 3. Combine with a caller's token
using var linked = CancellationTokenSource.CreateLinkedTokenSource(callerToken);
linked.CancelAfter(TimeSpan.FromSeconds(10));

// 4. Testable time (.NET 8+)
using var testable = new CancellationTokenSource(TimeSpan.FromSeconds(10), timeProvider);

var time = new FakeTimeProvider();
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30), time);

Assert.False(cts.IsCancellationRequested);
time.Advance(TimeSpan.FromSeconds(31));   // no real waiting
Assert.True(cts.IsCancellationRequested);

Simulator: WaitAsync stops waiting, not working

task.WaitAsync(TimeSpan.FromSeconds(3)) throws a TimeoutException after 3 seconds, but the underlying task keeps running. Run it, then turn on “also pass the token”.

HttpClient: timeout or cancel?

Both look like a TaskCanceledException. On .NET 5 and later, an HttpClient.Timeout (default 100 seconds) puts a TimeoutException in InnerException, so you can tell them apart:

try
{
    return await http.GetFromJsonAsync<Forecast>("/forecast", ct);
}
catch (TaskCanceledException ex) when (ex.InnerException is TimeoutException)
{
    logger.LogWarning("Weather API timed out");     // HttpClient.Timeout fired
    return Forecast.Unavailable;
}
catch (OperationCanceledException) when (ct.IsCancellationRequested)
{
    throw;                                           // our caller canceled: just stop
}

Cancellation is reported with exceptions, but it is not an error. Knowing how it travels through tasks avoids noisy logs and wrong HTTP status codes.

Exception
 └─ SystemException
     └─ OperationCanceledException      // catch THIS one
         └─ TaskCanceledException       // Task.Delay, HttpClient, awaited canceled tasks

Patterns for catching

// ✔ Only treat it as "canceled" if OUR token asked for it
try
{
    await ProcessAsync(order, ct);
}
catch (OperationCanceledException) when (ct.IsCancellationRequested)
{
    logger.LogInformation("Order {Id} processing canceled", order.Id);
    throw;            // usually rethrow so callers know it did not complete
}

// ✔ When you catch everything, let cancellation pass through first
try { await ProcessAsync(order, ct); }
catch (OperationCanceledException) { throw; }
catch (Exception ex)
{
    logger.LogError(ex, "Order {Id} failed", order.Id);
}

// ✔ Task.WhenAll: canceled if any task was canceled and none faulted
try { await Task.WhenAll(tasks); }
catch (OperationCanceledException) { /* all-or-nothing cancel */ }

// ✘ .Wait() / .Result wrap it: AggregateException -> TaskCanceledException

Task.Run(work, token): what the token actually does

The token passed to Task.Run only stops the task from starting if it is already canceled. Once the delegate runs, nothing stops it unless the delegate itself observes the token. It also lets the task end as Canceled (instead of Faulted) when the delegate throws an OperationCanceledException for that same token.

await Task.Run(() =>
{
    foreach (var tile in tiles)
    {
        ct.ThrowIfCancellationRequested();   // ← this is what really stops it
        Render(tile);
    }
}, ct);                                       // ← this only prevents a late start

Every request gets its own token. Add a CancellationToken parameter to a controller action or a minimal API handler and ASP.NET Core binds it to HttpContext.RequestAborted, which is canceled when the client disconnects.

app.MapGet("/reports/{id:int}", async (int id, ReportService svc, CancellationToken ct) =>
{
    var report = await svc.BuildAsync(id, ct);
    return Results.Ok(report);
});

public async Task<Report> BuildAsync(int id, CancellationToken ct)
{
    var rows = await _db.Sales
        .Where(s => s.ReportId == id)
        .ToListAsync(ct);

    var rates = await _http.GetFromJsonAsync<Rates>("/fx/today", ct);

    ct.ThrowIfCancellationRequested();
    return Compose(rows, rates);
}

Controllers work exactly the same way

[HttpGet("{id:int}")]
public async Task<ActionResult<Report>> Get(int id, CancellationToken cancellationToken)
    => await _reports.BuildAsync(id, cancellationToken);   // bound to RequestAborted

Server-side request timeouts .NET 8+

The request timeouts middleware cancels RequestAborted when an endpoint runs too long, so the same token handles both “client left” and “we gave up”. By default it answers with 504. Timeouts are not enforced while you are debugging.

builder.Services.AddRequestTimeouts(o =>
    o.DefaultPolicy = new RequestTimeoutPolicy { Timeout = TimeSpan.FromSeconds(10) });

app.UseRequestTimeouts();

app.MapGet("/slow", async (CancellationToken ct) => { /* ... */ })
   .WithRequestTimeout(TimeSpan.FromSeconds(2));

The point of no return

Cancellation must never leave things half done. Once you have charged the card, finish the bookkeeping even if the client disconnects:

public async Task<IResult> Checkout(Cart cart, CancellationToken ct)
{
    var quote = await _pricing.QuoteAsync(cart, ct);      // safe to cancel
    await _inventory.ReserveAsync(cart, ct);              // safe: reservation expires

    var payment = await _payments.ChargeAsync(quote, CancellationToken.None);
    // ── point of no return: money moved, we MUST record it ──
    _db.Orders.Add(Order.From(cart, payment));
    await _db.SaveChangesAsync(CancellationToken.None);

    return Results.Ok(payment.Receipt);
}

More real-world cases

private CancellationTokenSource? _searchCts;

public async Task OnQueryChangedAsync(string q)
{
    if (_searchCts is not null)
    {
        await _searchCts.CancelAsync();
        _searchCts.Dispose();
    }
    _searchCts = new CancellationTokenSource();
    var ct = _searchCts.Token;
    try
    {
        await Task.Delay(250, ct);                       // debounce
        Results = await _api.SearchAsync(q, ct);
    }
    catch (OperationCanceledException) { /* superseded */ }
}

app.MapGet("/api/profile", async (IHttpClientFactory f, CancellationToken ct) =>
{
    var client = f.CreateClient("users");
    using var resp = await client.GetAsync("/me", HttpCompletionOption.ResponseHeadersRead, ct);
    return Results.Stream(await resp.Content.ReadAsStreamAsync(ct), "application/json");
});

var total = await db.Orders
    .Where(o => o.Year == year)
    .SumAsync(o => o.Total, ct);

var rows = await conn.QueryAsync<Row>(
    new CommandDefinition(sql, args, cancellationToken: ct));

app.MapPost("/signup", async (User u, IBackgroundQueue q, CancellationToken ct) =>
{
    await q.EnqueueAsync(new SendWelcomeEmail(u.Email), ct); // quick hand-off
    return Results.Accepted();
});

public override async Task<Reply> Get(Req r, ServerCallContext context)
    => await _svc.GetAsync(r.Id, context.CancellationToken);

catch (OperationCanceledException) when (ctx.RequestAborted.IsCancellationRequested)
{
    logger.LogDebug("Client aborted {Path}", ctx.Request.Path);
    ctx.Response.StatusCode = 499;
}

A BackgroundService gets a stoppingToken that the host cancels when the app shuts down. Your job: notice it, finish the current unit of work, and exit before the host stops waiting.

public sealed class OrderConsumer(Channel<Order> queue, IServiceScopeFactory scopes,
                                  ILogger<OrderConsumer> log) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var order in queue.Reader.ReadAllAsync(stoppingToken))
        {
            await using var scope = scopes.CreateAsyncScope();
            var handler = scope.ServiceProvider.GetRequiredService<OrderHandler>();
            try
            {
                await handler.HandleAsync(order, stoppingToken);
            }
            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
            {
                log.LogInformation("Shutting down; order {Id} will be retried", order.Id);
                break;
            }
            catch (Exception ex)
            {
                log.LogError(ex, "Order {Id} failed", order.Id);   // keep the service alive
            }
        }
    }
}

Simulator: will your cleanup make it in time?

When the host stops (Ctrl+C, SIGTERM from Docker or Kubernetes), it cancels stoppingToken and then waits up to HostOptions.ShutdownTimeout (default 30 seconds) for services to finish.

builder.Services.Configure<HostOptions>(o =>
{
    o.ShutdownTimeout = TimeSpan.FromSeconds(25);  // keep below Kubernetes' 30 s grace period
    o.ServicesStopConcurrently = true;             // .NET 8+: stop services in parallel
});

protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
    using var timer = new PeriodicTimer(TimeSpan.FromMinutes(5));
    try
    {
        do
        {
            await RefreshCacheAsync(stoppingToken);
        }
        while (await timer.WaitForNextTickAsync(stoppingToken));
    }
    catch (OperationCanceledException) { /* normal shutdown */ }
}

More real-world cases

When many operations run at once, cancellation has to stop the ones in flight and prevent new ones from starting.

Simulator: Parallel.ForEachAsync

18 thumbnails, processed with a limited degree of parallelism. Cancel part-way, or make one item fail: the loop cancels the token it gave every other item.

var options = new ParallelOptions
{
    MaxDegreeOfParallelism = 3,
    CancellationToken = cts.Token          // stops scheduling new items
};

await Parallel.ForEachAsync(images, options, async (image, ct) =>
{
    // ct is canceled if cts is canceled OR another item throws
    var bytes = await blob.DownloadAsync(image.Path, ct);
    await blob.UploadAsync(image.ThumbPath, Resize(bytes), ct);
});

Simulator: cancelling an IAsyncEnumerable<T>

With await foreach (… in Stream().WithCancellation(ct)) the token only reaches your iterator if its parameter has [EnumeratorCancellation]. Without it the compiler warns (CS8425) and the token is silently ignored.

More patterns

using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
var tasks = shards.Select(async s =>
{
    try { return await QueryShardAsync(s, cts.Token); }
    catch { await cts.CancelAsync(); throw; }   // stop siblings early
});
var results = await Task.WhenAll(tasks);

for (int attempt = 1; ; attempt++)
{
    try { return await CallAsync(ct); }
    catch (HttpRequestException) when (attempt < 5)
    {
        await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)), ct);
    }
}

await channel.Writer.WriteAsync(item, ct);           // waits if full
await foreach (var x in channel.Reader.ReadAllAsync(ct))
    await HandleAsync(x, ct);

app.MapGet("/events", (EventStore s, CancellationToken ct) => s.ReadAllAsync(ct));

await _gate.WaitAsync(ct);          // waiting in line is cancellable
try { await CallRateLimitedApiAsync(ct); }
finally { _gate.Release(); }

A simplified model of what the runtime does. The real source is more optimized (lock-free fast paths, pooled nodes), but the behaviour is the same.

var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;
CancellationToken copy = token;

CancellationTokenRegistration reg =
    token.Register(() => socket.Abort());

bool before = token.IsCancellationRequested;

cts.Cancel();

bool after = copy.IsCancellationRequested;

reg.Dispose();
cts.Dispose();

var none = CancellationToken.None;
none.Register(() => Never());

The mistakes that show up in real code reviews. Pick one to compare the broken version with the fix.