Skip to content

Add documentation for synchronous access to asynchronous operations #47735

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Aug 5, 2025

This PR addresses the common scenario where developers need to call asynchronous methods but cannot use await throughout their call stack. This situation often occurs in legacy codebases or when integrating async methods into synchronous APIs.

The new section "Synchronous access to asynchronous operations" provides practical guidance on:

  • GetAwaiter().GetResult() - The preferred approach when blocking is unavoidable, as it preserves original exceptions without wrapping them in AggregateException
  • Task.Run wrapper pattern - For complex scenarios where isolating async work on a thread pool thread can help avoid deadlocks
  • Wait() and Result - Documented as discouraged approaches due to poor exception handling and higher deadlock risk

The documentation includes:

  • Clear warnings about deadlock risks and performance impacts
  • Code examples for each approach
  • Links to Stephen Toub's authoritative blog post on sync wrappers
  • Appropriate emphasis that async/await throughout the call stack remains the preferred solution

This enhancement follows the guidance from @stephentoub and @BillWagner to provide practical options while keeping "dangerous" patterns appropriately cautioned with clear warnings about their risks.

Fixes #37040.


💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.


Internal previews

📄 File 🔗 Preview link
docs/csharp/asynchronous-programming/async-scenarios.md docs/csharp/asynchronous-programming/async-scenarios

Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com>
@Copilot Copilot AI changed the title [WIP] How to wait Tasks when unable to await? Add documentation for synchronous access to asynchronous operations Aug 5, 2025
Copilot finished work on behalf of BillWagner August 5, 2025 17:38
@Copilot Copilot AI requested a review from BillWagner August 5, 2025 17:38
@dotnet-policy-service dotnet-policy-service bot added the okr-quality Content-quality KR: Concerns article defects (bugs), freshness, or build warnings. label Aug 6, 2025
Copy link
Member

@BillWagner BillWagner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good start, I have a few comments.

@BillWagner
Copy link
Member

@copilot address the review comments.

Co-authored-by: BillWagner <493969+BillWagner@users.noreply.github.com>
Copilot finished work on behalf of BillWagner August 6, 2025 18:17
@Copilot Copilot AI requested a review from BillWagner August 6, 2025 18:17
Copy link
Member

@BillWagner BillWagner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is ready for final review.

@BillWagner BillWagner marked this pull request as ready for review August 6, 2025 18:44
@BillWagner BillWagner requested a review from a team as a code owner August 6, 2025 18:44
@BillWagner BillWagner requested a review from adegeo August 6, 2025 18:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
async-task-programming/subsvc dotnet-csharp/svc okr-quality Content-quality KR: Concerns article defects (bugs), freshness, or build warnings.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

How to wait Tasks when unable to await?
2 participants