HttpWebRequest.BeginGetResponse example doesn't correctly follow the APM pattern

[svick]

Per @stephentoub's comment in microsoft/referencesource#177 (comment) regarding the documentation of HttpWebRequest.BeginGetResponse:

That code sample is buggy and does not correctly follow the APM pattern. BeginXx methods may complete the operation synchronously, which is why the IAsyncResult.CompletedSynchronously property exists. The callback needs to check that property, and if it's true, exit immediately and instead allow the BeginXx call site to perform the continuation. Otherwise, a string of synchronously completing operations may stack dive. The docs should be fixed

Also, I think it might be useful for this page to contain a prominent note pointing people to modern alternatives, namely async methods on HttpClient.

[ghost]

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

Issue Details

---

Per @stephentoub's comment in microsoft/referencesource#177 (comment) regarding the documentation of HttpWebRequest.BeginGetResponse:

That code sample is buggy and does not correctly follow the APM pattern. BeginXx methods may complete the operation synchronously, which is why the IAsyncResult.CompletedSynchronously property exists. The callback needs to check that property, and if it's true, exit immediately and instead allow the BeginXx call site to perform the continuation. Otherwise, a string of synchronously completing operations may stack dive. The docs should be fixed

Also, I think it might be useful for this page to contain a prominent note pointing people to modern alternatives, namely async methods on HttpClient.

Author:	svick
Assignees:	-
Labels:	area-System.Net, untriaged, Pri3
Milestone:	-