Dependency injection¶

Run the complete page example.

Several parts of your app may need the same API client. Registering it with dependency injection lets those parts ask for the interface in their constructors. You can keep the service address, request settings and HTTP handlers together in the app's setup code.

HttpClientFactoryExtensions is a static class that supplies these registration methods to IServiceCollection and IHttpClientBuilder. Refit's integration uses IHttpClientFactory to manage the HTTP handlers behind those clients. This page shows the initial registration, then how to give clients different names or keys.

Install Refit.HttpClientFactory beside Refit. Use AddRefitGeneratedClient<T> with a JSON context for clients that support AOT. This registration binds the interface to Refit's emitted implementation. Keep the reflection registration in the separate section for applications that accept runtime metadata. The context overloads exist on .NET 8 and later.

Register and resolve a generated client¶

1. Choose the context. Use the shared context that registers Person. Refit reads and writes JSON with the context's own options, and it never falls back to reflection.

2. Register the client. Import Microsoft.Extensions.DependencyInjection. Set the service's base address on the returned builder.

3. Resolve the interface and call it. This console example owns and disposes its service provider. An application host owns the provider for a hosted app. The runnable sample also plugs in a local handler, so it runs without a web server.

ServiceCollection services = new();
services.AddRefitGeneratedClient<IClientApi>(SampleJsonContext.Default)
    .ConfigureHttpClient(static client => client.BaseAddress = new Uri("https://api.example.com"));

await using ServiceProvider provider = services.BuildServiceProvider();
IClientApi api = provider.GetRequiredService<IClientApi>();
Person person = await api.ReadAsync(); // person.Name == "Ada"

The API implementation is transient: each resolution can create a new implementation. The factory manages the HTTP handler's lifetime. Configure the returned builder to set the base address, handlers or your app's HTTP resilience pipeline. An unavailable generated implementation fails when the client is resolved.

Register with settings¶

Register a RefitSettings when you need more than JSON, or when you prefer to own the JSON options. Pick the options way when you have JsonSerializerOptions to share, need full control, or want one options object reused elsewhere in your app. The short path needs no options object. The options way makes you assign the TypeInfoResolver yourself and keep the options unchanged after first use. Client creation builds JsonOptions this way.

The settings holder is a singleton: its settings are shared by clients for that registration.

RefitSettings settings = new(new SystemTextJsonContentSerializer(JsonOptions));

services.AddRefitGeneratedClient<IClientApi>(settings)
    .ConfigureHttpClient(static client => client.BaseAddress = new Uri("https://api.example.com"));

To keep your settings and add the context, pass both. That is the bridge. See obtain settings from services.

Distinguish clients with a key¶

A key lets you register the same interface for different destinations or policies. Resolve it with GetRequiredKeyedService<T> and the same key. Refit rejects null keys.

services.AddKeyedRefitGeneratedClient<IClientApi>("eu", SampleJsonContext.Default)
    .ConfigureHttpClient(static client => client.BaseAddress = new Uri("https://eu.api.example.com"));
services.AddKeyedRefitGeneratedClient<IClientApi>("us", SampleJsonContext.Default)
    .ConfigureHttpClient(static client => client.BaseAddress = new Uri("https://us.api.example.com"));

IClientApi europe = provider.GetRequiredKeyedService<IClientApi>("eu");

In a constructor, ask for a keyed client with [FromKeyedServices("eu")] IClientApi api.

The keyed overloads with settings also take an HTTP client name. This registration names the underlying HTTP client regional-people:

services.AddKeyedRefitGeneratedClient<IClientApi>("eu", settings, "regional-people")
    .ConfigureHttpClient(static client => client.BaseAddress = new Uri("https://eu.api.example.com"));

regional-people is the underlying named HTTP client. Omitting a name lets Refit derive one from the interface and key. A service key and an HTTP client name have different jobs: the key selects the DI service; the name selects the factory's HTTP configuration.

Obtain settings from services¶

The settings factory returns settings through the service provider. Refit stores the result in a singleton holder. The factory is not invoked for every HTTP request. Do not capture a scoped token service in that singleton settings object.

services.AddSingleton(settings);
services.AddRefitGeneratedClient<IClientApi>(
    static serviceProvider => serviceProvider.GetRequiredService<RefitSettings>(),
    "people");

SettingsFor<T> carries the nullable settings for one interface. ISettingsFor exposes its read-only Settings property without the generic interface type. Refit registers SettingsFor<T>, not ISettingsFor; register the interface yourself when your code needs it. The constructor stores the supplied settings reference; it does not copy settings.

services.AddSingleton<ISettingsFor>(new SettingsFor<IClientApi>(settings));

SettingsFor<IClientApi> holder = provider.GetRequiredService<SettingsFor<IClientApi>>();
ISettingsFor untypedHolder = provider.GetRequiredService<ISettingsFor>();

Pass a context next to the settings factory to keep your settings and add the context. Refit sets the context on the settings that the factory returns, so their naming policy and converters apply. This registration returns snake_case settings and adds the example's context class, SampleJsonContext. When the factory returns null, Refit uses the context's own options.

services.AddSingleton(RefitSettings.SnakeCase());
services.AddRefitGeneratedClient<IClientApi>(
        SampleJsonContext.Default,
        static serviceProvider => serviceProvider.GetRequiredService<RefitSettings>(),
        "snake-people")
    .ConfigureHttpClient(static client => client.BaseAddress = new Uri("https://api.example.com"));

Resolve authorization per request¶

AddAuthorizationHeaderValueProvider adds a handler that creates a fresh DI scope for each request. Use its service provider to resolve a token service with a scoped lifetime. ITokenService stands for your own service. Its GetTokenAsync method returns the access token as a ValueTask<string>.

services.AddScoped<ITokenService, TokenService>();
services.AddRefitGeneratedClient<IClientApi>(settings)
    .ConfigureHttpClient(static client => client.BaseAddress = new Uri("https://api.example.com"))
    .AddAuthorizationHeaderValueProvider(static (serviceProvider, request, cancellationToken) =>
        serviceProvider.GetRequiredService<ITokenService>().GetTokenAsync(cancellationToken));

The handler runs for every outgoing request. It keeps a declared authorization scheme or uses Bearer when no scheme exists. It replaces an existing token. A null, empty or whitespace result removes the header. It asynchronously disposes the token-service scope before passing the request to the next handler. The delegate receives the request and cancellation token.

Authorization getters and handlers¶

The plain supplied-client example fills a declared scheme only when its token is missing. CreateHttpClient and DI registration also install a handler when AuthorizationHeaderValueGetter is configured. That handler obtains a token whenever an authorization header exists, including a header with an explicit token.

This example counts how often Refit asks for a token.

int calls = 0;
RefitSettings settings = new()
{
    AuthorizationHeaderValueGetter = (request, cancellationToken) =>
    {
        calls++;
        return ValueTask.FromResult("ada-access-token");
    },
};

using HttpClient client = RestService.CreateHttpClient("https://api.example.com", settings);
IClientApi api = RestService.ForGenerated<IClientApi>(client, settings);

await api.AuthorizedAsync(); // calls == 2

The missing-token call asks twice: generated preparation and the handler both invoke the getter. A call that passes its own token asks once:

calls = 0;
await api.ExplicitAsync("caller-token"); // calls == 1, and the request sends "ada-access-token"

The explicit-token call asks once, and the handler replaces the supplied token. This differs from generated preparation's preserve-explicit-token rule. Avoid combining the settings getter with another token provider. Use a plain supplied client with generated preparation when you need that rule, or use the scoped provider when a handler should own authorization for every request.

Reflection registration and existing builders¶

AddRefitClient and AddKeyedRefitClient register the reflection request builder. Install Refit.Reflection and use these only when reflection is acceptable. Their generic overloads carry trimming warnings. Runtime-Type overloads also require dynamic generic construction. The separate reflection executable compiles these calls without claiming Native AOT support.

services.AddRefitClient<IClientApi>(settings)
    .ConfigureHttpClient(static client => client.BaseAddress = new Uri("https://api.example.com"));
services.AddRefitClient(typeof(IClientApi), static _ => null, "runtime-selected");
services.AddKeyedRefitClient<IClientApi>("eu", settings);

The IHttpClientBuilder overloads attach registrations to an existing named HTTP configuration. They preserve its name.

IHttpClientBuilder http = services.AddHttpClient("existing")
    .ConfigureHttpClient(static client => client.BaseAddress = new Uri("https://api.example.com"));
http.AddRefitClient<IClientApi>(settings);
http.AddKeyedRefitClient(typeof(IClientApi), "eu", settings);

There are no generated-registration overloads on IHttpClientBuilder. Start from the service collection's generated registration and configure its returned builder.

Registration overloads¶

Every registration method below returns an IHttpClientBuilder. Generic methods require a class/interface type through where T : class. settings can be null; a settings factory can be null or return null to select defaults. Those defaults do not add your app's generated JSON metadata. With a context, a null factory result selects the context's own options.

Implementation: HttpClientFactoryExtensions.ServiceCollection.cs, HttpClientFactoryExtensions.JsonContext.cs, HttpClientFactoryExtensions.HttpClientBuilder.cs, HttpClientFactoryCore.cs, ScopedAuthorizationHeaderHandler.cs, SettingsFor{T}.cs, and ISettingsFor.cs at Refit SHA 6f0507fa061f1844a8da6ea92e839b622dfc74ef.

Settings factories have type Func<IServiceProvider, RefitSettings?>. Names have type string?. Keys have type object?, but must contain a non-null value. There are no runtime-Type generated DI registrations.