FclEx.Http 2.4.0

FclEx.Http

HTTP, HTML, cookie, authentication, and web-client helpers for FclEx.

What Is Included

• HttpService, HttpClientOptions, request handlers, retry helpers, and download/upload utilities.
• HTTP action abstractions for JSON, JSONP, XML, HTML, and HTML file workflows.
• AngleSharp helpers for parsing and querying HTML documents.
• Cookie parsing and simple cookie models.
• OAuth client-credentials token provider and authentication handler.
• MIME type lookup helpers.
• User-client abstractions for authenticated web clients and session-aware workflows.
• Form data models and helpers for web form submission.
• Source-generated HttpClientBuilder helper overloads.

Usage Notes

• The action types wrap HTTP responses into OperationResult<T>.
• When implementing custom actions, keep parsing and validation errors inside the action pipeline so callers can handle them consistently.
• ASP.NET Core server-side helpers live in FclEx.AspNetCore.

Named Access Token Providers

Register a client-credentials provider for each authority and client identity. The overload without a name registers the default provider under the empty name.

services.AddHttpClient(nameof(ClientCredentialsTokenProvider));

services.AddClientCredentialsTokenProvider("captcha-a", options =>
{
    options.Authority = authA.Authority;
    options.ClientId = authA.ClientId;
    options.ClientSecret = authA.ClientSecret;
});

services.AddClientCredentialsTokenProvider("captcha-b", options =>
{
    options.Authority = authB.Authority;
    options.ClientId = authB.ClientId;
    options.ClientSecret = authB.ClientSecret;
});

services.AddHttpClient("captcha-api-a")
    .AddAuthenticationHandler("captcha-a", ["captcha.read"]);

services.AddHttpClient("captcha-api-b")
    .AddAuthenticationHandler("captcha-b", ["captcha.read"]);

The name passed to AddAuthenticationHandler selects the token provider; it is independent of the HttpClient name. Multiple clients can share a provider name, and their handlers can request different scopes. Each provider instance retains its discovery-document and access-token caches for the lifetime of the service provider. Re-registering a name replaces that name's previous provider factory or client-credentials configuration; registrations are not merged. The handler overload without a provider name selects the default provider.

AddAccessTokenProvider<TProvider> registers a custom IAccessTokenProvider in the same named registry. Its overload without a name targets the default provider. The corresponding TryAddAccessTokenProvider<TProvider> overloads, with or without a name, keep an existing registration; when no name is supplied they target the default provider.

Each AddClientCredentialsTokenProvider and AddClientCredentialsTokenProviderBy<TDependency> overload also has a corresponding TryAdd form. These keep an existing registration with the same name and do not invoke the options callback or resolve the dependency for the skipped registration. Names are compared ordinally and are case-sensitive. Registration callbacks run lazily, the first time that name is requested, and the selected provider is cached for the service-provider lifetime.

Client-credentials registrations also support options callbacks that receive IServiceProvider, options factories, and AddClientCredentialsTokenProviderBy<TDependency> overloads that resolve a registered dependency. Those provider-registration callbacks execute from the root service provider, so the dependency and any services they resolve must not be scoped. If scoped services are needed to configure handler options, use AddAuthenticationHandlerBy<TDependency>; its dependency is resolved from the HTTP handler scope.

For example, a custom provider can be registered and selected in the same way:

services.AddAccessTokenProvider<MyAccessTokenProvider>("custom", provider =>
    new MyAccessTokenProvider(provider.GetRequiredService<ITokenClient>()));

services.AddHttpClient("custom-api")
    .AddAuthenticationHandler("custom", ["api.read"]);

The registration factory owns the provider instance. Do not return an instance that is also registered for disposal by DI; if a provider implements IDisposable, it is disposed when the service provider is disposed. Register one provider per credential configuration and let the named factory cache it, so its discovery and token caches remain effective.

Client-credentials providers send discovery and token requests through the HTTP client named ClientCredentialsTokenProvider. Configure that named client if those requests need custom transport settings such as a proxy or timeout.

HTML Context Lifetime

Use HtmlActionContext.Document to access the parsed document; Element is obsolete and can be replaced with Document.DocumentElement. The default HTML action pipeline disposes the context after result conversion, including error and exception paths. Materialize values during GetResult; do not return document nodes or deferred queries over them. When constructing a context or calling CreateContext directly, dispose each successfully created context after use. Context copies share the same document. CSS selectors are evaluated against the document, so selectors such as html and :root can select the root element.