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 generated metadata. Use the context and serializer from client creation.

2. Choose the settings constructor. The serializer is required in these constructor overloads. A null formatter selects the default formatter.

RefitSettings defaults = new() { ContentSerializer = JsonSettings.ContentSerializer };
RefitSettings serializerOnly = new(JsonSettings.ContentSerializer);
RefitSettings values = new(JsonSettings.ContentSerializer, new DefaultUrlParameterFormatter());
RefitSettings forms = new(JsonSettings.ContentSerializer, null, new DefaultFormUrlEncodedParameterFormatter());
RefitSettings keys = new(JsonSettings.ContentSerializer, null, null, new CamelCaseUrlParameterKeyFormatter());

3. Pass the settings to client creation or registration. Reuse the configured serializer. The parameterless constructor creates a System.Text.Json serializer and default formatters. Assign generated JSON metadata before using that serializer in an AOT app. 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.

Align naming rules with generated JSON¶

CamelCase(), SnakeCase() and KebabCase() return new settings. They align the JSON naming policy and URL key formatter. For AOT, replace their serializer with one whose generated context uses the same convention. These contexts register the demonstration model, ClientNamingInput(int PageSize).

[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
[JsonSerializable(typeof(ClientNamingInput))]
internal sealed partial class ClientCamelJsonContext : JsonSerializerContext;

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

[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.KebabCaseLower)]
[JsonSerializable(typeof(ClientNamingInput))]
internal sealed partial class ClientKebabJsonContext : JsonSerializerContext;

The example checks all three shortcuts and writes the model with each generated context.

RefitSettings camel = RefitSettings.CamelCase();
RefitSettings snake = RefitSettings.SnakeCase();
RefitSettings kebab = RefitSettings.KebabCase();
RefitSettings[] naming = [camel, snake, kebab];
System.Text.Json.Serialization.JsonSerializerContext[] contexts = [ClientCamelJsonContext.Default, ClientSnakeJsonContext.Default, ClientKebabJsonContext.Default];
for (int index = 0; index < naming.Length; index++)
{
    RefitSettings settings = naming[index];
    System.Text.Json.Serialization.JsonSerializerContext context = contexts[index];
    JsonSerializerOptions options = new(context.Options) { TypeInfoResolver = context };
    settings.ContentSerializer = new SystemTextJsonContentSerializer(options);
    Console.WriteLine(settings.UrlParameterKeyFormatter.Format(NamingKey));
    using HttpContent content = settings.ContentSerializer.ToHttpContent(new ClientNamingInput(NamingPageSize));
    Console.WriteLine(await content.ReadAsStringAsync());
}

The key/body names are pageSize, page_size and page-size. 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. The policy example checks both client defaults and both attribute overrides. Its handler observes the content length before reading any bytes:

RefitSettings settings = new(serializer) { Buffered = buffer };
ISettingsPolicyApi api = RestService.ForGenerated<ISettingsPolicyApi>(client, settings);
SampleCheck.Equal(BufferingHandler.ReplyText, await api.InheritedAsync(new(1, "Ada")));
SampleCheck.Equal(buffer, handler.LengthBeforeRead.HasValue);
SampleCheck.Equal(BufferingHandler.ReplyText, await api.UnbufferedAsync(new(1, "Ada")));
SampleCheck.Equal(false, handler.LengthBeforeRead.HasValue);
SampleCheck.Equal(BufferingHandler.ReplyText, await api.BufferedAsync(new(1, "Ada")));
SampleCheck.Equal(true, handler.LengthBeforeRead > 0);

The same project declares /policy/{tenant} without a matching method argument. With AllowUnmatchedRouteParameters false, building that request throws ArgumentException. True retains the placeholder for code that will rewrite it later. It does not supply a tenant value.

RefitSettings settings = new(serializer) { AllowUnmatchedRouteParameters = allow };
ISettingsPolicyApi api = RestService.ForGenerated<ISettingsPolicyApi>(client, settings);

Configure either setting before creating the client. The complete example reuses one local HTTP client across the checks and does not contact a server.

Settings reference¶

Each row describes one constructor, naming factory, 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.