I couldn't figure out the best area label to add to this PR. If you have write-permissions please help me learn by adding exactly one area label.

@stephentoub If the methods actually throw a TaskCanceledException, I guess it's still okay to catch OperationCanceledException when you await?

@stephentoub If the methods actually throw a TaskCanceledException, I guess it's still okay to catch OperationCanceledException when you await?

Yes, in fact we want folks to catch OperationCanceledException and not TaskCanceledException. From my perspective, our introducing TaskCanceledException was a well-intentioned mistake. The idea was that it would be an OperationCanceledException that would carry a little more information (the Task that was canceled) if necessary, but that additional information is basically never useful or needed, and it's often not even possible to provide, yet because APIs were throwing it, developers started writing catch blocks for it, which then made it a breaking change for the implementation throwing it to be tweaked in such a way that the base OperationCanceledException was being thrown. We should probably introduce an analyzer to warn people off from catching TaskCanceledException, and maybe even obsolete it (though that's drastic).

Based on @stephentoub 's comment, I checked our conceptual and samples repos.

In conceptual docs, I found 138 instances of TaskCanceledException. In our samples, I found 101 instances. Should we update the relevant catch clauses, and the text describing them to catch OperationCanceledException instead?

In conceptual docs, I found 138 instances of TaskCanceledException. In our samples, I found 101 instances. Should we update the relevant catch clauses, and the text describing them to catch OperationCanceledException instead?

@BillWagner I'd say yes!

Yes, please and thank you.

Learn Build status updates of commit 52f0fdd:

✅ Validation status: passed

This comment lists only the first 25 files in the pull request.
For more details, please refer to the build report.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel

Learn Build status updates of commit 55eac5d:

✅ Validation status: passed

This comment lists only the first 25 files in the pull request.
For more details, please refer to the build report.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel