ExecutionContext and SynchronizationContext deep dive by BillWagner · Pull Request #52890 · dotnet/docs

BillWagner · 2026-04-07T18:32:05Z

Contributes to #17714

Create executioncontext-and-synchronizationcontext.md — from "ExecutionContext vs SynchronizationContext." Covers what each context is, what "flow" means, how async/await interacts with both, why SynchronizationContext.Current doesn't flow across awaits. Most popular post (20 reactions), no existing equivalent.
Create synchronizationcontext-and-console-apps.md — from "Await, SynchronizationContext, and Console Apps" parts 1-3. Needs significant update: add async Task Main(), top-level statements, modern .NET runtime behavior.
Add both to TOC after the wrapper articles.

Summary

Describe your changes here.

Fixes #Issue_Number (if available)

Internal previews

📄 File	🔗 Preview link
docs/navigate/advanced-programming/toc.yml	docs/navigate/advanced-programming/toc
docs/standard/asynchronous-programming-patterns/executioncontext-synchronizationcontext.md	ExecutionContext and SynchronizationContext
docs/standard/asynchronous-programming-patterns/synchronizationcontext-console-apps.md	"SynchronizationContext and console apps"

1. Create `executioncontext-and-synchronizationcontext.md` — from "ExecutionContext vs SynchronizationContext." Covers what each context is, what "flow" means, how async/await interacts with both, why `SynchronizationContext.Current` doesn't flow across awaits. *Most popular post (20 reactions), no existing equivalent.* 1. Create `synchronizationcontext-and-console-apps.md` — from "Await, SynchronizationContext, and Console Apps" parts 1-3. **Needs significant update:** add `async Task Main()`, top-level statements, modern .NET runtime behavior. 1. Add both to TOC after the wrapper articles.

Copilot

Pull request overview

This PR adds two new conceptual articles that explain how ExecutionContext and SynchronizationContext relate to async/await, and how console apps behave (and how to build a single-threaded pump when you need thread affinity).

Changes:

Add executioncontext-synchronizationcontext.md with runnable C# and Visual Basic snippets.
Add synchronizationcontext-console-apps.md including an AsyncPump-style implementation and snippets.
Add both new articles to the advanced programming navigation TOC.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 17 comments.

Show a summary per file

File	Description
docs/standard/asynchronous-programming-patterns/executioncontext-synchronizationcontext.md	New conceptual article explaining both contexts, flow, and `await` interactions.
docs/standard/asynchronous-programming-patterns/snippets/executioncontext-synchronizationcontext/csharp/Program.cs	C# runnable snippet backing the ExecutionContext/SynchronizationContext article.
docs/standard/asynchronous-programming-patterns/snippets/executioncontext-synchronizationcontext/csharp/ExecutionContextAndSyncContext.csproj	C# project for building/running the snippet.
docs/standard/asynchronous-programming-patterns/snippets/executioncontext-synchronizationcontext/vb/Program.vb	Visual Basic runnable snippet backing the article.
docs/standard/asynchronous-programming-patterns/snippets/executioncontext-synchronizationcontext/vb/ExecutionContextAndSyncContext.vbproj	Visual Basic project for building/running the snippet.
docs/standard/asynchronous-programming-patterns/synchronizationcontext-console-apps.md	New article explaining console default behavior and a custom single-threaded context/pump.
docs/standard/asynchronous-programming-patterns/snippets/synchronizationcontext-console-apps/csharp/Program.cs	C# runnable snippet implementing the custom context and pump.
docs/standard/asynchronous-programming-patterns/snippets/synchronizationcontext-console-apps/csharp/SyncContextConsoleApps.csproj	C# project for building/running the snippet.
docs/standard/asynchronous-programming-patterns/snippets/synchronizationcontext-console-apps/vb/Program.vb	Visual Basic runnable snippet implementing the custom context and pump.
docs/standard/asynchronous-programming-patterns/snippets/synchronizationcontext-console-apps/vb/SyncContextConsoleApps.vbproj	Visual Basic project for building/running the snippet.
docs/navigate/advanced-programming/toc.yml	Adds both new articles to the navigation TOC.

...chronous-programming-patterns/snippets/synchronizationcontext-console-apps/csharp/Program.cs

docs/standard/asynchronous-programming-patterns/synchronizationcontext-console-apps.md

docs/standard/asynchronous-programming-patterns/executioncontext-synchronizationcontext.md

...nous-programming-patterns/snippets/executioncontext-synchronizationcontext/csharp/Program.cs

...chronous-programming-patterns/snippets/executioncontext-synchronizationcontext/vb/Program.vb

docs/standard/asynchronous-programming-patterns/synchronizationcontext-console-apps.md

docs/standard/asynchronous-programming-patterns/executioncontext-synchronizationcontext.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Fix feedback, and one final edit pass

…nto async-aweigh-2

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 8 comments.

...chronous-programming-patterns/snippets/executioncontext-synchronizationcontext/vb/Program.vb

...nous-programming-patterns/snippets/executioncontext-synchronizationcontext/csharp/Program.cs

...chronous-programming-patterns/snippets/executioncontext-synchronizationcontext/vb/Program.vb

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

BillWagner · 2026-04-10T18:30:46Z

@adegeo This one is ready for final review.

gewarren · 2026-04-10T20:15:47Z

docs/standard/asynchronous-programming-patterns/synchronizationcontext-console-apps.md

+
+### The custom context
+
+The context uses a <xref:System.Collections.Concurrent.BlockingCollection%601> to coordinate producers (the async continuations) and a consumer (the pumping loop):


Suggested change

The context uses a <xref:System.Collections.Concurrent.BlockingCollection%601> to coordinate producers (the async continuations) and a consumer (the pumping loop):

The context uses a <xref:System.Collections.Concurrent.BlockingCollection`1> to coordinate producers (the async continuations) and a consumer (the pumping loop):

gewarren · 2026-04-10T20:16:48Z

docs/standard/asynchronous-programming-patterns/synchronizationcontext-console-apps.md

+
+## Practical considerations
+
+- **Deadlock risk**: If code running inside `AsyncPump.Run` blocks synchronously (for example, by calling `.Result` or `.Wait()` on a task whose continuation must post back to the pump), the pump thread can't process that continuation. The result is a deadlock. The same problem described in [Synchronous wrappers for asynchronous methods](synchronous-wrappers-for-asynchronous-methods.md).


Suggested change

- **Deadlock risk**: If code running inside `AsyncPump.Run` blocks synchronously (for example, by calling `.Result` or `.Wait()` on a task whose continuation must post back to the pump), the pump thread can't process that continuation. The result is a deadlock. The same problem described in [Synchronous wrappers for asynchronous methods](synchronous-wrappers-for-asynchronous-methods.md).

- **Deadlock risk**: If code running inside `AsyncPump.Run` blocks synchronously (for example, by calling `.Result` or `.Wait()` on a task whose continuation must post back to the pump), the pump thread can't process that continuation. The result is a deadlock. The same problem is described in [Synchronous wrappers for asynchronous methods](synchronous-wrappers-for-asynchronous-methods.md).

gewarren · 2026-04-10T20:17:43Z

docs/standard/asynchronous-programming-patterns/executioncontext-synchronizationcontext.md

+---
+# ExecutionContext and SynchronizationContext
+
+When you work with `async` and `await`, two context types play important but very different roles: <xref:System.Threading.ExecutionContext> and <xref:System.Threading.SynchronizationContext>. You learn what each one does, how each one interacts with `async`/`await`, and why <xref:System.Threading.SynchronizationContext.Current?displayProperty=nameWithType> doesn't flow across await points.


Is use of async/await appropriate for VB devs?

gewarren · 2026-04-10T20:19:08Z

docs/standard/asynchronous-programming-patterns/executioncontext-synchronizationcontext.md

+:::code language="csharp" source="./snippets/executioncontext-synchronizationcontext/csharp/Program.cs" id="SyncContextUsage":::
+:::code language="vb" source="./snippets/executioncontext-synchronizationcontext/vb/Program.vb" id="SyncContextUsage":::
+
+### Capturing a SynchronizationContext


Suggested change

### Capturing a SynchronizationContext

### Capture a SynchronizationContext

gewarren · 2026-04-10T20:24:42Z

docs/standard/asynchronous-programming-patterns/executioncontext-synchronizationcontext.md

+
+### Task awaiters capture SynchronizationContext
+
+The awaiters for <xref:System.Threading.Tasks.Task> and <xref:System.Threading.Tasks.Task%601> include support for <xref:System.Threading.SynchronizationContext>. The async method builders don't include this support.


Suggested change

The awaiters for <xref:System.Threading.Tasks.Task> and <xref:System.Threading.Tasks.Task%601> include support for <xref:System.Threading.SynchronizationContext>. The async method builders don't include this support.

The awaiters for <xref:System.Threading.Tasks.Task> and <xref:System.Threading.Tasks.Task`1> include support for <xref:System.Threading.SynchronizationContext>. The async method builders don't include this support.

dotnetrepoman bot added this to the April 2026 milestone Apr 7, 2026

dotnet-policy-service bot added the dotnet-fundamentals/svc label Apr 7, 2026

BillWagner added 2 commits April 8, 2026 09:26

fix build suggestions

17f8935

BillWagner force-pushed the async-aweigh-2 branch from 74e85ff to 17f8935 Compare April 8, 2026 13:26

BillWagner marked this pull request as ready for review April 8, 2026 13:39

BillWagner requested a review from a team as a code owner April 8, 2026 13:39

Copilot AI review requested due to automatic review settings April 8, 2026 13:39

Copilot started reviewing on behalf of BillWagner April 8, 2026 13:40 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

BillWagner and others added 6 commits April 8, 2026 09:49

Apply suggestions from code review

4114bb1

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Full edit pass

5f5f980

Fix feedback, and one final edit pass

Merge branch 'async-aweigh-2' of https://github.com/BillWagner/docs i…

15de870

…nto async-aweigh-2

continue the merge

2253026

Final edit pass

89fe908

fix build issues

33bc2e4

BillWagner requested review from adegeo and Copilot April 8, 2026 18:39

Copilot started reviewing on behalf of BillWagner April 8, 2026 20:57 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

BillWagner and others added 2 commits April 10, 2026 13:53

Apply suggestions from code review

2af0cbd

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Fix samles.

3fda2df

gewarren approved these changes Apr 10, 2026

View reviewed changes


		### The custom context

		The context uses a <xref:System.Collections.Concurrent.BlockingCollection%601> to coordinate producers (the async continuations) and a consumer (the pumping loop):


		## Practical considerations

		- Deadlock risk: If code running inside `AsyncPump.Run` blocks synchronously (for example, by calling `.Result` or `.Wait()` on a task whose continuation must post back to the pump), the pump thread can't process that continuation. The result is a deadlock. The same problem described in [Synchronous wrappers for asynchronous methods](synchronous-wrappers-for-asynchronous-methods.md).

	### Capturing a SynchronizationContext
	### Capture a SynchronizationContext


		### Task awaiters capture SynchronizationContext

		The awaiters for <xref:System.Threading.Tasks.Task> and <xref:System.Threading.Tasks.Task%601> include support for <xref:System.Threading.SynchronizationContext>. The async method builders don't include this support.

Conversation

BillWagner commented Apr 7, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Internal previews

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BillWagner commented Apr 10, 2026

Uh oh!

gewarren Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

gewarren Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

gewarren Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

gewarren Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

gewarren Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

BillWagner commented Apr 7, 2026 •

edited by github-actions bot

Loading