Settings¶

Run the complete page example.

Calls to the same service often need the same rules: how to write JSON, format a date, add an access token, or handle a failed reply. RefitSettings keeps those choices in one place so you can apply them across a client.

Set up these rules before creating the client. Start with the serializer your service needs, then change the other settings when a request calls for them.

Set the serializer and formatters¶

1. Prepare the JSON serializer. Build it from the JSON context described in client creation.

2. Choose the settings constructor. The serializer is required in these constructor overloads. A null formatter selects the default formatter. Each line below is a separate choice; pick the one you need.

SystemTextJsonContentSerializer serializer = SystemTextJsonContentSerializer.ForContext(SampleJsonContext.Default);

RefitSettings serializerOnly = new(serializer);
RefitSettings values = new(serializer, new DefaultUrlParameterFormatter());
RefitSettings forms = new(serializer, null, new DefaultFormUrlEncodedParameterFormatter());
RefitSettings keys = new(serializer, null, null, new CamelCaseUrlParameterKeyFormatter()); // keys "PageSize" as "pageSize"
RefitSettings initialized = new() { ContentSerializer = serializer };

3. Pass the settings to client creation or registration. Reuse the configured serializer. The parameterless constructor creates a System.Text.Json serializer with Refit's defaults and no context. Add a context before using that serializer in an AOT app. The next section shows how. A null serializer passed to a constructor throws ArgumentNullException.

A production client commonly keeps one RefitSettings instance with its generated JSON context and assigns an asynchronous ExceptionFactory when the service has a typed error envelope. Refit awaits this factory. Keep its asynchronous work asynchronous: do not use .Result or .Wait(), which can block a thread and can deadlock code that has a synchronization context. The factory returns an exception for that envelope or null to suppress the HTTP error.

The reflection builder retains the serializer supplied when it is constructed. Other settings may be read when a request is built. Changing shared settings during calls does not provide a uniform reconfiguration contract. Prepare a different settings instance when clients need different rules.

Add a JSON context to settings¶

Settings hold the serializer, so settings hold the JSON choices. You can give the serializer a context three ways.

• Build the options yourself. Assign the context as the TypeInfoResolver of your own options, wrap them in a serializer and pass new RefitSettings(serializer). Client creation shows this. Pick this 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. This way makes you assign the TypeInfoResolver yourself and keep the options unchanged after first use.
• Build settings from a context. RefitSettings.ForJsonContext(context) makes settings that use the context's own options. Reflection-based JSON is off.
• Add a context to settings you have. settings.UseJsonContext(context) is the bridge. It keeps your serializer's naming policy, converters and other options, adds the context, and returns the same settings. It throws InvalidOperationException when the serializer is not a SystemTextJsonContentSerializer.

RefitSettings shortcut = RefitSettings.ForJsonContext(SampleJsonContext.Default);

RefitSettings camel = RefitSettings.CamelCase().UseJsonContext(ClientNamingJsonContext.Default);

Each method takes allowReflectionFallback too. Pass true to let a type the context does not list use reflection-based JSON. That is not trim or Native AOT safe. The same settings also work with the reflection creation methods, such as RestService.For(hostUrl, settings). See choose whose settings apply. These APIs exist on .NET 8 and later.

Align naming rules with generated JSON¶

CamelCase(), SnakeCase() and KebabCase() return settings that align the JSON naming policy and the URL key formatter. Add a context with UseJsonContext. The settings' naming policy wins over the naming in the context's own JsonSourceGenerationOptions, so one context serves all three. This context registers a model with one property, ClientNamingInput(int PageSize).

[JsonSourceGenerationOptions(JsonSerializerDefaults.Web)]
[JsonSerializable(typeof(ClientNamingInput))]
internal sealed partial class ClientNamingJsonContext : JsonSerializerContext;

The snake_case settings below send PageSize as page_size in both the URL and the JSON body.

RefitSettings settings = RefitSettings.SnakeCase().UseJsonContext(ClientNamingJsonContext.Default);
string key = settings.UrlParameterKeyFormatter.Format("PageSize"); // "page_size"
using HttpContent body = settings.ContentSerializer.ToHttpContent(new ClientNamingInput(5));
string json = await body.ReadAsStringAsync(cancellationToken); // {"page_size":5}

CamelCase() gives pageSize and KebabCase() gives page-size in the same places.

If you build the options yourself, give each convention its own context. Each context states its naming in JsonSourceGenerationOptions, and you assign it as the TypeInfoResolver of options you own. A camelCase or kebab-case context differs only in its PropertyNamingPolicy.

[JsonSourceGenerationOptions(JsonSerializerDefaults.Web, PropertyNamingPolicy = JsonKnownNamingPolicy.SnakeCaseLower)]
[JsonSerializable(typeof(ClientNamingInput))]
internal sealed partial class ClientSnakeJsonContext : JsonSerializerContext;

JsonSerializerOptions options = new(ClientSnakeJsonContext.Default.Options) { TypeInfoResolver = ClientSnakeJsonContext.Default };
RefitSettings settings = RefitSettings.SnakeCase();
settings.ContentSerializer = new SystemTextJsonContentSerializer(options);
// URL key "page_size", JSON body {"page_size":5}

Register each request, reply and container type your real API uses. See JSON contexts for combining and reusing registrations. An explicit AliasAs name wins over a naming rule. An explicit serializer property name can also control flattened query keys. See query formatters.

URL resolution¶

UrlResolution defaults to RefitLegacy. Legacy mode requires a leading slash and prepends the base address path. For example, base https://service.example/api/ and route /people produce /api/people.

Rfc3986 uses standard URI resolution. A leading slash replaces the base path: /people produces https://service.example/people. With a base ending in /api/, people produces /api/people. With a base ending in /api, people replaces the final path segment and produces /people. Keep the trailing slash when the base path represents a folder to append to.

Check buffering and unresolved routes¶

Buffered asks Refit to load the request body into memory before passing it to the HTTP handler. An explicit [Body(true)] or [Body(false)] overrides the client setting for that argument. A buffered body has a known Content-Length before the handler reads it.

internal interface ISettingsPolicyApi
{
    [Post("/people")]
    Task<string> InheritedAsync([Body] Person person); // follows settings.Buffered

    [Post("/people")]
    Task<string> UnbufferedAsync([Body(false)] Person person); // never buffered

    [Post("/people")]
    Task<string> BufferedAsync([Body(true)] Person person); // always buffered

    [Get("/policy/{tenant}")]
    Task<HttpRequestMessage> UnmatchedAsync();
}

RefitSettings settings = new(serializer) { Buffered = true };
ISettingsPolicyApi api = RestService.ForGenerated<ISettingsPolicyApi>(httpClient, settings);
string reply = await api.InheritedAsync(new(1, "Ada")); // sent buffered, with a Content-Length

UnmatchedAsync declares {tenant} without a matching method argument. With AllowUnmatchedRouteParameters false, the default, building that request throws ArgumentException. True keeps the placeholder for code that will rewrite it later. It does not supply a tenant value. The build warns about {tenant} with RF015.

RefitSettings settings = new(serializer) { AllowUnmatchedRouteParameters = true };
ISettingsPolicyApi api = RestService.ForGenerated<ISettingsPolicyApi>(httpClient, settings);
using HttpRequestMessage request = await api.UnmatchedAsync(); // request.RequestUri: "/policy/{tenant}"

Configure either setting before creating the client.

Settings reference¶

Each row describes one constructor, factory, context method, or public property. Nullable constructor arguments use null to select the formatter default; they are not optional C# parameters.

The enum values used by these properties are:

Source: RefitSettings.cs at Refit SHA 6f0507fa061f1844a8da6ea92e839b622dfc74ef.

ReturnTypeAdapters and UrlParameterFormatterMap expose mutable collections through read-only properties. Registering a formatter map entry makes generated calls use the formatter route instead of the built-in formatting branch. HttpRequestMessageOptions is init-only, but its dictionary remains mutable. Configure all three before calls begin.

Request bodies explains buffering, compression and body ownership. Headers explains validation and token declarations. .NET Framework settings omit Version, VersionPolicy and compression options. .NET 8 includes HTTP version settings but omits compression options.