Thanks for assigning this issue to me. I'm starting to work on it and will keep this PR's description up to date as I form a plan and make progress.

Original issue description:

Hello,

As far as I understand, async/await is just syntactic sugar over the Task function ContinueWith. For instance, if we have a Task t and a function f, then X x = await t; return f(x); is the same as t.ContinueWith((x) => { return f(x.Result); });.

Then instead of comparing synchronous code versus async/await code, I would recommend to compare asynchronous code by ContinueWith to asynchronous code by async/await. In the particular breakfast example of this webpage, we would see 2 almost identical codes, because all async methods have only one or two awaits.

The async/await notation is called "monadic do-notation" in functional programming, and it is most useful when there are 3 or 4 monadic values to combine in a single function. Here that would mean 3 or 4 awaits in a single function, then we would see a big simplification compared to intertwined lambda functions inside ContinueWiths.

Moreover, the discussion of synchronous code might be skipped altogether in this page. The difference between monothread and multithread algorithms has become common these days, people are probably already familiar with them.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 17d27a0d-c072-8c9f-7e31-3de60bee9ae8
• Version Independent ID: e0c09794-e712-19ff-cb9f-12648d60d4f6
• Content: Asynchronous programming in C#
• Content Source: docs/csharp/programming-guide/concepts/async/index.md
• Product: dotnet-csharp
• Technology: csharp-async
• GitHub Login: @BillWagner
• Microsoft Alias: wiwagn

Fixes #21296.

💡 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.