Minecraft-Console-Client/.skills/csharp-best-practices/references/async-source-notes.md

description	metadata
Authority notes and citations for the c# async best practices skill, separating official documentation, expert interpretation, and synthesized guidance.	tags source sources citations authority notes external

Source Notes

Official facts

• Microsoft Learn, "Implementing the Task-based Asynchronous Pattern"
  • https://learn.microsoft.com/en-us/dotnet/standard/asynchronous-programming-patterns/implementing-the-task-based-asynchronous-pattern
  • Return types, cancellation behavior, Task.Run boundaries, and TAP implementation guidance.
• Microsoft Learn, "Consuming the Task-based Asynchronous Pattern"
  • https://learn.microsoft.com/en-us/dotnet/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern
  • await, WhenAll, WhenAny, cancellation propagation, and exception behavior.
• Microsoft Learn, "Async return types"
  • https://learn.microsoft.com/en-us/dotnet/csharp/asynchronous-programming/async-return-types
  • Task, Task<T>, async void, generalized async return types.
• Microsoft Learn, ValueTask API reference
  • https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.valuetask
  • single-consumer warnings and default-to-Task guidance.
• Microsoft Learn, ASP.NET Core best practices
  • https://learn.microsoft.com/en-us/aspnet/core/fundamentals/best-practices
  • avoid blocking calls, avoid unnecessary Task.Run, background-work cautions.
• Microsoft Learn, hosted services in ASP.NET Core
  • https://learn.microsoft.com/en-us/aspnet/core/fundamentals/host/hosted-services
  • safe long-lived background work and cancellation during shutdown.

Expert guidance used only when technically grounded

• Stephen Toub, ".NET Blog: ConfigureAwait FAQ"
  • https://devblogs.microsoft.com/dotnet/configureawait-faq/
  • best source for context capture semantics and library-vs-app guidance.
• Stephen Toub, ".NET Blog: Understanding the Whys, Whats, and Whens of ValueTask"
  • https://devblogs.microsoft.com/dotnet/understanding-the-whys-whats-and-whens-of-valuetask/
  • performance rationale and tradeoffs behind ValueTask<T>.
• Stephen Toub, ".NET Blog: Await, and UI, and deadlocks! Oh my!"
  • https://devblogs.microsoft.com/dotnet/await-and-ui-and-deadlocks-oh-my/
  • canonical deadlock explanation for context-bound code.
• Stephen Toub, ".NET Blog: Task Exception Handling in .NET 4.5"
  • https://devblogs.microsoft.com/dotnet/task-exception-handling-in-net-4-5/
  • explains await versus blocking exception shape and why WhenAll matters.
• Andrew Arnott, "Recommended patterns for CancellationToken"
  • https://devblogs.microsoft.com/premier-developer/recommended-patterns-for-cancellationtoken/
  • practical cancellation design heuristics; useful, but not treated as a language/runtime spec.
• Stephen Cleary, "Async/Await - Best Practices in Asynchronous Programming"
  • https://learn.microsoft.com/en-us/archive/msdn-magazine/2013/march/async-await-best-practices-in-asynchronous-programming
  • useful design interpretation, but older and treated as contextual guidance rather than current official policy.

Where the skill is intentionally cautious

• ConfigureAwait: strong guidance exists for libraries, weaker guidance for app code. Blanket rules are rejected.
• Task.Run: valid for deliberate CPU offload, weak as a server-side patch for blocking I/O.
• ValueTask: supported and useful, but easy to misuse. The skill defaults to Task unless evidence is present.
• Fire-and-forget: acceptable only with explicit ownership and lifecycle design, especially in server code.