Having already been caught out by the ASP.NET deadlock issue when using async code synchronously I did a lot of reading on the subject, from various sources and ended up compiling a list of rules/conventions to follow when dealing with async code. This is by no means a gospel list and I don't elaborate on why each guideline exists, but it's just a concise set of reminders of things to consider when writing async code, since the compiler will not pick up warnings for a lot of these things. The list is shared below:
  • Don't use .Result or .Wait() - use async/await (unless absolutely necessary - e.g. destructor, domain value factory - see final point)
  • Don't used async void - always return a Task
  • Always use "ConfigureAwait(false)" inside async library code (unless you need the context) [NB. Not applicable to .NET Core, bear in mind your consumers for .NET Standard]
  • Don't throw parameter exceptions in an async method, make the async method private and check the params in a public Task method before calling the private one
  • Don't "await Task.FromResult" - remove the async and just return the Task directly (unless async null or type casting).
  • When returning Task, don't return "null" - you must return Task.FromResult<T>(null);
  • Make sure any function returning Task is suffixed as "Async" to guide the caller
  • Don't use parallel for each with async/await, use tasks and Task.WhenAll (unless need custom partitioning)
  • Constructors and destructors cannot be marked async, therefore should not call async methods (no compiler warning)
  • For ctors - consider making it a factory with CreateInstanceAsync
  • For destructors - try to design against it, or fall back to Task.Run().GetAwaiter().GetResult() syntax (see final point)
  • When using .Wait() and .Result syntax, ensure it runs on a background thread with no context e.g. ... Task.Run(() => theMainAsync()).GetAwaiter().GetResult();
    [Technically GetAwaiter().GetResult() is not for public consumption and should be replaced with .Result, however I prefer it because it unwraps exceptions and it shows that you have purposefully coded as blocking code]
General approach: In general, start off by making the interface return Task<> .. update the classes to return Task, then look to see if anything inside the function is truly async. If yes - mark the function async and use await (unless you can pass through).. if No, then just return a Task.FromResult to satisfy the interface.. Don't use async/await inside of a parallel loop. You can block here since its already async and on another thread, or change to tasks. If you *need* to convert to synchronous (such as for passing a value factory) then use Task.Run to encapsulate the blocking call, so that its on another thread with a different context and use .GetAwaiter().GetResult() to unwrap exceptions. I have uploaded some examples to GitHub: https://github.com/craigwardman/AsyncExamples