Triage for dotnet/runtime#115819 by light-traveller

[MihuBot]

Triage for dotnet/runtime#115819.
Last updated: 2025-05-21_10-28-12

Proposal: Clarify or Alias AddHttpClient to Better Reflect Factory Behavior Problem by light-traveller
[Tool] Searching for AddHttpClient confusing, AddHttpClientFactory, HttpClientFactory method naming, AddHttpClient documentation, HttpClientFactory registration confusion
[Tool] Found 45 issues, 39 comments, 47 returned results (4448 ms)

Here are the most relevant related issues and discussions for #115819 ("Proposal: Clarify or Alias AddHttpClient to Better Reflect Factory Behavior Problem"):

---

1. Issue #64034 - [API Proposal]: Make AddHttpClient() inject an ITypedHttpClientFactory into instantiated class

• Summary: This proposal suggests that AddHttpClient() should inject a new interface, ITypedHttpClientFactory, to allow services to create new HttpClient instances with the configured settings, especially to avoid lifetime issues when injecting typed clients into singletons. The discussion highlights confusion around how AddHttpClient works, especially regarding DI lifetimes and expectations.
• Relevance: Shows that confusion around the behavior and intent of AddHttpClient is a recurring theme, especially regarding what is actually registered and how it interacts with DI.

---

2. Issue #96308 - [docs] Typed client registration issue

• Summary: This issue discusses the non-obvious behavior of AddHttpClient<TClient, TImplementation>, where the configuration is linked to a named client (by default, the type name of TClient). The discussion points out that this can be confusing and is not well documented, and suggests improving the documentation to clarify how registration and configuration work.
• Relevance: Reinforces the need for better documentation and clearer communication of how AddHttpClient and related methods behave, echoing the proposal's suggestion.

---

3. Issue #80202 - TryAddEnumerable for HttpClients

• Summary: The user wants to register multiple typed clients implementing the same interface. The discussion reveals that the configuration is keyed by the type name, and that specifying a distinct name per implementation is necessary. The explanation highlights the non-intuitive nature of the current API and the importance of understanding the underlying factory behavior.
• Relevance: Demonstrates that the naming and registration model of AddHttpClient is a source of confusion, supporting the proposal's rationale.

---

4. Issue #35997 - Add ability to register named HttpClient after DI configuration

• Summary: This issue requests the ability to register new named HttpClients at runtime, not just during DI configuration. The discussion includes workarounds and custom implementations, and highlights the distinction between registering a client and configuring the factory.
• Relevance: Shows that the distinction between registering a client and configuring the factory is not always clear to users, which is part of the confusion the proposal aims to address.

---

5. Issue #74508 - Can we make HttpClientFactory as purely configuration API?

• Summary: Discusses the intent of HttpClientFactory as a configuration API rather than a lifetime management API, and the confusion that arises from this. The discussion references official guidance and blog posts, and suggests that the documentation and API surface could be clearer.
• Relevance: Directly supports the proposal's point that the method name and documentation should better reflect the true behavior and intent of the API.

---

6. Issue #89755 - HttpClientFactory support for keyed DI

• Summary: This issue and its related PRs discuss new APIs for integrating keyed DI with HttpClientFactory, including new extension methods and registration patterns. The discussion includes considerations about naming, lifetimes, and the complexity of the current API surface.
• Relevance: Shows ongoing evolution of the API and the need for clear, discoverable, and intention-revealing method names and documentation.

---

7. Issue #110996 - Adding multiple HttpClients with same Interface results in conflicting configurations

• Summary: Users are surprised that registering multiple typed clients with the same interface results in shared configuration, due to the way AddHttpClient uses the interface name as the key. The discussion clarifies that this is by design, but acknowledges that it is non-obvious and can be confusing.
• Relevance: Another example of confusion stemming from the current naming and registration model.

---

8. Issue #36378 - Is dynamic IHttpClientFactory registration a bug or a feature?

• Summary: Explores the dynamic configuration of HttpClientFactory and the challenges of understanding how named clients and configuration actions work. The discussion includes requests for clearer documentation and more flexible APIs.
• Relevance: Highlights the need for better documentation and clearer API intent, as proposed in #115819.

---

9. Pull request #57719 - Add documentation to Microsoft.Extensions.Http

• Summary: This PR adds documentation to various parts of the Microsoft.Extensions.Http library, including the factory and builder APIs.
• Relevance: Indicates ongoing efforts to improve documentation, which aligns with the proposal's suggestion to enhance XML docs and IntelliSense.

---

10. Issue #96308 - [docs] Typed client registration issue

• Summary: (Duplicate of [MihaZupan] Vectorize ProbabilisticMap.IndexOfAny #2 above, but worth emphasizing) The issue and its triage note specifically call out the need for better conceptual documentation to explain the behavior of AddHttpClient and its overloads.
• Relevance: Directly supports the proposal's call for improved documentation.

---

Summary

• There is a clear, recurring pattern of confusion around the behavior and intent of AddHttpClient, especially regarding what is registered, how configuration is applied, and how it interacts with DI.
• Multiple issues and discussions call for improved documentation and clearer API surface.
• The proposal to introduce an alias like AddHttpClientFactory() and/or improve documentation is well-supported by user feedback and related issues.
• The .NET team has acknowledged these pain points in several places, and there are ongoing efforts to improve both the API and its documentation.

No previous issue or PR has proposed exactly the same aliasing approach, but the need for clarity and better documentation is a well-established theme.

---

If you need more details on any specific issue or want the full comment history for a particular discussion, let me know!