Add `Task.WithCancellation(CancellationToken)` method

[AArnott]

The WithCancellation extension method is super-useful. Should we add it to the .NET Framework / .NET Standard itself?

The risk is that folks will misunderstand the subtle yet important difference between using this method and passing the CancellationToken into the original async method properly.

Preferably this is not an extension method so it doesn't conflict with extension methods that folks have already defined. It should just override them, assuming the semantics are equivalent (the type of exception thrown, etc.)

See also the source code for its definition in the vs-threading library.

As discussed in davidfowl/AspNetCoreDiagnosticScenarios#8 with @davidfowl.

[benaadams]

Similar code is already in corefx; but only used for running tests rather than exposed as api

Task WithCancellation(this Task task, CancellationToken cancellationToken)

https://github.com/dotnet/corefx/blob/407c09d5840384fbd24bbd5b8869ef13be71de63/src/Common/tests/System/Threading/Tasks/TaskTimeoutExtensions.cs#L15

Also

Task WhenAllOrAnyFailed(this Task[] tasks)
Task WhenAllOrAnyFailed(this Task[] tasks, int millisecondsTimeout)

[Wraith2]

The risk is that folks will misunderstand the subtle yet important difference between using this method and passing the CancellationToken into the original async method properly.

for those not good at async, what difference?

[benaadams]

for those not good at async, what difference?

Cancelling the CancellationToken passed into the method cancels the Task

Cancelling the CancellationToken passed into the WithCancellation cancels waiting for the Task (but not the Task)

[omariom]

The risk is that folks will misunderstand the subtle yet important difference between using this method and passing the CancellationToken into the original async method properly.

What would be a good name for that? WithWaitingCancellation?

[jnm2]

ConfigureAwait(CancellationToken)

[AArnott]

ConfigureAwait(CancellationToken)

That's actually an interesting idea. The upside is I think people would understand it better. The downside is that Task is applicable in more scenarios than just awaiting, so if you're not awaiting and you want a Task that completes with early cancellation, you're not likely to look at a ConfigureAwait overload for that functionality.

[tarekgh]

CC @stephentoub

[StephenCleary]

I really prefer the Task.WaitAsync(CancellationToken) naming over WithCancellation. I think WaitAsync makes it much more clear that it is the wait that is canceled and not the task.