Skip to content

Registration

Every client gets a registration: a public extension method on IServiceCollection, written next to the generated code. For a client named RocketsClient it is:

public static IHttpClientBuilder AddRocketsClient(this IServiceCollection services, Action<RocketsClientOptions>? configure = null);

It is in the client’s namespace, in a static class named RocketsClientServiceCollectionExtensions, next to the client’s options, RocketsClientOptions. Both are public, so an application can register and configure a client that a library it references generated. The project of the client writes no code of its own.

  • Kiota: a named HttpClient, RocketsClient, and the typed client RocketsClient, built on Kiota’s HttpClientRequestAdapter with the authentication provider from the container, unless the options configure an authentication (see Authentication).
  • Refitter: IRocketsClient, through Refit’s AddRefitGeneratedClient. Refit’s source generator writes the implementation at build time, so there is no reflection.
  • Both: the options, RocketsClientOptions, with their validation, which runs when the host starts.

Resolve the client from the container, or inject it:

public sealed class LaunchService(RocketsClient rockets) { … } // Kiota
public sealed class LaunchService(IRocketsClient rockets) { … } // Refitter

RocketsClientOptions holds what the registration applies to the client each time its HttpClient is created. Generated code fills it from configuration, without the reflection binder, so it is safe for trimming and AOT. The registration reads it through IOptionsMonitor<RocketsClientOptions>, so a configuration reload applies when the client’s handlers rotate.

The options are filled from three sources, from lowest to highest:

  1. The keys under Clients:RocketsClient.
  2. Code: the configure argument of AddRocketsClient(), and any services.Configure<RocketsClientOptions>(…), wherever it is called, in the order they are registered: a Configure registered before AddRocketsClient() runs before the configure argument, one registered after runs after it.
  3. The client’s connection string, applied as a post-configuration, so it wins over everything else.

Code that must win over the connection string uses services.PostConfigure<RocketsClientOptions>(…).

builder.Services.AddRocketsClient(options => options.Timeout = TimeSpan.FromSeconds(10));

The section’s path is an internal constant on the registration class, RocketsClientServiceCollectionExtensions.SectionKey.

{
"Clients": {
"RocketsClient": {
"BaseAddress": "https://rockets.example.com/",
"Timeout": "00:00:30",
"DefaultRequestHeaders": {
"X-Api-Version": "2"
},
"Resilience": true
}
}
}
Key Type Effect
ConnectionString string The client’s connection string.
BaseAddress absolute URI HttpClient.BaseAddress, http or https. Alias Endpoint. Without one, Kiota uses the document’s first server, Refit fails when called, unless service discovery is on.
Timeout TimeSpan HttpClient.Timeout, written as hh:mm:ss in the invariant culture (00:00:00.5 is half a second). Without one, the HttpClient default of 100 seconds stays.
DefaultRequestHeaders string to string map Each entry is added to HttpClient.DefaultRequestHeaders, so every request sends it. Not in a connection string.
Resilience bool or object true keeps the standard resilience handler (AddStandardResilienceHandler()): retries, timeouts and a circuit breaker; an object sets its settings. It is read only when the project references Microsoft.Extensions.Http.Resilience.
AllowedHosts array of hosts More hosts than the BaseAddress host that may receive the client’s credentials. In a connection string, a comma-separated list.
Authentication method How the client authenticates: None (the default, the container decides), ApiKey, Bearer or Basic (configured).
ApiKey string The key of ApiKey. Alias Key.
ApiKeyHeader string The header ApiKey sends the key in, X-Api-Key by default.
ApiKeyQuery string The query parameter ApiKey sends the key in, instead of a header.
Token string The token of Bearer. In code, TokenProvider can give it instead.
Username string The user name of Basic.
Password string The password of Basic.
CertificatePath path A client certificate, a PKCS#12 (.pfx, .p12) or PEM file.
CertificatePassword string The password of the PKCS#12 file, or of the encrypted PEM key.
CertificateKeyPath path The PEM private key, when CertificatePath is a PEM certificate without its key.
CertificateThumbprint string A client certificate in a certificate store, instead of a file.
CertificateStore <location>/<name> The store of CertificateThumbprint: CurrentUser/My (the default) or LocalMachine/My, say.

Keys are case-insensitive. A key that isn’t set leaves the HttpClient as it is. Any configuration source works: the environment variable Clients__RocketsClient__DefaultRequestHeaders__X-Api-Version sets a header, for example.

A client can take its settings as one SqlClient-style string, as a database does. It is read from Clients:RocketsClient:ConnectionString (RocketsClientServiceCollectionExtensions.ConnectionStringKey) when that key exists, else from ConnectionStrings:RocketsClient, which is where Aspire and most hosts put connection strings. The first one found is used, and the two are never merged.

{
"ConnectionStrings": {
"RocketsClient": "Endpoint=https://rockets.example.com/;Timeout=00:00:30"
}
}

It has the syntax of DbConnectionStringBuilder:

  • key=value pairs separated by ;. Whitespace around keys and unquoted values is trimmed.
  • A value that contains ;, or leading or trailing spaces, is quoted with ' or ". A doubled quote stands for itself: Endpoint='https://rockets.example.com/?a=1;b=2'.
  • An unquoted value may contain =.

It takes the keys of the table above, except ConnectionString and DefaultRequestHeaders, and the resilience settings, as MaxRetryAttempts, AttemptTimeout and the like. The parser is stricter than DbConnectionStringBuilder: an unknown key and a key given twice (an alias with its key, Endpoint and BaseAddress, too) are errors.

When an application already has a connection string named after the client for something else, a database say, set Clients:RocketsClient:ConnectionString to an empty value. The client then reads no connection string:

{
"ConnectionStrings": { "RocketsClient": "Data Source=db;Initial Catalog=rockets" },
"Clients": { "RocketsClient": { "ConnectionString": "", "BaseAddress": "https://rockets.example.com/" } }
}

The registration validates the options with a generated IValidateOptions<RocketsClientOptions>, and asks for it at startup (ValidateOnStart). Under a host, a bad client stops the host from starting, with an OptionsValidationException that lists every problem. With a bare ServiceCollection, the same exception is thrown when the client is first created.

It fails on:

  • an unknown key in the connection string, or a key given twice there (an alias with its key too);
  • a value that doesn’t parse (Timeout, Resilience and its settings, Authentication), or a malformed connection string;
  • a BaseAddress that isn’t an absolute http or https URI (or, with service discovery, a service-discovery address), or a Timeout that isn’t positive;
  • with service discovery, no service-discovery provider registered by the application;
  • an Authentication without the keys it needs (the keys of another method are ignored), or with no host to send the credentials to (neither BaseAddress nor AllowedHosts);
  • a client certificate given by both a path and a thumbprint, a CertificatePassword or CertificateKeyPath without a CertificatePath, a CertificateStore without a CertificateThumbprint, a file that doesn’t exist, and a certificate that doesn’t load with its private key (a wrong password, say).

Under Clients:RocketsClient the keys are lenient, as configuration binding is: a key the client doesn’t read is ignored, of a key and its alias (Endpoint and BaseAddress) the later one wins, and a key that must be a value but holds an object is ignored with a warning, logged when the application registers an ILoggerFactory.

The messages name the source (Clients:RocketsClient:Timeout, ConnectionStrings:RocketsClient) and the key, never a value, so they are safe to log even when a value is a secret. In a connection string, an unknown key is named only when it reads as one (letters, digits and spaces, not followed by another =): an unquoted secret holding a ;, Key=ab;cd== say, is reported as an unrecognised part, without its text.

Chirograph adds no resilience package. When the project references Microsoft.Extensions.Http.Resilience (directly or through another package or project), the build sees it among the resolved references and writes the resilience code into the registration: it calls AddStandardResilienceHandler() on the client’s builder, and takes the handler out again when the client’s handlers are built unless Resilience is true. Without the package the registration has no such code, it compiles, and Resilience is ignored.

Resilience is either true or false, or an object of the handler’s settings, named as HttpStandardResilienceOptions names them (the standard resilience handler). An object keeps the handler, unless its Enabled is false, and a setting it leaves out keeps the handler’s default:

{
"Clients": {
"RocketsClient": {
"Resilience": {
"Retry": { "MaxRetryAttempts": 5, "BackoffType": "Exponential", "Delay": "00:00:01" },
"AttemptTimeout": { "Timeout": "00:00:05" },
"TotalRequestTimeout": { "Timeout": "00:01:00" },
"CircuitBreaker": { "FailureRatio": 0.2, "SamplingDuration": "00:00:30" }
}
}
}
}
Setting Type Default
Enabled bool true
RateLimiter:DefaultRateLimiterOptions:PermitLimit int 1000
RateLimiter:DefaultRateLimiterOptions:QueueLimit int 0
RateLimiter:DefaultRateLimiterOptions:QueueProcessingOrder OldestFirst, NewestFirst OldestFirst
TotalRequestTimeout:Timeout TimeSpan 00:00:30
Retry:MaxRetryAttempts int 3
Retry:BackoffType Constant, Linear, Exponential Exponential
Retry:UseJitter bool true
Retry:Delay TimeSpan 00:00:02
Retry:MaxDelay TimeSpan none
Retry:ShouldRetryAfterHeader bool true
CircuitBreaker:FailureRatio number, 0 to 1 0.1
CircuitBreaker:MinimumThroughput int 100
CircuitBreaker:SamplingDuration TimeSpan 00:00:30
CircuitBreaker:BreakDuration TimeSpan 00:00:05
AttemptTimeout:Timeout TimeSpan 00:00:10

The registration reads them without reflection into RocketsClientOptions.ResilienceOptions, so code can change them too (AddRocketsClient(o => o.ResilienceOptions.Retry.MaxRetryAttempts = 5)), and hands them to the handler whenever the options are filled, when configuration reloads too. A value that doesn’t parse fails validation; Microsoft.Extensions.Http.Resilience checks the rest when the host starts (MaxRetryAttempts at least 1, an AttemptTimeout shorter than the TotalRequestTimeout, a SamplingDuration at least twice the AttemptTimeout, and so on). To add a handler of your own, chain on the builder the registration returns.

A connection string takes the same settings, as keys named after them: the last name of each setting (MaxRetryAttempts, Delay, FailureRatio, PermitLimit, and so on), except the two timeouts, which are TotalRequestTimeout and AttemptTimeout since Timeout is the client’s. They win over the keys of the section, and a setting turns the handler on unless the connection string also sets Resilience:

Endpoint=https://rockets.example.com/;MaxRetryAttempts=5;AttemptTimeout=00:00:05

The code that reads the settings is written once for the project, ChirographResilience.g.cs next to the clients’ folders in obj, and shared by every client: only when the project references Microsoft.Extensions.Http.Resilience.

Chirograph adds no service-discovery package either. When the project references Microsoft.Extensions.ServiceDiscovery (directly, or through another package or project such as an Aspire service-defaults project), the build sees it among the resolved references and writes the service-discovery code into the registration:

  • it calls AddServiceDiscovery() on the client’s builder, after the authentication handler;
  • it registers no provider: the application calls AddServiceDiscovery() on the services (an Aspire service-defaults project does), which adds the configuration provider (Services:<name>) and the pass-through provider, or registers its own after AddServiceDiscoveryCore(). Without any provider, validation fails at startup and says so, whatever the BaseAddress: the service-discovery handler resolves an http address too;
  • BaseAddress may be a service-discovery address, such as https+http://rockets;
  • a client without a BaseAddress calls https+http://<ClientName>, so its endpoints come from Services:<ClientName>, or from the platform.
{
"Services": { "RocketsClient": { "https": ["https://10.0.0.5:8443/"] } }
}
builder.Services.AddServiceDiscovery();
builder.Services.AddRocketsClient();

Without the package, a client without a BaseAddress behaves as before, and a service-discovery address fails validation.

The authentication handler runs before the service-discovery handler, so the host check compares the logical host, rockets in https+http://rockets, not the endpoint it resolves to.

The registration returns the IHttpClientBuilder, so everything IHttpClientFactory offers chains on it: handlers, resilience, lifetimes, and a base address of your own that wins over the configuration.

builder.Services
.AddRocketsClient()
.AddHttpMessageHandler<BearerTokenHandler>()
.AddStandardResilienceHandler();

Chirograph adds a handler itself only when Authentication asks for one, and resilience only when Resilience does. Handlers chained on the builder come after the authentication handler, so they see the credentials.

A client authenticates one of two ways. With Authentication set to a method, configuration gives the credentials and a generated handler sends them. With None, the default, the container gives the client its authentication.

Authentication Keys Sends
ApiKey ApiKey (alias Key), and ApiKeyHeader (default X-Api-Key) or ApiKeyQuery (a query parameter name) The key in the header, or in the query.
Bearer Token, or TokenProvider in code Authorization: Bearer <token>.
Basic Username, Password Authorization: Basic, the two in UTF-8.

ClientCredentials and PrivateKeyJwt, and the four Azure methods, are more methods, which the OpenApiClient item declares: see Client credentials, Private key JWT and Azure.

{
"ConnectionStrings": {
"RocketsClient": "Endpoint=https://rockets.example.com/;Authentication=ApiKey;Key=abc123"
}
}

The keys of a method other than the one chosen are an error, so a token left over from another setup can’t be sent by mistake. TokenProvider is asked for the token on each request that gets it, so a token that expires is fetched again by the provider, which caches it as it needs:

builder.Services.AddRocketsClient(options =>
{
options.Authentication = RocketsClientAuthentication.Bearer;
options.TokenProvider = (services, cancellationToken) => services.GetRequiredService<ITokenSource>().GetTokenAsync(cancellationToken);
});

The handler is added to the client’s HttpClient, so Kiota and Refit go through the same pipeline. With Authentication set:

  • Kiota: the adapter gets AnonymousAuthenticationProvider, not the container’s provider, so nothing sets the credentials twice.
  • Refitter: the RefitSettings still come from the container, since they carry Refit’s serializers.
  • ConfigureRequestAdapter and ConfigureRefitSettings still have the last word.

The handler adds the credentials only to a request for the BaseAddress host, on its port, or for a host in AllowedHosts. An entry of AllowedHosts that is a host alone allows each of its ports; host:port allows that port only. A Kiota next-link to another host goes without them.

The handler also follows redirects in place of the primary handler (it turns the primary handler’s AllowAutoRedirect off, and follows as many as that allowed), so each hop is checked the same way: a redirect to another host goes without the credentials, whichever header or query parameter carries them.

With service discovery, the host is the logical one, and the endpoint it resolves to gets the credentials as well. A relative redirect resolves against the logical address, so it is resolved again and keeps the credentials. A redirect to another host still goes without them. A redirected request never carries the Host header of the first one.

A client with an Authentication needs a host to send the credentials to: a BaseAddress, or AllowedHosts. With service discovery, the default https+http://<ClientName> is one.

ClientCredentials gets an OAuth access token with the client-credentials grant and sends it as Authorization: Bearer <token>, through Duende.AccessTokenManagement 4.x. The OpenApiClient item must declare it, because it needs that package (the declaration allows PrivateKeyJwt too):

<OpenApiClient Include="openapi/rockets.json" Generator="Kiota" ClientName="RocketsClient" Authentication="ClientCredentials" />

The metadata adds a reference to Duende.AccessTokenManagement (the version of ChirographDuendeAccessTokenManagementVersion, unless the project references the package itself) and writes the code that uses it. Without it, there is neither, and configuration that names the method fails validation with a message that names the metadata to set.

Key Meaning
TokenEndpoint The token endpoint, an absolute http or https URI. Or:
Authority An absolute https URI whose discovery document (/.well-known/openid-configuration) gives the token endpoint.
ClientId The client id. Required.
ClientSecret The client secret. Required. Keep it in user secrets or a vault, not in appsettings.json.
Scope The scopes to ask for, space-separated. Optional.
Resource The resource to ask for (RFC 8707). Optional.
ClientCredentialStyle Header (the default) sends the id and secret as HTTP Basic authentication; Body sends them in the token request.
{
"ConnectionStrings": {
"RocketsClient": "Endpoint=https://rockets.example.com/;Authentication=ClientCredentials;Authority=https://login.example.com/;ClientId=rockets-app;ClientSecret=…;Scope=rockets.read"
}
}

The registration configures a Duende client-credentials client named after the client (RocketsClient) from the options, and the authentication handler sets its token, so the host check applies to it as to the other methods. Duende caches the token and fetches a new one shortly before it expires (its CacheLifetimeBuffer, 60 seconds by default), so one token serves every request until then. A refresh_token in the response isn’t used: RFC 6749 §4.4.3 says the server shouldn’t send one.

With Authority, the discovery document is read on the first token request, not at startup, and cached (Duende.IdentityModel’s DiscoveryCache). Startup only checks that Authority is an absolute https URI, so a host starts without the network. The discovery document and the token request go through Duende’s back-channel HttpClient (ClientCredentialsTokenManagementDefaults.BackChannelHttpClientName): configure a proxy or a certificate for both there.

A token request that fails fails the call with an HttpRequestException that gives the server’s error, such as invalid_client.

Duende keeps tokens in a HybridCache. Chirograph registers none: Duende’s registration adds the default one, in memory. To keep them in FusionCache (2.x, which adapts itself to HybridCache), register it for the whole application:

using ZiggyCreatures.Caching.Fusion;
builder.Services.AddFusionCache().AsHybridCache();

or for the tokens only, keyed with Duende’s ServiceProviderKeys.ClientCredentialsTokenCache:

using Duende.AccessTokenManagement;
using ZiggyCreatures.Caching.Fusion;
builder.Services.AddFusionCache().AsKeyedHybridCache(ServiceProviderKeys.ClientCredentialsTokenCache);

The cache key is Duende’s: <CacheKeyPrefix>::RocketsClient::<hashed scope>::<hashed resource>. A distributed cache behind HybridCache shares the tokens across instances; encrypt them there if the cache is shared (see Duende’s client credentials docs).

Duende doesn’t claim compatibility with native AOT: a native publish of a client that declares ClientCredentials warns about Microsoft.Extensions.Caching.Hybrid’s default JSON serializer (its token cache), and works. A client that doesn’t declare it adds no package and no warning.

PrivateKeyJwt is ClientCredentials with a client assertion (private_key_jwt, RFC 7523) in place of the secret: the client proves who it is with a short-lived JWT signed by its certificate. The ClientCredentials declaration on the OpenApiClient item allows it. It takes the keys of ClientCredentials without ClientSecret and ClientCredentialStyle, plus a certificate, given with the certificate keys:

{
"Clients": {
"RocketsClient": {
"BaseAddress": "https://rockets.example.com/",
"Authentication": "PrivateKeyJwt",
"Authority": "https://login.example.com/",
"ClientId": "rockets-app",
"CertificatePath": "/run/secrets/rockets-signing.pfx",
"CertificatePassword": "…",
"Scope": "rockets.read"
}
}
}

The assertion has iss and sub set to ClientId, aud set to the token endpoint (the configured one, or the one the discovery document of Authority gives), a random jti, and exp five minutes ahead. It is signed through Microsoft.IdentityModel.JsonWebTokens, which Duende brings: RS256 with an RSA key, ES256, ES384 or ES512 with an EC key. The certificate is loaded for each assertion, and Duende asks for one only when it requests a token, so a renewed file is read on the next token request. Startup checks that a certificate is given, and that it loads with its private key. A ClientSecret alongside fails validation.

A certificate has one role: the one PrivateKeyJwt signs with is not also presented for mutual TLS.

The assertion comes from an IClientAssertionService, registered keyed with the client’s name ("RocketsClient"). Duende asks the unkeyed IClientAssertionService for the assertion of each of its clients; the registration makes that one hand each client to the service keyed with its name, and any other to the service registered before it (Duende’s, which makes none, or the application’s). An IClientAssertionService of the application’s own registered after AddRocketsClient() would replace that one, so no assertion would be made: validation fails at startup and says to register it before, where it is kept for the other clients.

The Azure methods get a Microsoft Entra ID token from an Azure.Identity credential and send it as Authorization: Bearer <token>. The OpenApiClient item declares them with Azure, which adds a reference to Azure.Identity (the version of ChirographAzureIdentityVersion, unless the project references the package itself) and writes the code that uses it:

<OpenApiClient Include="openapi/rockets.json" Generator="Kiota" ClientName="RocketsClient" Authentication="Azure" />
Authentication Credential Keys
AzureDefault DefaultAzureCredential Scope; optional TenantId, and ClientId (a user-assigned or workload identity)
AzureManagedIdentity ManagedIdentityCredential Scope; optional ClientId, a user-assigned identity (system-assigned without)
AzureWorkloadIdentity WorkloadIdentityCredential Scope; optional TenantId and ClientId (else the platform’s variables)
AzureServicePrincipal ClientSecretCredential, or ClientCertificateCredential Scope, TenantId, ClientId, and ClientSecret or the certificate keys

Scope is the scopes to ask for, space-separated: api://rockets/.default, say. TenantId is a tenant id or a domain.

{
"ConnectionStrings": {
"RocketsClient": "Endpoint=https://rockets.example.com/;Authentication=AzureManagedIdentity;Scope=api://rockets/.default"
}
}

The client has one credential, made from the options the first time a token is asked for, and made again when the options are reloaded. The authentication handler asks it for a token on each request, so the host check applies; the credential caches the token and gets a new one before it expires. Startup checks the keys only: it asks Azure for nothing. A credential that can’t get a token fails the call with Azure.Identity’s AuthenticationFailedException (or CredentialUnavailableException).

AzureServicePrincipal takes ClientSecret or a certificate, given with the certificate keys, not both. The certificate then signs the credential’s assertions, and is not also presented for mutual TLS.

A TokenCredential registered keyed with the client’s name is used instead of the one the method makes, for a credential Chirograph doesn’t make (AzureCliCredential, a ChainedTokenCredential) or a fake one in tests. The keys of the method are still checked, so pair it with AzureDefault, which needs only Scope:

builder.Services.AddKeyedSingleton<TokenCredential>("RocketsClient", new AzureCliCredential());

A native AOT publish of a client that declares Azure reports no trimming or AOT warnings.

With Authentication set to None, when the client is created, the registration takes its authentication from the container, under the key of the client’s name first:

  • Kiota: an IAuthenticationProvider keyed "RocketsClient", else an unkeyed one, else AnonymousAuthenticationProvider. An IParseNodeFactory and an ISerializationWriterFactory are looked up the same way, and Kiota’s defaults are used without one.
  • Refitter: RefitSettings keyed "RocketsClient", else unkeyed ones, else none (Refit’s defaults).

A provider keyed with another client’s name is not this client’s. The application registers them, so a client that a library generated gets its authentication from the application that uses it:

// Kiota: a bearer token for RocketsClient only
builder.Services.AddKeyedSingleton<IAuthenticationProvider>(
"RocketsClient",
(services, _) => new BaseBearerTokenAuthenticationProvider(services.GetRequiredService<IAccessTokenProvider>()));
// Refitter: settings for IRocketsClient only
builder.Services.AddKeyedSingleton(
"RocketsClient",
(services, _) => new RefitSettings
{
AuthorizationHeaderValueGetter = (request, cancellationToken) =>
services.GetRequiredService<ITokenSource>().GetTokenAsync(cancellationToken),
});
builder.Services.AddRocketsClient();

Refit’s AuthorizationHeaderValueGetter fills an Authorization header that the operation declares ([Headers("Authorization: Bearer")]).

A delegate on the options decides what the client uses at last. It gets what the container gave; without it, the client uses that.

  • Kiota: ConfigureRequestAdapter, given the adapter built over the client’s HttpClient. Return another adapter, say with an authentication provider of the library’s own.
  • Refitter: ConfigureRefitSettings, given the settings from the container, or null. Return settings with a serializer or a handler set.
builder.Services.AddRocketsClient(options =>
options.ConfigureRefitSettings = (services, settings) => new RefitSettings { ContentSerializer = mySerializer });

A client can present a certificate to the server, for mutual TLS, whatever its Authentication, None included, unless PrivateKeyJwt or AzureServicePrincipal signs with it. Give it as a file:

{
"Clients": {
"RocketsClient": {
"BaseAddress": "https://rockets.example.com/",
"CertificatePath": "/run/secrets/rockets-client.pfx",
"CertificatePassword": "…"
}
}
}
  • A PKCS#12 file (.pfx, .p12), with its CertificatePassword if it has one.
  • A PEM certificate with its key in CertificateKeyPath, the key encrypted with CertificatePassword or not.
  • A PEM file that holds both the certificate and its key.

Or as a certificate in a store: CertificateThumbprint, in CertificateStore (CurrentUser/My unless it says otherwise). The keys work in a connection string too: Endpoint=https://rockets.example.com/;CertificatePath=/run/secrets/rockets-client.pfx;CertificatePassword=….

The registration puts the certificate on the client’s primary handler (ConfigurePrimaryHttpMessageHandler), the SocketsHttpHandler or HttpClientHandler the factory made, not in a DelegatingHandler. It loads it again each time the handler is made, so a renewed file is picked up when the handlers rotate. The certificate is checked at startup, with the rest of the options: it must load, with its private key.

ConfigurePrimaryHttpMessageHandler with a handler of your own on the builder AddRocketsClient() returns (or a RefitSettings HttpMessageHandlerFactory) replaces the handler that carries the certificate. The overload that changes the handler, ConfigurePrimaryHttpMessageHandler((handler, services) => …), keeps it.

A generated client is an ordinary class or interface. Create one from an HttpClient, for example against a test server:

var kiota = new RocketsClient(new HttpClientRequestAdapter(new AnonymousAuthenticationProvider(), httpClient: httpClient)); // or a provider of your own
var refit = RestService.For<IRocketsClient>(httpClient);

A Dovetail joint is one more caller of the registration. See With Dovetail.