Cancellation

Work does not always need to finish. Someone closes the browser tab before the report they asked for is built. A nightly import is still running when the maintenance window closes. A price lookup has taken eight seconds and the caller has already stopped caring.

C# has one mechanism for all of these. A CancellationToken is a small value you pass into an operation. The operation looks at it. If the token says a cancellation has been requested, the operation stops and says so.

The important word is looks. A token does not stop anything by itself. It carries a message, and code that never reads the message runs happily to the end.

public class OrderImportService
{
    private readonly HttpClient _httpClient;
    private readonly IOrderStore _orders;

    public OrderImportService(HttpClient httpClient, IOrderStore orders)
    {
        _httpClient = httpClient;
        _orders = orders;
    }

    public async Task<int> ImportAsync(
        IReadOnlyList<string> supplierIds,
        CancellationToken cancellationToken)
    {
        int imported = 0;

        foreach (string supplierId in supplierIds)
        {
            // Check before taking on another unit of work.
            cancellationToken.ThrowIfCancellationRequested();

            using HttpResponseMessage response = await _httpClient.GetAsync(
                $"suppliers/{supplierId}/orders",
                cancellationToken);

            response.EnsureSuccessStatusCode();

            List<Order>? batch = await response.Content
                .ReadFromJsonAsync<List<Order>>(cancellationToken);

            if (batch is null)
            {
                continue;
            }

            await _orders.SaveManyAsync(batch, cancellationToken);
            imported += batch.Count;
        }

        return imported;
    }
}

• The token is an ordinary parameter. Convention puts it last and names it cancellationToken, which is worth following because tooling and reviewers both look for it there.
• ThrowIfCancellationRequested is the loop's check. It does nothing when no cancellation has been asked for, and throws OperationCanceledException when one has. One check per supplier means the import stops within roughly one supplier's worth of work instead of at the very end.
• Passing the token into GetAsync matters more than it appears to. Without it, a cancellation during a slow network call goes unnoticed until the call returns on its own, which might be thirty seconds later. With it, the request itself is abandoned.
• The token also goes into ReadFromJsonAsync and into SaveManyAsync. Anything that accepts a token should be given one. A single method in the chain that drops it becomes the place where cancellation quietly stops working.
• using on the response means it is disposed when the method exits, including when cancellation throws on the next iteration. Cancellation is an exception path, so your resource cleanup has to hold up on that path too.
• The count is returned only on the success path. If cancellation throws, the caller gets no number, which is honest — the import did not finish.

[HttpPost("imports")]
public async Task<IActionResult> RunImport(
    [FromBody] ImportRequest request,
    CancellationToken cancellationToken)
{
    // Stop if the caller disconnects, or after 30 seconds, whichever comes first.
    using CancellationTokenSource budget =
        CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);

    budget.CancelAfter(TimeSpan.FromSeconds(30));

    try
    {
        int imported = await _import.ImportAsync(request.SupplierIds, budget.Token);

        return Ok(new ImportResult(imported));
    }
    catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
    {
        // The client gave up. Nobody is waiting for a response.
        _logger.LogInformation("Import abandoned by the caller.");

        return new StatusCodeResult(499);
    }
    catch (OperationCanceledException)
    {
        // Our own budget ran out. That is worth knowing about.
        _logger.LogWarning("Import exceeded its 30 second budget and was stopped.");

        return StatusCode(StatusCodes.Status504GatewayTimeout);
    }
}

• The action declares a CancellationToken parameter, so ASP.NET Core supplies the token tied to the client connection. No attribute and no service lookup is needed.
• CreateLinkedTokenSource wraps that token in a new source. Cancelling the connection cancels budget.Token, and so does CancelAfter once thirty seconds pass. ImportAsync only has to watch one token.
• Both catch blocks are for the same exception type, separated by a when filter. That filter is how you tell a client who left apart from a deadline you imposed on yourself.
• Neither case is a bug, and that is the point of writing them separately. OperationCanceledException here means the system did what it was told. Logging it at error level teaches everyone to ignore your error log.
• The 499 status code is a convention for "client closed the request", not part of the HTTP standard. It costs nothing since the client has gone, and it keeps these out of your 500 count.
• Disposing the source matters. A linked source holds a registration on the token it was built from, and CancelAfter starts a timer. Both are released by the using declaration.