[API Proposal] ConfigureHttpClientDefaults for HttpClientFactory

[JamesNK]

Original issue by @JamesNK

Background and motivation

HttpClientFactory in Microsoft.Extensions.Http allows a developer to centrally configure and instatiate HTTP clients with DI:

services
    .AddHttpClient("consoto", c => c.BaseAddress = new Uri("https://consoto.com/"))
    .AddHttpMessageHandler<MyAuthHandler>();

services
    .AddHttpClient("github", c => c.BaseAddress = new Uri("https://github.com/"))
    .AddHttpMessageHandler<MyAuthHandler>();

Two named clients are defined in the example above. Unfortunately, there isn't a way to apply the default settings for all clients. Both need AddHttpMessageHandler<MyAuthHandler>().

This issue proposes an AddHttpClientDefaults method that can be used to specify configuration that is applied to all clients.

API Proposal

namespace Microsoft.Extensions.DependencyInjection;

public static class HttpClientFactoryServiceCollectionExtensions
{
+   public static IHttpClientBuilder AddHttpClientDefaults(this IServiceCollection services);
}

API Usage

AddHttpClientDefaults returns an IHttpClientBuilder. This is the same type returned by services.AddHttpClient(...). That means all the extension methods for IHttpClientBuilder automatically work with AddHttpClientDefaults.

services.AddHttpClientDefaults()
    .AddHttpMessageHandler<MyAuthHandler>();

// Clients automatically have the handler specified as a default.
services.AddHttpClient("consoto", c => c.BaseAddress = new Uri("https://consoto.com/"));
services.AddHttpClient("github", c => c.BaseAddress = new Uri("https://github.com/"));

The default configuration is run on a client before client-specific configuration:

services.AddHttpClientDefaults()
    .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://consoto.com/"));

// Client a base address of https://consoto.com
services.AddHttpClient("consoto");

// Client has a base address of https://github.com/ (overrides default)
services.AddHttpClient("github", c => c.BaseAddress = new Uri("https://github.com/"));

Default configuration can be added to multiple times, and its order compared to AddHttpClient doesn't matter:

services.AddHttpClientDefaults()
    .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://consoto.com/"));

// Client a base address of https://consoto.com and has MyAuthHandler
services.AddHttpClient("consoto");

services.AddHttpClientDefaults()
    .AddHttpMessageHandler<MyAuthHandler>();

Alternative Designs

We want AddHttpClientDefaults that returns an IHttpClientBuilder so existing extension methods automatically work with it.

We want to avoid the situation that we are seeing where people are adding two extension methods: one to add configuration to a builder, and another to apply configuration to all builders.

Example of what we don't want:

// Add handler to one client
services.AddHttpClient("myclient").AddMyCustomerLogging();

// Add handler to all clients
services.AddMyCustomerLoggingToAllClients();

Risks

No response

---

Background and motivation

HttpClientFactory in Microsoft.Extensions.Http allows a developer to configure and create HttpClient instances with DI.

Consider an example where two named clients are defined, and they all need MyAuthHandler in their message handlers chain.

services
    .AddHttpClient("consoto", c => c.BaseAddress = new Uri("https://consoto.com/"))
    .AddHttpMessageHandler<MyAuthHandler>();

services
    .AddHttpClient("github", c => c.BaseAddress = new Uri("https://github.com/"))
    .AddHttpMessageHandler<MyAuthHandler>();

Unfortunately, there isn't a way to apply the default settings for all clients. All need AddHttpMessageHandler<MyAuthHandler>().

This issue proposes an ConfigureHttpClientDefaults method that can be used to specify configuration that is applied to all clients.

API Proposal

// existing
public static class HttpClientFactoryServiceCollectionExtensions
{
    // new
    public static IServiceCollection ConfigureHttpClientDefaults(
        this IServiceCollection services, Action<IHttpClientBuilder> configure) {}
}

// existing
public static class HttpClientBuilderExtensions
{
    // new
    public static IHttpClientBuilder ConfigurePrimaryHttpMessageHandler(
        this IHttpClientBuilder builder,
        Action<HttpMessageHandler, IServiceProvider> configureHandler) {}

    public static IHttpClientBuilder ConfigureAdditionalHttpMessageHandlers(
        this IHttpClientBuilder builder,
        Action<IList<DelegatingHandler>, IServiceProvider> configureAdditionalHandlers) {}


    // existing (+2 overloads)
    // public static IHttpClientBuilder ConfigurePrimaryHttpMessageHandler(this IHttpClientBuilder builder, Func<HttpMessageHandler> configureHandler) {}

    // existing (+2 overloads)
    // public static IHttpClientBuilder AddHttpMessageHandler(this IHttpClientBuilder builder, Func<DelegatingHandler> configureHandler) {}

    // existing -- to be deprecated in the future
    // public static IHttpClientBuilder ConfigureHttpMessageHandlerBuilder(this IHttpClientBuilder builder, Action<HttpMessageHandlerBuilder> configureBuilder) {}
}

API Usage

1. Basic usage and extension methods

ConfigureHttpClientDefaults accepts an action over IHttpClientBuilder. This is the same type returned by services.AddHttpClient(...). That means all the extension methods for IHttpClientBuilder automatically work with AddHttpClientDefaults.

services.ConfigureHttpClientDefaults(b =>
    b.AddHttpMessageHandler<MyAuthHandler>());

// Clients automatically have the handler specified as a default.
services.AddHttpClient("consoto", c => c.BaseAddress = new Uri("https://consoto.com/"));
services.AddHttpClient("github", c => c.BaseAddress = new Uri("https://github.com/"));

2. Order of applying

The default configuration is run on a client before client-specific configuration:

services.ConfigureHttpClientDefaults(b =>
    b.ConfigureHttpClient(c => c.BaseAddress = new Uri("https://consoto.com/")));

// Client a base address of https://consoto.com
services.AddHttpClient("consoto");

// Client has a base address of https://github.com/ (overrides default)
services.AddHttpClient("github", c => c.BaseAddress = new Uri("https://github.com/"));

Default configuration can be added to multiple times, between each other it will be applied one-by-one in order of registration; and its place in the registration compared to AddHttpClient doesn't matter:

services.ConfigureHttpClientDefaults(b =>
    b.ConfigureHttpClient(c => c.BaseAddress = new Uri("https://consoto.com/")));

// Client a base address of https://consoto.com and has MyAuthHandler
services.AddHttpClient("consoto");

services.AddHttpClientDefaults()
    .AddHttpMessageHandler<MyAuthHandler>();

3. Subsequent per-name reconfiguration

Setting additional properties in a primary handler:

services.ConfigureHttpClientDefaults(b =>
    b.ConfigurePrimaryHandler(() => new SocketsHttpHandler() { UseCookies = false }));

// will have SocketsHttpHandler with UseCookies = false and MaxConnectionsPerServer = 1
services.AddHttpClient("bar")
    .ConfigurePrimaryHandler((handler, _) => ((SocketsHttpHandler)handler).MaxConnectionsPerServer = 1);

Inserting in a specific position or removing from an additional handlers list:

services.ConfigureHttpClientDefaults(b =>
    b.AddHttpMessageHandler<MyAuthHandler>());

// will have MyLoggingHandler as a top-most wrapper handler, and MyAuthHandler
services.AddHttpClient("baz")
    .ConfigureAdditionalHttpMessageHandlers((handlerList, _) => handlerList.Insert(0, new MyLoggingHandler());

// will NOT have MyAuthHandler
services.AddHttpClient("qux")
    .ConfigureAdditionalHttpMessageHandlers((handlerList, _) =>
        handlerList.Remove(handlerList.SingleOrDefault(h => h.GetType() == typeof(MyAuthHandler))));

4. Subsequent per-name reconfiguration -- order of applying

Between each other, the order of ConfigurePrimaryHandler and ConfigureAdditionalHttpMessageHandlers and other per-name configuration methods is the same as if it was implemented via ConfigureHttpMessageHandlerBuilder -- in order of registration, and if a subsequent write overwrites e.g. a primary handler instance, the last one "wins".

// Primary handler will already be a SocketsHttpHandler instance because it was set in ConfigureHttpClientDefaults
// below, which runs first, so it is safe to cast
services.AddHttpClient("bar")
    .ConfigurePrimaryHandler((handler, _) => ((SocketsHttpHandler)handler).MaxConnectionsPerServer = 1);

// But the second call overwrites primary handler, so the final result will NOT have MaxConnectionsPerServer  set
services.AddHttpClient("bar")
    .ConfigurePrimaryHandler(() => new SocketsHttpHandler() { UseCookies = false }));

services.ConfigureHttpClientDefaults(b =>
    b.ConfigurePrimaryHandler(() => new SocketsHttpHandler()));

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

Issue Details

---

Background and motivation

HttpClientFactory in Microsoft.Extensions.Http allows a developer to centrally build and configure HTTP clients with DI:

services
    .AddHttpClient("consoto", c => c.BaseAddress = new Uri("https://consoto.com/"))
    .AddHttpMessageHandler<MyAuthHandler>();

services
    .AddHttpClient("github", c => c.BaseAddress = new Uri("https://github.com/"))
    .AddHttpMessageHandler<MyAuthHandler>();

Two named clients are defined in the example above. Unfortunately, there isn't a way to apply the default settings for all clients. Both need AddHttpMessageHandler<MyAuthHandler>().

This issue proposes an AddHttpClientDefaults method that can be used to specify configuration that is applied to all clients.

API Proposal

namespace Microsoft.Extensions.DependencyInjection;

public static class HttpClientFactoryServiceCollectionExtensions
{
    public static IHttpClientBuilder AddHttpClientDefaults(this IServiceCollection services);
}

API Usage

AddHttpClientDefaults returns an IHttpClientBuilder. This is the same type returned by services.AddHttpClient(...). That means all the extension methods for IHttpClientBuilder automatically work with AddHttpClientDefaults.

services.AddHttpClientDefaults()
    .AddHttpMessageHandler<MyAuthHandler>();

// Clients automatically have the handler specified as a default.
services.AddHttpClient("consoto", c => c.BaseAddress = new Uri("https://consoto.com/"));
services.AddHttpClient("github", c => c.BaseAddress = new Uri("https://github.com/"));

The default configuration is run on a client before client-specific configuration:

services.AddHttpClientDefaults()
    .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://consoto.com/"));

// Client a base address of https://consoto.com
services.AddHttpClient("consoto");

// Client has a base address of https://github.com/ (overrides default)
services.AddHttpClient("github", c => c.BaseAddress = new Uri("https://github.com/"));

Default configuration can be added to multiple times, and its order compared to AddHttpClient doesn't matter:

services.AddHttpClientDefaults()
    .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://consoto.com/"));

// Client a base address of https://consoto.com and has MyAuthHandler
services.AddHttpClient("consoto");

services.AddHttpClientDefaults()
    .AddHttpMessageHandler<MyAuthHandler>();

Alternative Designs

We want AddHttpClientDefaults that returns an IHttpClientBuilder so existing extension methods automatically work with it.

We want to avoid the situation we are seeing where people are adding two extension methods: one to add configuration to a builder, and another to apply configuration to all builders.

Example of what we don't want:

// Add handler to one client
services.AddHttpClient("myclient").AddMyCustomerLogging();

// Add handler to all clients
services.AddMyCustomerLoggingToAllClients();

Risks

No response

Author:	JamesNK
Assignees:	-
Labels:	api-suggestion, area-Extensions-HttpClientFactory
Milestone:	-

[CarnaViire]

We had a discussion with @stephentoub yesterday about the API shape and we came up with a potentially more easy-to-undersand API:

public static IServiceCollection ConfigureHttpClientDefaults(this IServiceCollection services, Action<IHttpClientBuilder> configure) {}

One of the main points was that AddHttpClientDefaults() itself is a "no-op" which doesn't bring any value if the builder is not subsequently configured. The API proposed requires a configuration method to be passed.
This API also mitigates the issue we've discussed on our call @JamesNK

I strongly believe we need 2 additional APIs to be able to conveniently modify default configuration per-name:

public static IHttpClientBuilder ConfigurePrimaryHttpMessageHandler(this IHttpClientBuilder builder, Action<HttpMessageHandler, IServiceProvider> configureHandler) {}
public static IHttpClientBuilder ConfigureAdditionalHttpMessageHandlers(this IHttpClientBuilder builder, Action<IList<DelegatingHandler>, IServiceProvider> configureAdditionalHandlers) {}

While this can be achieved through ConfigureHttpMessageHandlerBuilder, I would strongly advise against it.

I'd like to avoid encouraging users to use the API that forbids optimizations and that we are planning to eventually deprecate (as it prevents us from improvements and/or fixes like #35987 and #47091 that require separation of PrimaryHandler creation from additional handlers creation) -- and currently there's no other way.

Usages:

services.ConfigureHttpClientDefaults(b =>
    b.AddHttpMessageHandler<MyAuthHandler>()
        .ConfigurePrimaryHandler(() => new SocketsHttpHandler() { UseCookies = false }));

// will have MyAuthHandler and SocketsHttpHandler with UseCookies = false
services.AddHttpClient("foo");

// will have MyAuthHandler and SocketsHttpHandler with UseCookies = false and MaxConnectionsPerServer = 1
services.AddHttpClient("bar")
    .ConfigurePrimaryHandler((handler, _) => ((SocketsHttpHandler)handler).MaxConnectionsPerServer = 1);

// will have MyLoggingHandler as a top-most wrapper handler, MyAuthHandler, and SocketsHttpHandler
// with UseCookies = false
services.AddHttpClient("baz")
    .ConfigureAdditionalHttpMessageHandlers((handlerList, _) => handlerList.Insert(0, new MyLoggingHandler());

// will have SocketsHttpHandler with UseCookies = false and will not have MyAuthHandler
services.AddHttpClient("qux")
    .ConfigureAdditionalHttpMessageHandlers((handlerList, _) =>
        handlerList.Remove(handlerList.SingleOrDefault(h => h.GetType() == typeof(MyAuthHandler))));

[JamesNK]

We had a discussion with @stephentoub yesterday about the API shape and we came up with a potentially more easy-to-undersand API:

public static IServiceCollection ConfigureHttpClientDefaults(this IServiceCollection services, Action<IHttpClientBuilder> configure) {}

One of the main points was that AddHttpClientDefaults() itself is a "no-op" which doesn't bring any value if the builder is not subsequently configured. The API proposed requires a configuration method to be passed. This API also mitigates the issue we've discussed on our call @JamesNK

Good point that AddHttpClientDefaults() doesn't do anything by itself. However, it's worth mentioning that AddHttpClient("name") doesn't do anything either. It just returns a builder with the name, and that's it:

runtime/src/libraries/Microsoft.Extensions.Http/src/DependencyInjection/HttpClientFactoryServiceCollectionExtensions.cs

Lines 78 to 86 in 3195fbb

	public static IHttpClientBuilder AddHttpClient(this IServiceCollection services, string name)
	{
	ThrowHelper.ThrowIfNull(services);
	ThrowHelper.ThrowIfNull(name);
	AddHttpClient(services);
	return new DefaultHttpClientBuilder(services, name);
	}

I like how AddHttpClientDefaults() is so similar to AddHttpClient(...). But, I don't have a strong objection to ConfigureHttpClientDefaults. It solves the chaining issue.

I strongly believe we need 2 additional APIs to be able to conveniently modify default configuration per-name:

Do they need to be done right now as part of this issue? As far as I can tell they don't block the customer scenarios in this issue, and they aren't blocked from being done in the future.

Off topic, I noticed a problem in one of your sample usages:

// will have MyAuthHandler and SocketsHttpHandler with UseCookies = false and MaxConnectionsPerServer = 1
services.AddHttpClient("bar")
    .ConfigurePrimaryHandler((handler, _) => handler.MaxConnectionsPerServer = 1);

In the proposed API, this example is missing a cast from HttpMessageHandler to SocketsHttpHandler:

// will have MyAuthHandler and SocketsHttpHandler with UseCookies = false and MaxConnectionsPerServer = 1
services.AddHttpClient("bar")
    .ConfigurePrimaryHandler((handler, _) => ((SocketsHttpHandler)handler).MaxConnectionsPerServer = 1);

[CarnaViire]

Do they need to be done right now as part of this issue? As far as I can tell they don't block the customer scenarios in this issue, and they aren't blocked from being done in the future.

I believe they need to be part of this release. While they don't block scenario of setting defaults, their absence subsequently encourages the use of ConfigureHttpMessageHandlerBuilder as the only workaround for per-name re-configuration. It will make it super painful to obsolete ConfigureHttpMessageHandlerBuilder in the future if that happens.

In the proposed API, this example is missing a cast from HttpMessageHandler to SocketsHttpHandler

Good catch, thanks! I'll update it.

[CarnaViire]

Good point that AddHttpClientDefaults() doesn't do anything by itself. However, it's worth mentioning that AddHttpClient("name") doesn't do anything either. It just returns a builder with the name, and that's it

Good point, even though that's not strictly true, it will add all the HttpClientFactory infra the first time it's called... so you can use the factory to create (unconfigured/default) clients right away. And while AddHttpClientDefaults would also all the infra, it wouldn't bring any more value than an empty AddHttpClient call... Though, I liked the similarity as well. I suggest bringing both options to the API review and decide there.

2 additional APIs to be able to conveniently modify default configuration per-name

Do they need to be done right now as part of this issue?

Let me also add that they don't have to be optimized now, if you are worried about that. Non-optimized implementation is a straightforward one-liner.

[stephentoub]

The concept of a parameterless method adding a new named client makes sense. The concept of a parameterless method adding defaults does not; it suggests without doing it there aren't defaults, which is both confusing and incorrect.

[JamesNK]

Updating to use ConfigureHttpClientDefaults: a13c14a (#87953)

Simple change. Feels good to use.

Add extra configure methods for additional handlers and primary handler: ec57e0a (#87953)

I implemented these by using the existing HttpMessageHandlerBuilderActions. That means the order the configuration runs in depends on when it is called.

What happens if someone does:

services.AddHttpClient("bar")
    .ConfigurePrimaryHandler((handler, _) => ((SocketsHttpHandler)handler).MaxConnectionsPerServer = 1);

services.AddHttpClient("bar")
    .ConfigurePrimaryHandler(() => new SocketsHttpHandler() { UseCookies = false }));

Exact thought needs to be put into when these methods run.

Another example:

services.AddHttpClient("bar")
    .AddHttpMessageHandler(() => Mock.Of<DelegatingHandler>())
    .ConfigureAdditionalHttpMessageHandlers((additionalHandlers, _) =>
    {
        additionalHandlers.Clear();
    });

Someone might expect the code above to result in no additional handlers for the client. Actually the client still has two additional handlers. After the delegate added by ConfigureAdditionalHttpMessageHandlers runs and clears the collection, configuration by the logging filter adds two logging handlers.

[JamesNK]

I think the intent is these configuration methods is they run after HttpMessageHandlerBuilderActions. Won't extra APIs be needed on HttpClientFactoryOptions?

public class HttpClientFactoryOptions
{
+   public IList<Action<HttpMessageHandler>> PrimaryMessageHandlerActions { get; }

+   public IList<Action<IList<HttpMessageHandler>> AdditionalHttpMessageHandlerActions { get; }
}