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.
What it registers
Section titled “What it registers”- Kiota: a named
HttpClient,RocketsClient, and the typed clientRocketsClient, built on Kiota’sHttpClientRequestAdapterwith the authentication provider from the container, unless the options configure an authentication (see Authentication). - Refitter:
IRocketsClient, through Refit’sAddRefitGeneratedClient. 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) { … } // Kiotapublic sealed class LaunchService(IRocketsClient rockets) { … } // RefitterThe options
Section titled “The options”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:
- The keys under
Clients:RocketsClient. - Code: the
configureargument ofAddRocketsClient(), and anyservices.Configure<RocketsClientOptions>(…), wherever it is called, in the order they are registered: aConfigureregistered beforeAddRocketsClient()runs before theconfigureargument, one registered after runs after it. - 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));Configuration
Section titled “Configuration”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.
The connection string
Section titled “The connection string”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=valuepairs 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/" } }}Validation
Section titled “Validation”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,Resilienceand its settings,Authentication), or a malformed connection string; - a
BaseAddressthat isn’t an absolutehttporhttpsURI (or, with service discovery, a service-discovery address), or aTimeoutthat isn’t positive; - with service discovery, no service-discovery provider registered by the application;
- an
Authenticationwithout the keys it needs (the keys of another method are ignored), or with no host to send the credentials to (neitherBaseAddressnorAllowedHosts); - a client certificate given by both a path and a thumbprint, a
CertificatePasswordorCertificateKeyPathwithout aCertificatePath, aCertificateStorewithout aCertificateThumbprint, 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.
Resilience
Section titled “Resilience”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:05The 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.
Service discovery
Section titled “Service discovery”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 afterAddServiceDiscoveryCore(). Without any provider, validation fails at startup and says so, whatever theBaseAddress: the service-discovery handler resolves anhttpaddress too; BaseAddressmay be a service-discovery address, such ashttps+http://rockets;- a client without a
BaseAddresscallshttps+http://<ClientName>, so its endpoints come fromServices:<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.
Configuring the client further
Section titled “Configuring the client further”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.
Authentication
Section titled “Authentication”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.
Configured authentication
Section titled “Configured 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
RefitSettingsstill come from the container, since they carry Refit’s serializers. ConfigureRequestAdapterandConfigureRefitSettingsstill have the last word.
Which hosts get the credentials
Section titled “Which hosts get the credentials”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.
Client credentials
Section titled “Client credentials”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.
The token cache
Section titled “The token cache”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.
Private key JWT
Section titled “Private key JWT”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.
From the container
Section titled “From the container”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
IAuthenticationProviderkeyed"RocketsClient", else an unkeyed one, elseAnonymousAuthenticationProvider. AnIParseNodeFactoryand anISerializationWriterFactoryare looked up the same way, and Kiota’s defaults are used without one. - Refitter:
RefitSettingskeyed"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 onlybuilder.Services.AddKeyedSingleton<IAuthenticationProvider>( "RocketsClient", (services, _) => new BaseBearerTokenAuthenticationProvider(services.GetRequiredService<IAccessTokenProvider>()));
// Refitter: settings for IRocketsClient onlybuilder.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")]).
The last word
Section titled “The last word”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’sHttpClient. Return another adapter, say with an authentication provider of the library’s own. - Refitter:
ConfigureRefitSettings, given the settings from the container, ornull. Return settings with a serializer or a handler set.
builder.Services.AddRocketsClient(options => options.ConfigureRefitSettings = (services, settings) => new RefitSettings { ContentSerializer = mySerializer });Client certificate (mTLS)
Section titled “Client certificate (mTLS)”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 itsCertificatePasswordif it has one. - A PEM certificate with its key in
CertificateKeyPath, the key encrypted withCertificatePasswordor 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.
Without the registration
Section titled “Without the registration”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 ownvar refit = RestService.For<IRocketsClient>(httpClient);With Dovetail
Section titled “With Dovetail”A Dovetail joint is one more caller of the registration. See With Dovetail.