Building resilient streaming endpoints with CancellationToken records

Streaming responses have moved from a niche feature into a daily workhorse for .NET teams. Whether you are pushing market data to a dashboard in Sydney, feeding sensor readings into a machine learning pipeline in Melbourne, or signalling progress from a long-running job to a browser in Brisbane, the standard pattern rarely looks like a one-shot return any more. Modern applications assume that bytes flow in chunks over time, that clients connect and disconnect unpredictably, and that networks drop in the middle of a transaction.

This shift has put cancellation under the spotlight. A streaming endpoint that never times out or never honours a client disconnect can leak worker threads, hold buffers in memory, and chew through bandwidth on a regional NBN link long after the requester has moved on. In Australia, where workloads are often stretched between capital cities and remote sites with intermittent connectivity, the cost of poor cancellation hygiene grows quickly.

A clean way to manage this in C# 9 and later is to combine IAsyncEnumerable<T> with a small, purpose-built record that packages a CancellationToken together with the metadata a streaming endpoint actually needs. The pattern keeps the async stream idiomatic, gives the host a single object to inspect, and lets background workers cooperate without spaghetti logic.

Why streaming endpoints need cooperative cancellation

Cooperative cancellation is the only kind that actually works in managed code. The runtime cannot just yank a thread out from under a Stream.CopyToAsync call without risking torn buffers and unhandled exceptions. The CancellationToken exists so that the producing code can observe a signal, stop what it is doing cleanly, and free the resources it had reserved.

In a streaming endpoint, the implications multiply. A controller method returning IAsyncEnumerable<T> is technically a state machine that the framework pulls on a slice at a time. Each yield is an opportunity to bail out, but only if the developer remembers to ask token.ThrowIfCancellationRequested() inside the loop. Without those checks, an upstream closed socket just sits idle while the database keeps polling, and the GC keeps allocating.

That setup matters in Australian contexts where latency is not always predictable. A user querying ASIC business registry data from a mobile connection on the Yorke Peninsula is not the same as someone parked at a desk in Parramatta. Endpoints that assume a flat latency profile tend to over-fetch on slower links, which in turn means more time sitting in memory waiting to be cancelled.

Anatomy of IAsyncEnumerable and token flow

IAsyncEnumerable<T> arrived with C# 8 and quietly raised the floor for asynchronous programming. The interface exposes a single GetAsyncEnumerator method that returns an IAsyncEnumerator<T>, which in turn supports MoveNextAsync and the familiar Current property. Because MoveNextAsync returns a ValueTask<bool>, callers can hang tight without blocking a thread, and the producer can yield values lazily.

The interface includes a default CancellationToken parameter on GetAsyncEnumerator. When a caller passes a token through, the producer is expected to honour it at every await point. ASP.NET Core pushes its request-aborted token through automatically when the framework recognises the parameter, so applications get cancellation for free when the response stream is flushed and the client disconnects.

The trick is layering business-level cancellation on top of that. A streaming endpoint that exports cheque clearance records for an ATO reconciliation job should not only stop when the client goes away, it should stop when an internal deadline fires, when a downstream dependency becomes unhealthy, or when an administrator manually pauses the stream. Each of those triggers should be a CancellationTokenSource that gets composed into a single token the loop can observe.

Designing a CancellationTokenRecord wrapper

A CancellationTokenRecord is a natural fit for the language feature with the same name. In C# 9 or later, declaring a positional record gives you value equality, immutability, and a clean syntax for moving the structure around. The wrapper typically bundles a token with the reason for cancellation, a deadline expressed in Australian Eastern Standard Time for clarity, and a correlation identifier that ends up in the application log.

public record CancellationTokenRecord(
    CancellationToken Token,
    string Reason,
    DateTimeOffset DeadlineLocal,
    string CorrelationId);

The real benefit surfaces when the helper exposes a few small operations. A WithReason(string) factory method returns a new record when circumstances change. A combined static method accepts multiple sources and produces a single linked token plus a record that aggregates the originating reasons. That single object can then travel into repositories, background services, and controller actions without anyone needing to chase three different parameters.

In Australian teams, the deadline is usually expressed in Australia/Sydney time even when the server is hosted elsewhere, because that is the timezone the operations team reads clocks in. Building the convention into the record saves a lot of small but confusing bugs where deadlines are silently off by a few hours, the sort of subtle drift that any code reviewer in Melbourne would likely catch on a Wednesday afternoon.

Wiring the record into ASP.NET Core endpoints

Once the record exists, the controller method becomes pleasantly small. The action binds the record through dependency injection, hands it into the repository, and yields values as they arrive. ASP.NET Core links the framework token with the record token using CancellationTokenSource.CreateLinkedTokenSource, so any of the triggers tearing down the connection also tears down the response.

[HttpGet("stream")]
public async IAsyncEnumerable<TradeEvent> StreamAsync(
    [FromServices] CancellationTokenRecord record,
    [EnumeratorCancellation] CancellationToken frameworkToken)
{
    using var linked = CancellationTokenSource
        .CreateLinkedTokenSource(record.Token, frameworkToken);

    await foreach (var trade in _repository
        .WatchTradesAsync(linked.Token, record.Reason))
    {
        yield return trade;
    }
}

The [EnumeratorCancellation] attribute is the small detail that ties everything together. Without it, the framework cannot propagate its own token into the async iterator, and the only signal your loop sees is the business-level one. With it, a slow consumer closing the tab and an admin pressing the emergency stop button both result in the same clean unwind, the same log entry, and the same release of upstream sockets.

This is particularly handy for SignalR hubs running across regions. A hub group hosted in Sydney serving subscribers in Perth can use the record to attach a per-connection timeout, log when a connection dies, and propagate a deadline down to the database call so the cancellation actually reaches the query plan.

Comparing cancellation approaches across real-world scenarios

Not every project needs a record. A quick look at the choices helps to pick the right tool for the right job.

The record approach usually pays for itself once an endpoint crosses into anything resembling production. Compliance audits tend to ask precise questions about who cancelled what and when, and the metadata flowing through the wrapper answers them without anyone needing to instrument the logs after the fact. The discipline also makes integration tests easier, since the cancellation path can be exercised deliberately rather than discovered only when a flaky CI build finally drops a connection at the wrong moment.

Practical habits for day-to-day streaming code

• Always thread a CancellationTokenRecord into repository and service methods, even if the immediate call site does not need it, so cancellation is never one layer away from being honoured.
• Set deadlines in Australia/Sydney (or the customer-facing timezone) so application logs and incident timelines line up with operational expectations.
• Log on cancellation with the correlation id from the record, not just the time, so a single trace can be followed end-to-end through application code and infrastructure tooling.
• Avoid buffering full result sets before yielding, emit each item as soon as it arrives and check the token between yields to keep memory flat under load.
• Treat timeout values as configuration rather than constants, especially for endpoints that reach customers outside the capital cities where NBN and enterprise link variability shape the realistic upper bound on stream length.