Async: explain the pattern of Task-returning synchronous methods

[BillWagner]

It's common that a method may perform all its work synchronously, and the last action is to call a (possibly asynchronous) method that returns a Task or Task<T>:

public async Task SomeMethodAsync()
{
   // some validation or other synchronous work
   await ownedObject.DoAsynchronousThings();
}

In these cases, the code can be simplified (including the generated code) by removing the async modifier, and the await statement:

public Task SomeMethodAsync()
{
   // some validation or other synchronous work
   return ownedObject.DoAsynchronousThings();
}

However, when we explain this optimization, we must be careful to explain when it can cause bugs. One important case is when the method allocates a Disposable object:

// Danger! Will often throw an AlreadyDisposedException:
public Task SomeMethodAsync()
{
   // some validation or other synchronous work
   using (var resource = AllocateDisposableResource())
   {
      return ownedObject.DoAsynchronousThings(resource);
   }
}

In the case above, the resource is possible still be used by ownedObject.DoAsynchronouseThings after the synchronous method SomeMethodAsync returns. In those cases (and others that manage or capture resources, the async / await keywords ensure that cleanup doesn't happen until the asynchronous work finishes:

// The generated state machine ensures resource cleanup
// only after the asynchronous method has completed its work:
public async Task SomeMethodAsync()
{
   // some validation or other synchronous work
   using (var resource = AllocateDisposableResource())
   {
      await ownedObject.DoAsynchronousThings(resource);
   }
}

[BrennanConroy]

Same thing with try catch

try
{
    return AsyncFunc();
}
// Will never catch exceptions thrown from AsyncFunc (unless they are thrown before the function goes async)
catch (...)
{
    ...
}

[BillWagner]

Adding a note on the comment above. This pattern with try / catch also requires the state machine, as @BrennanConroy notes. However, this phrase in the comment "(unless they are thrown before the function goes async)" is incorrect. The catch will never catch exceptions. See the discussion of local functions for async methods for details.

[BrennanConroy]

You're right, I was thinking of AsyncFunc being something like:

public Task AsyncFunc()
{
if (cond) throw new Exception();

return Task.Delay(100);
}

In which case the exception would be caught, but the function itself never went async

[dotnet-bot]

This issue has been closed as part of the issue backlog grooming process outlined in #22351.

That automated process may have closed some issues that should be addressed. If you think this is one of them, reopen it with a comment explaining why. Tag the @dotnet/docs team for visibility.