Add detail in HttpClient documentation

[rpetrusha]

Add detail in HttpClient documentation

See PR dotnet/docs#4330 for background information.

Issues with Existing Topics

The HttpClient documentation needs to be updated to address issues that are not discussed or differences between .NET implementations. These include:

• The connection limit, on a per-implementation basis.
• Issues related to using a single instance of HttpClient
• HttpClient and the DNS refresh problem
• Guidance on when to instantiate a new HttpClient instance

Suggest reviewers

@feherzsolt @davidsh @karelz

[mairaw]

Can you set milestone and priority @rpetrusha? Thanks.

[Treit]

I was going to open a new issue on the HttpClient documentation but I see this issue seems to cover similar topics.

Specifically, this statement:

HttpClient is intended to be instantiated once and re-used throughout the life of an application. Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads. This will result in SocketException errors. Below is an example using HttpClient correctly.

There is no mention anywhere in the documentation for HttpClient that I can see that points to HttpClientFactory, which I understand is now considered the 'best practice' way to get an HttpClient instance and avoids several issues, as discussed here:

https://docs.microsoft.com/en-us/aspnet/core/fundamentals/http-requests?view=aspnetcore-5.0

The documentation should be updated to point out the best practice for using HttpClient and should not leave the reader with the impression that creating a single instance and re-using it for the entire applications lifetime is the documented best practice.

Let me know if this is targeted enough that a separate issue should be filed for this. I see this issue is quite old.

[gewarren]

Related to dotnet/docs#26510, #8021, and #8082.