Skip to content

Commit 5c6a26c

Browse files
BillWagnerCopilot
BillWagner
and
Copilot
authored
Cancellation patterns (#52996)
* Cancellation patterns Contributes to #17714 1. Create `cancel-non-cancelable-async-operations.md` — from "How do I cancel non-cancelable async operations?" Covers the 3 meanings of cancellation, the `WithCancellation<T>` extension method pattern using `Task.WhenAny`. **Update:** note that many .NET Core streams are now fully cancelable; `NetworkStream` async operations honor tokens. 1. Create `coalescing-cancellation-tokens-from-timeouts.md` — from "Coalescing CancellationTokens from timeouts." Covers combining a user-provided `CancellationToken` with timeout-based tokens using `CancellationTokenSource.CreateLinkedTokenSource`. **Update** for modern API surface. 1. Add both to TOC near existing cancellation content. * fix suggestions * proofread and review pass * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent ad51410 commit 5c6a26c

File tree

11 files changed

+614
-0
lines changed

11 files changed

+614
-0
lines changed

‎docs/navigate/advanced-programming/toc.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@ items:
2424
href: ../../standard/asynchronous-programming-patterns/executioncontext-synchronizationcontext.md
2525
- name: SynchronizationContext and console apps
2626
href: ../../standard/asynchronous-programming-patterns/synchronizationcontext-console-apps.md
27+
- name: Cancel non-cancelable async operations
28+
href: ../../standard/asynchronous-programming-patterns/cancel-non-cancelable-async-operations.md
29+
- name: Coalesce cancellation tokens from timeouts
30+
href: ../../standard/asynchronous-programming-patterns/coalesce-cancellation-tokens-from-timeouts.md
2731
- name: Best practices and troubleshooting
2832
items:
2933
- name: Common async/await bugs

‎docs/standard/asynchronous-programming-patterns/cancel-non-cancelable-async-operations.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
title: "Cancel non-cancelable async operations"
3+
description: Learn practical patterns for cancellation when an async operation doesn't accept a cancellation token, including canceling the wait, canceling the operation, or both.
4+
ms.date: 04/13/2026
5+
ai-usage: ai-assisted
6+
dev_langs:
7+
- "csharp"
8+
- "vb"
9+
helpviewer_keywords:
10+
- "cancellation, async"
11+
- "Task.WhenAny"
12+
- "WithCancellation"
13+
- "CancellationToken"
14+
- "NetworkStream, cancellation"
15+
---
16+
# Cancel non-cancelable async operations
17+
18+
Sometimes you need cancellation, but the operation you're waiting on doesn't accept a <xref:System.Threading.CancellationToken>. In that case, choose the behavior you need:
19+
20+
- Cancel the operation itself.
21+
- Cancel only your wait.
22+
- Cancel both the operation and your wait.
23+
24+
The right choice depends on who owns the operation and what cleanup guarantees you need.
25+
26+
## Understand the three cancellation meanings
27+
28+
When people say, "cancel this async call," they usually mean one of three different things:
29+
30+
- **Cancel the operation.** Signal the operation to stop work.
31+
- **Cancel the wait.** Stop awaiting and continue your workflow, even if the operation still runs.
32+
- **Cancel both.** Request operation cancellation and also stop waiting promptly.
33+
34+
Treat these meanings as separate design decisions. If you mix them, cancellation behavior becomes hard to reason about.
35+
36+
## Prefer token-aware APIs when available
37+
38+
Before you add a wrapper, check whether the API already supports cancellation tokens. Modern .NET APIs have much broader token support than older .NET Framework code. For example, many stream APIs in .NET now support cancellation, and `NetworkStream` async operations honor cancellation tokens.
39+
40+
Use token overloads whenever they exist:
41+
42+
:::code language="csharp" source="./snippets/cancel-non-cancelable-async-operations/csharp/Program.cs" id="PreferTokenAwareApis":::
43+
:::code language="vb" source="./snippets/cancel-non-cancelable-async-operations/vb/Program.vb" id="PreferTokenAwareApis":::
44+
45+
## Cancel only the wait by using `Task.WhenAny`
46+
47+
When an operation doesn't accept a token, cancel your wait by racing the operation against a token-backed task. This pattern often appears as a `WithCancellation` helper:
48+
49+
:::code language="csharp" source="./snippets/cancel-non-cancelable-async-operations/csharp/Program.cs" id="WithCancellation":::
50+
:::code language="vb" source="./snippets/cancel-non-cancelable-async-operations/vb/Program.vb" id="WithCancellation":::
51+
52+
This pattern uses <xref:System.Threading.Tasks.Task.WhenAny*> to return as soon as either task completes.
53+
54+
Use this approach only when it's safe for the original operation to continue in the background.
55+
56+
## Cancel both operation and wait when you own the operation
57+
58+
If you own the operation and it accepts a token, pass the token and still use a cancelable wait when needed:
59+
60+
:::code language="csharp" source="./snippets/cancel-non-cancelable-async-operations/csharp/Program.cs" id="CancelBoth":::
61+
:::code language="vb" source="./snippets/cancel-non-cancelable-async-operations/vb/Program.vb" id="CancelBoth":::
62+
63+
This combination gives responsive cancellation for callers and cooperative shutdown for the underlying work.
64+
65+
## Handle abandoned operations safely
66+
67+
If you cancel only the wait, the original task might later fault. Keep a reference so you can observe completion and log exceptions. Otherwise, you can miss failures and make troubleshooting harder.
68+
69+
:::code language="csharp" source="./snippets/cancel-non-cancelable-async-operations/csharp/Program.cs" id="ObserveLateFault":::
70+
:::code language="vb" source="./snippets/cancel-non-cancelable-async-operations/vb/Program.vb" id="ObserveLateFault":::
71+
72+
## See also
73+
74+
- [Consume the task-based asynchronous pattern](consuming-the-task-based-asynchronous-pattern.md)
75+
- [Task cancellation](../parallel-programming/task-cancellation.md)
76+
- [Cancellation in managed threads](../threading/cancellation-in-managed-threads.md)
77+
- <xref:System.Threading.CancellationToken>
78+
- <xref:System.Threading.Tasks.Task.WhenAny*>

‎docs/standard/asynchronous-programming-patterns/coalesce-cancellation-tokens-from-timeouts.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: "Coalesce cancellation tokens from timeouts"
3+
description: Learn how to combine caller-driven cancellation with timeout-driven cancellation by using linked cancellation token sources in modern .NET.
4+
ms.date: 04/13/2026
5+
ai-usage: ai-assisted
6+
dev_langs:
7+
- "csharp"
8+
- "vb"
9+
helpviewer_keywords:
10+
- "CancellationTokenSource.CreateLinkedTokenSource"
11+
- "timeout, cancellation"
12+
- "linked cancellation token"
13+
- "CancelAfter"
14+
- "WaitAsync"
15+
---
16+
# Coalesce cancellation tokens from timeouts
17+
18+
Many APIs need two cancellation triggers:
19+
20+
- A caller-provided <xref:System.Threading.CancellationToken>.
21+
- A timeout enforced by your component.
22+
23+
Use <xref:System.Threading.CancellationTokenSource.CreateLinkedTokenSource*> to merge both into a single token that your async work can consume.
24+
25+
## Use a linked token source for caller token plus timeout
26+
27+
Create a timeout <xref:System.Threading.CancellationTokenSource>, link it with the caller token, and pass the linked token to the operation:
28+
29+
:::code language="csharp" source="./snippets/coalescing-cancellation-tokens-from-timeouts/csharp/Program.cs" id="LinkedTokenBasic":::
30+
:::code language="vb" source="./snippets/coalescing-cancellation-tokens-from-timeouts/vb/Program.vb" id="LinkedTokenBasic":::
31+
32+
Dispose both `CancellationTokenSource` instances after the operation completes so registrations and timers are released promptly.
33+
34+
## Encapsulate linking in a helper
35+
36+
Wrap linking logic in a helper method when several call sites need the same policy:
37+
38+
:::code language="csharp" source="./snippets/coalescing-cancellation-tokens-from-timeouts/csharp/Program.cs" id="LinkedTokenHelper":::
39+
:::code language="vb" source="./snippets/coalescing-cancellation-tokens-from-timeouts/vb/Program.vb" id="LinkedTokenHelper":::
40+
41+
A helper keeps timeout behavior consistent and avoids duplicate disposal bugs.
42+
43+
## Choose the right timeout model
44+
45+
Linked tokens are useful when the callee accepts a token and you need one unified cancellation path. In modern .NET, you also have these alternatives:
46+
47+
- Use <xref:System.Threading.CancellationTokenSource.CancelAfter*> to enforce timeouts on a `CancellationTokenSource` you own.
48+
- Use <xref:System.Threading.Tasks.Task.WaitAsync*> when you want to time out the wait without canceling underlying work.
49+
50+
This example shows a `WaitAsync` timeout for "cancel wait only" semantics:
51+
52+
:::code language="csharp" source="./snippets/coalescing-cancellation-tokens-from-timeouts/csharp/Program.cs" id="WaitAsyncAlternative":::
53+
:::code language="vb" source="./snippets/coalescing-cancellation-tokens-from-timeouts/vb/Program.vb" id="WaitAsyncAlternative":::
54+
55+
## Summary
56+
57+
Use linked tokens when you need to combine caller intent and infrastructure timeouts into one cancellation contract. Keep ownership and disposal rules explicit:
58+
59+
- If your component creates a `CancellationTokenSource`, your component disposes it.
60+
- If callers pass a token, never dispose the caller's token source.
61+
- If an operation doesn't accept tokens, use wait-cancellation patterns instead of linked tokens.
62+
63+
## See also
64+
65+
- [Cancel non-cancelable async operations](cancel-non-cancelable-async-operations.md)
66+
- [Task cancellation](../parallel-programming/task-cancellation.md)
67+
- [Cancellation in managed threads](../threading/cancellation-in-managed-threads.md)
68+
- <xref:System.Threading.CancellationTokenSource.CreateLinkedTokenSource*>
69+
- <xref:System.Threading.CancellationTokenSource.CancelAfter*>
70+
- <xref:System.Threading.Tasks.Task.WaitAsync*>

‎docs/standard/asynchronous-programming-patterns/snippets/cancel-non-cancelable-async-operations/csharp/CancelNonCancelableAsyncOperations.csproj‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>net10.0</TargetFramework>
6+
<ImplicitUsings>enable</ImplicitUsings>
7+
<Nullable>enable</Nullable>
8+
</PropertyGroup>
9+
10+
</Project>

‎docs/standard/asynchronous-programming-patterns/snippets/cancel-non-cancelable-async-operations/csharp/Program.cs‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
using System.Net.Sockets;
2+
3+
// <PreferTokenAwareApis>
4+
public static class StreamExamples
5+
{
6+
public static async Task<int> ReadOnceAsync(
7+
NetworkStream stream,
8+
byte[] buffer,
9+
CancellationToken cancellationToken)
10+
{
11+
return await stream.ReadAsync(
12+
buffer.AsMemory(0, buffer.Length),
13+
cancellationToken);
14+
}
15+
}
16+
// </PreferTokenAwareApis>
17+
18+
// <WithCancellation>
19+
public static class TaskCancellationExtensions
20+
{
21+
public static async Task<T> WithCancellation<T>(
22+
this Task<T> task,
23+
CancellationToken cancellationToken)
24+
{
25+
if (task.IsCompleted)
26+
return await task.ConfigureAwait(false);
27+
28+
var cancellationTaskSource = new TaskCompletionSource<bool>(
29+
TaskCreationOptions.RunContinuationsAsynchronously);
30+
31+
using var registration = cancellationToken.Register(
32+
static state =>
33+
((TaskCompletionSource<bool>)state!).TrySetResult(true),
34+
cancellationTaskSource);
35+
36+
Task completed = await Task.WhenAny(task, cancellationTaskSource.Task)
37+
.ConfigureAwait(false);
38+
39+
if (completed != task)
40+
throw new OperationCanceledException(cancellationToken);
41+
42+
return await task.ConfigureAwait(false);
43+
}
44+
}
45+
// </WithCancellation>
46+
47+
// <CancelBoth>
48+
public static class CancelBothDemo
49+
{
50+
public static async Task<string> FetchDataAsync(CancellationToken cancellationToken)
51+
{
52+
await Task.Delay(500, cancellationToken);
53+
return "payload";
54+
}
55+
56+
public static async Task RunAsync()
57+
{
58+
using var cts = new CancellationTokenSource();
59+
cts.CancelAfter(100);
60+
61+
try
62+
{
63+
string payload = await FetchDataAsync(cts.Token)
64+
.WithCancellation(cts.Token);
65+
Console.WriteLine(payload);
66+
}
67+
catch (OperationCanceledException)
68+
{
69+
Console.WriteLine("Canceled operation and wait.");
70+
}
71+
}
72+
}
73+
// </CancelBoth>
74+
75+
// <ObserveLateFault>
76+
public static class ObserveLateFaultDemo
77+
{
78+
private static async Task<int> FaultLaterAsync()
79+
{
80+
await Task.Delay(250);
81+
throw new InvalidOperationException("Background operation failed.");
82+
}
83+
84+
public static async Task RunAsync()
85+
{
86+
Task<int> operation = FaultLaterAsync();
87+
88+
using var cts = new CancellationTokenSource(50);
89+
90+
try
91+
{
92+
await operation.WithCancellation(cts.Token);
93+
}
94+
catch (OperationCanceledException)
95+
{
96+
Console.WriteLine("Stopped waiting; operation still running.");
97+
}
98+
99+
_ = operation.ContinueWith(
100+
t => Console.WriteLine($"Observed late fault: {t.Exception!.InnerException!.Message}"),
101+
TaskContinuationOptions.OnlyOnFaulted);
102+
103+
await Task.Delay(300);
104+
}
105+
}
106+
// </ObserveLateFault>
107+
108+
public class Program
109+
{
110+
public static async Task Main()
111+
{
112+
Console.WriteLine("=== Cancel both operation and wait ===");
113+
await CancelBothDemo.RunAsync();
114+
115+
Console.WriteLine();
116+
Console.WriteLine("=== Cancel wait only and observe late fault ===");
117+
await ObserveLateFaultDemo.RunAsync();
118+
119+
Console.WriteLine();
120+
Console.WriteLine("Done.");
121+
}
122+
}

‎docs/standard/asynchronous-programming-patterns/snippets/cancel-non-cancelable-async-operations/vb/CancelNonCancelableAsyncOperations.vbproj‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<RootNamespace>CancelNonCancelableAsyncOperations</RootNamespace>
6+
<TargetFramework>net10.0</TargetFramework>
7+
</PropertyGroup>
8+
9+
</Project>

0 commit comments

Comments
 (0)