Cancellation and timeouts

Stop work nobody needs

A user closes the browser tab while the server is still building a 30-second report. A search is superseded by the next keystroke. A dependency hangs and never answers. In each case, continuing the work wastes CPU, database connections and threads. .NET's answer is cooperative cancellation.

The two halves

• CancellationTokenSource — the remote control. Whoever owns it can call Cancel().
• CancellationToken — a read-only signal handed to the work. Code can check it, but can't cancel it.

using var cts = new CancellationTokenSource();
CancellationToken token = cts.Token;
 
Task work = ProcessAsync(token);   // the work receives the token
cts.Cancel();                      // later: request cancellation

Passing tokens through

By convention, async methods take an optional CancellationToken as their last parameter and pass it on to everything they call:

async Task<Report> BuildReportAsync(int year, CancellationToken cancellationToken = default)
{
    var orders = await db.Orders
        .Where(o => o.Year == year)
        .ToListAsync(cancellationToken);                       // EF Core observes it
 
    var rates = await http.GetFromJsonAsync<Rates>(ratesUrl, cancellationToken);   // so does HttpClient
 
    return Summarize(orders, rates);
}

When the token is cancelled, these calls throw OperationCanceledException (often its subclass TaskCanceledException), which unwinds your method.

Checking in your own loops

Cancellation is cooperative — nothing is killed. CPU-bound loops must check:

foreach (var file in files)
{
    cancellationToken.ThrowIfCancellationRequested();   // throws if cancelled
    Process(file);
}

Timeouts

A timeout is just cancellation scheduled in advance:

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));   // or cts.CancelAfter(...)
try
{
    var price = await GetPriceAsync(productId, cts.Token);
}
catch (OperationCanceledException)
{
    Console.WriteLine("The price service took too long");
}
 
// Or, for any task:
var result = await SomeTaskAsync().WaitAsync(TimeSpan.FromSeconds(5));   // throws TimeoutException

Combine a caller's token with your own timeout using a linked source:

using var linked = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
linked.CancelAfter(TimeSpan.FromSeconds(10));
await CallServiceAsync(linked.Token);   // cancelled by the caller OR after 10 s

In ASP.NET Core

Add a CancellationToken parameter to an endpoint and ASP.NET Core fills it with a token that's cancelled when the client disconnects:

app.MapGet("/reports/{year}", async (int year, ReportService reports, CancellationToken ct) =>
    await reports.BuildReportAsync(year, ct));

Try it

Key takeaways

• CancellationTokenSource cancels; the CancellationToken is passed to the work.
• Cancellation is cooperative: pass tokens down and check them in long loops.
• Cancelled operations throw OperationCanceledException.
• Timeouts are scheduled cancellation: new CancellationTokenSource(timeout) or CancelAfter.