Merge general async guidance into the docs

[timmydo]

There are some good guides around using async, such as:

https://github.com/davidfowl/AspNetCoreDiagnosticScenarios/blob/master/AsyncGuidance.md

Could I request that these tips be merged into the remarks section of individual class/method/property documents (such as https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskcompletionsource-1?view=net-5.0) as well as maybe having a dedicated section within dotnet or asp.net?

Tagging subscribers to this area: @carlossanlop
See info in area-owners.md if you want to be subscribed.

Issue Details

---

There are some good guides around using async, such as:

https://github.com/davidfowl/AspNetCoreDiagnosticScenarios/blob/master/AsyncGuidance.md

Could I request that these tips be merged into the remarks section of individual class/method/property documents (such as https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskcompletionsource-1?view=net-5.0) as well as maybe having a dedicated section within dotnet or asp.net?

Author:	timmydo
Assignees:	-
Labels:	:watch: Not Triaged, Pri3, area-System.Threading.Tasks
Milestone:	-

[gewarren]

@timmydo We do have some conceptual articles in the .NET docs, e.g. https://docs.microsoft.com/en-us/dotnet/standard/async-in-depth. Were you aware of these?

[timmydo]

No, I wasn't, but looking at that one, it seems the content doesn't cover the AsyncGuidance.md I linked.

Generally speaking, I don't find the articles on docs.microsoft.com to be as discoverable as the API docs. I'm not sure what I could suggest other than incorporating some of the guidance into the remarks sections.

[steveharter]

cc @stephentoub

[stephentoub]

David's examples are good, but there's also a lot of opinion mixed in. I'd be fine if we incorporated some of the more factual aspects that aren't covered in enough detail, or if we wanted to add coverage of the pros and cons to various things, but I don't think the docs should take as hard a stance on some of these as he does. You mention TaskCompletionSource as an example; there are plenty of situations where passing RunContinuationsAsynchronously, which the write-up says to always do, is a deoptimization and doesn't provide benefit, even though I agree with the general spirit of it being the safer thing to do until you know what you're doing.

[timmydo]

I agree. David's doc is highly opinionated, which is fitting for its purpose. For the .NET API docs, I think pros and cons would be a better fit.

To follow the same example, https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskcreationoptions?view=net-5.0, RunContinuationsAsynchronously means Forces continuations added to the current task to be executed asynchronously. Maybe there could be a remarks section there and in the TaskCompletionSource ctor describing the implications of what that means.

Another example might be https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.task.continuewith?view=net-5.0. The example doesn't seem representitive of how I've seen it used--and when I see a bunch of comments "for demo purposes" then I don't get a feeling of how I /should/ be calling it. Maybe that page could explain the difference between ContinueWith and just using await.