Dotnet-api-docs: explain default behavior of ConfigureAwait()

[galich]

what is the default behavior? will code continue to run on captured context by default or not?
> ...attempt to marshal...

Does that mean attempt may fail? Under what conditions?

---

Document Details

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

• ID: e069a261-9adf-92e6-9b16-8a701968a36d
• Version Independent ID: a12bf93b-1690-1604-20b0-2bf5ca44b372
• Content: Task.ConfigureAwait(Boolean) Method (System.Threading.Tasks)
• Content Source: xml/System.Threading.Tasks/Task.xml
• Product: .net
• GitHub Login: @dotnet-bot
• Microsoft Alias: dotnetcontent

[mairaw]

@stephentoub can you help with this issue?

[stephentoub]

what is the default behavior? will code continue to run on captured context by default or not?

When await'ing a Task/Task<T>, the default behavior is the same as if .ConfigureAwait(continueOnCapturedContext:true) was used. That means that the awaiter looks to see if there's a non-default SynchronizationContext (or if there isn't, a non-default TaskScheduler) present, and if there is, it stores it for the continuation to be handed off to when the awaiter completes.

...attempt to marshal...

That means there may not be anything to marshal back to... there may not be a context to capture, e.g. SynchronizationContext.Current may return null.

[mrange]

I think it is interesting that here the true case is documented but when devs use it they pass false which is not documented what that means. Since this affects how the continuation is invoked which is important to understand when it comes to avoid dead-locks and/or race conditions I think this methods should be one of the most documented methods in .NET API. Also the name is not helping I think.

[drumsta]

This topic definitely should be documented much better, or at least pointed out to another pages where the method would be explained more thoroughly.

[NathanWarden]

Yes, better documentation for this would be very appreciated! :)

[laishiekai]

And please provide good example codes.

[mrange]

This is a method that is hard for the community to help document because TBH the details of how async really works is poorly understood and when it comes to concurrency the details matters.

[gbelzile]

Why is the default value set to true and FxCop tells you to use false? Is it true that this doesn't apply to .Net Core?

[KalleOlaviNiemitalo]

Please document that the bool continueOnCapturedContext parameter controls only SynchronizationContext and not ExecutionContext. In particular, if you set AsyncLocal\.Value before awaiting and get it afterwards, then you will find the same value, regardless of whether continueOnCapturedContext is true or false.