HttpClient - items to improve

[gewarren]

• Add cross-link to https://docs.microsoft.com/en-us/dotnet/standard/microservices-architecture/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests
• Add examples of using Polly and Polly.Extensions.Http nuget PackageReference to a project. These are "opinionated" libraries to assist in transient fault handling.
• Incorporate @karelz feedback:

  Unfortunately, this recommendation is not complete.
  We need to warn users also about having long-existing HttpClient instances as that may lead to stale DNS usage. That can lead to non-functional connections.

  The recommendation should be either to:

  • Use HttpClient instances as statics, which are recycled on regular basis, or
  • Use HttpClientFactory which works around this problem, or
  • Use static instances on .NET Core while setting System.Net.Http.SocketsHttpHandler.PooledConnectionLifetime.

• Regarding PooledConnectionLifetime, consider adding reference to Fix SocketsHttpHandler handling of pooling timeouts with max connections corefx#29822 which I believe fixes this in .NET Core 2.2 (Stephen Toub's commit is on May 22, 2018 and .NET Core 2.1 was released on May 30th, 2018). In other words, if your application needs to target .NET Core 2.1, this approach can probably run into problems described in that PR.
• Consider describing the benefits of using HttpClient via HttpClientFactory, including remarks in SockerHttpHandler https://docs.microsoft.com/en-us/dotnet/api/system.net.http.socketshttphandler?view=netcore-3.1#remarks

Originally posted by @jzabroski in dotnet/dotnet-api-docs#2315 (comment)

[CarnaViire]

Originally posted by @alex-jitbit in dotnet/dotnet-api-docs#7285

---

HttpClient needs official guidance on how to use it properly. Currently MS docs mention only two ways of how we should use it:

• (a) singleton static instance (for console apps)
• (b) HttpClientFactory via DI in ASP.NET apps.

But that's not enough.

For example, here's one MS doc at https://docs.microsoft.com/en-us/dotnet/api/system.net.http.httpclient?view=net-5.0 that literally says

HttpClient is intended to be instantiated once and re-used throughout the life of an application

But it never mentions that in that case, HttpClient will ignore DNS changes. This issue has been reported multiple times on github and stackoverflow. And to fix the DNS problem we need to use a special constructor:

new HttpClient(new SocketsHttpHandler
{
	PooledConnectionLifetime = TimeSpan.FromMinutes(20) //recreate every 20 minutes
});

But MS docs never mention this fix. I found it accidentally, after hours of searching github for comments from MS employees.

The only more or less full (ish) guidance I found is in this comment: dotnet/aspnetcore#28385 (comment) but its not even written by MS, just some good Samaritan who decided to help everyone.

Please read the comment and reflect the docs

[antonfirsov]

Been thinking about this issue a bit, and for me it feels like we need a good conceptual doc around HttpClient and IHttpClientFactory explaining and comparing both approaches. We can then link that doc from various Remarks sections across the huge and complicated API surface we have.

I see that a new document "HTTP with dotnet" has been introduced recently in #25061, which mostly focuses on the factory, although it's not necessarily the go-to way to do "HTTP with dotnet".

My recommendation would be to restructure that document in a manner that also explains HttpClient, the implications of it's disposal, DNS behavior and PooledConnectionLifetime.

[gewarren]

@antonfirsov Okay, I'll transfer this issue to dotnet/docs repo.

[CarnaViire]

It might be helpful to gather the explanations we post elsewhere on GH so they might be reused when preparing the docs.

---

dotnet/runtime#68866 (comment)

HttpClientFactory is no magic wand that will give you a "fixed" HttpClient. The factory solves socket exhaustion problem by pooling, reusing and recreating HttpClientHandlers. HttpClients created by the factory are expected to be short-lived, and it is OK because handlers are reused. After HttpClient is created, HttpClientFactory has no control over it anymore, so it plainly cannot handle it's lifetime.

If you use .NET Core/.NET 5+, we recommend using a static/singleton HttpClient with PooledConnectionLifetime set to a desired interval depending on expected DNS changes (e.g. you can use 2 mins as HttpClientFactory does by default):

new HttpClient(new SocketsHttpHandler
{
    PooledConnectionLifetime = TimeSpan.FromMinutes(2) //recreate every 2 minutes
});

If you wish to register your handler separately to be able to mock it, it could be

services.AddSingleton<HttpClientHandler>(sp => new SocketsHttpHandler { PooledConnectionLifetime = TimeSpan.FromMinutes(2) });
services.AddSingleton<HttpClient>(sp => new HttpClient(sp.GetRequiredService<HttpClientHandler>()));

This would solve both socket exhaustion and DNS changes problems without adding an overhead of HttpClientFactory.

If you require the full configurability HttpClientFactory offers, though, like having multiple differently configured HttpClients for different use cases, you are welcome to use Typed client approach, though please be aware, that Typed clients are also intended to be short-lived, and you may shoot yourself in a foot if you inject it into a sigleton. See e.g. dotnet/runtime#64034

---

dotnet/runtime#68866 (comment)

I feel lot of the confusion and issues comes from the fact that users do not understand how it actually works and we do not have great documentation. Partially for historical reasons and lack of time and partially because it is internal implementation detail. Also some of it depends on specific use pattern so there not simple single solution that fits everything.

in .NET Framework the connection pool was linked to ServicePointManager and HttpClient was implemented on top of HttpWebRequest. So disposing HttpClient did not impact connection management.

In .NET Core, the connection pool is linked to HttpClient's underlying HttpHandler. So when HttpClient is disposed it will dispose all previously used connections. That forces new connection next time you need to talk to the same server and there is performance penalty as well it needs new TCP port. If the rate of request is high or if there are any firewall limitations that can exhaust available range because of default TCP cleanup timers.

So tho work efficiently as possible it is good to reuse HttpClient. Either as singleton or via Factory as @CarnaViire suggested.

The DNS issue was always somewhat mysterious to me. If you for example move server to new IP and update DNS it will work as the existing connections would see error and there is new DNS lookup every time HttpClient needs connection (e.g. there is no magic DNS caching behind the scenes). The only once case that is not handled well is case when existing server decides to stop handling request for given site silently e.g. without closing connections first. This is where the PooledConnectionLifetime comes in to force recreation every so often (mostly without real need)

So depending on your use single static HttpClient may work for you just fine