.NET: Align HTTP client infrastructure and developer experience #9992

Category

Other - .NET HTTP infrastructure and developer-experience alignment.

Problem

.NET integrations currently offer several different HTTP customization and ownership models: a direct HttpClient parameter, an init-only client property, internally constructed clients, and named/typed clients obtained through IHttpClientFactory.

Applications using multiple integrations consequently have to learn different registration, configuration, client-lifetime, and disposal conventions. We should align the infrastructure and application experience around host-managed HTTP configuration and handler pooling, building on the factory-based approach already being introduced for declarative workflows.

This is an infrastructure-consistency and developer-experience task, not a report of a security defect. A direct HttpClient parameter is not automatically something to remove: typed clients and internal helpers can legitimately consume factory-created clients. The goal is a coherent host-facing experience and explicit ownership, not a mechanical signature rewrite.

Evidence

Inventory below is based on commit fb791b540. Source links are pinned to that revision.

Existing pull requests establishing the direction

• .NET: [BREAKING] fix(dotnet): require allowed HTTP hosts #9841: DefaultHttpRequestHandler now requires an application-owned IHttpClientFactory, supports a configured client name, and no longer has direct-client, creation-callback, internally owned fallback, or handler-disposal paths. The factory-only migration is in commit 050475d25. See the handler constructor and acquisition/disposal path and updated HTTP workflow sample registration.
• .NET: [BREAKING] fix: scope workflow MCP clients to invocations #9722: aligns declarative DefaultMcpToolHandler around an application-owned IHttpClientFactory and separates invocation-owned protocol clients from reusable HTTP infrastructure. That handler is already covered by the existing PR and is not additional work for this issue.

Public API surfaces to assess

There are six additional public entry points across three integration areas; all accept a client directly rather than a callback that creates one.

No additional callback-returning-HttpClient surface was found in production source outside the declarative MCP handler already covered by #9722.

Internal infrastructure and already-aligned paths

• Mem0: Mem0Client(HttpClient) retains the client supplied by Mem0Provider. Keep this internal lifetime consistent with any public-provider migration.
• Purview: PurviewClient(..., HttpClient, ...) receives its client through a privately built service provider. PurviewExtensions.CreateWrapper currently uses AddSingleton<HttpClient>(). Assess host integration and explicit ownership of both the service provider and HTTP infrastructure rather than only changing the internal constructor.
• Aspire DevUI: AspireDashboardTraceClient.IsAvailableAsync and GetTraceEventsAsync accept direct clients, but their callers already acquire and dispose named factory clients: availability check, trace retrieval. These are examples of legitimate internal direct-client parameters, not necessarily migration targets.
• Foundry hosting toolbox: FoundryToolboxService creates its own client, stores it in CachedToolbox, and disposes it with the cached toolbox. This is an adjacent infrastructure-alignment candidate, not an externally exposed direct-client overload. Evaluate reusable HTTP-handler infrastructure separately from MCP client/session lifetimes. This service is distinct from the declarative MCP tool handler covered by .NET: [BREAKING] fix: scope workflow MCP clients to invocations #9722.

Sample experience to keep consistent

• Mem0 sample: manually configures and passes a client. Update alongside any provider API or registration changes.
• AgentWebChat: AgentDiscoveryClient, OpenAIResponsesAgentClient, and OpenAIChatCompletionsAgentClient take direct clients, but all three are registered as typed factory clients. Preserve this already-aligned pattern.
• Invocations sample: InvocationsAIAgent accepts an optional client and falls back to new HttpClient(). Align the documented registration and ownership experience.
• Resilience samples: IdempotentServiceClient(HttpClient) and the private ServerManager readiness helper / LocalAgentClient ownership wrapper are sample-local surfaces to assess for consistency, not additional package API commitments.

Desired Outcome

• Define and document a consistent host-facing HTTP configuration and ownership model, using named/typed IHttpClientFactory registrations where appropriate.
• Decide which public direct-client entry points should migrate, which should remain as deliberate SDK/typed-client integration points, and how existing callers transition.
• Clearly separate the lifetime of a request/client wrapper, a pooled HTTP message-handler pipeline, and any longer-lived SDK/protocol client.
• Apply consistent configuration guidance for base addresses, authentication handlers, timeouts, cancellation, handler rotation, and disposal without requiring each integration to invent a different application setup.
• Update affected internal wiring, samples, XML/package documentation, and the corresponding public consumer-skill guidance together.
• Record any intentional public API changes in every applicable API baseline and package-compatibility suppression, with migration guidance.
• Add focused lifetime/configuration tests for behavior that changes and run the relevant builds, tests, and formatting checks.
• Retain already-factory-backed internal/typed-client patterns when they satisfy the agreed model; do not replace every HttpClient parameter indiscriminately.

Scope is .NET only. Do not duplicate the DefaultHttpRequestHandler work in #9841 or the declarative DefaultMcpToolHandler work in #9722. Changes to third-party SDK APIs, destination-authorization behavior, or MCP protocol/session semantics are not goals of this alignment task.

Language

.NET

Acknowledgements

• I searched existing issues and did not find a duplicate.
• I will wait for explicit maintainer agreement before starting implementation of a non-trivial change.