AutoHttpClient.Generator 1.5.0

AutoHttpClient.Generator

AutoHttpClient.Generator is an AOT-safe, compile-time typed HTTP client for .NET. Annotate an interface with [HttpClient], decorate methods with [Get], [Post], [Put], [Delete], or [Patch], and the generator emits a strongly-typed implementation plus DI registration at build time.

Related Swevo packages

• AutoDispatch.Generator — compile-time MediatR-style dispatch
• AutoMap.Generator — compile-time DTO/entity mapping
• Swevo.AutoAssert — fluent assertions without commercial licensing

Why AutoHttpClient.Generator?

• Compile-time generated clients — no dynamic proxy generation, no reflection-heavy dispatch layer
• AOT-safe request dispatch — generated C# calls HttpClient directly with no reflection-based proxy, and passing an explicit JsonSerializerOptions (ideally backed by a JsonSerializerContext) to the constructor or AddAutoHttpClients(jsonOptions) produces zero trim/AOT warnings, measured against Refit in samples/AotBenchmark/BENCHMARK.md
• Minimal ceremony — plain interfaces plus attributes, no hand-written wrappers
• DI-ready — AddAutoHttpClients() registers every generated client for IServiceCollection
• Strongly typed — route values, query parameters, headers, and JSON bodies all come from your method signature

Why not Refit or RestSharp?

• Refit (v16+) has also moved to a Roslyn source generator and ships an official Native AOT path (RestService.ForGenerated<T> + a JsonSerializerContext), so it's no longer purely runtime-proxy based. Both libraries can now produce warning-free trimmed/AOT builds when given explicit JSON type info. The real differences today are ergonomics: AutoHttpClient.Generator's generated client can be constructed directly (new) or resolved from DI with zero extra AOT-specific API surface, has build-time diagnostics for common mistakes (see Diagnostics), and ships an OpenAPI scaffolding tool. See samples/AotBenchmark/BENCHMARK.md for a measured, head-to-head trim/AOT comparison.
• RestSharp is a runtime HTTP abstraction with reflection-oriented configuration rather than compile-time emitted clients
• AutoHttpClient.Generator keeps everything as generated source in your build output: explicit, trim-friendly, and (for the request-building path) zero-reflection

Installation

dotnet add package AutoHttpClient.Generator

Then register the generated clients:

builder.Services.AddAutoHttpClients();

Quick start

using AutoHttpClient;

[HttpClient]
public interface IOrdersApi
{
    [Get("/api/orders/{id}")]
    Task<Order?> GetOrderAsync(int id, CancellationToken ct = default);

    [Get("/api/orders")]
    Task<List<Order>> GetOrdersAsync([Query("status")] string? status = null, CancellationToken ct = default);

    [Post("/api/orders")]
    Task<Order> CreateOrderAsync([Body] CreateOrderRequest request, CancellationToken ct = default);

    [Put("/api/orders/{id}")]
    Task<Order> UpdateOrderAsync(int id, [Body] UpdateOrderRequest request, CancellationToken ct = default);

    [Delete("/api/orders/{id}")]
    Task DeleteOrderAsync(int id, CancellationToken ct = default);

    [Get("/api/orders/{id}/status")]
    Task<HttpResponseMessage> GetOrderStatusRawAsync(int id, CancellationToken ct = default);
}

Register the generated implementation:

builder.Services.AddAutoHttpClients();

This emits an internal sealed client implementation and a DI registration similar to:

services.AddHttpClient("global::IOrdersApi").AddTypedClient<IOrdersApi>(httpClient => new OrdersApiClient(httpClient, jsonOptions));

AddAutoHttpClients() (parameterless) is a convenience overload that falls back to JsonSerializerOptions.Web; it's annotated [RequiresUnreferencedCode]/ [RequiresDynamicCode] so it only warns if you actually use it. For a fully warning-free trimmed/Native AOT build, pass your own options instead — ideally backed by a source-generated JsonSerializerContext:

builder.Services.AddAutoHttpClients(new JsonSerializerOptions(MyJsonContext.Default.Options)
{
    TypeInfoResolver = MyJsonContext.Default,
});

See samples/AotBenchmark/BENCHMARK.md for a measured, zero-warning comparison against Refit using this pattern.

Parameter attributes

AutoHttpClient.Generator classifies parameters using these rules:

Examples

[Get("/api/orders")]
Task<List<Order>> GetOrdersAsync([Query("status")] string? status = null, int page = 1, CancellationToken ct = default);

[Post("/api/orders")]
Task<Order> CreateOrderAsync([Body] CreateOrderRequest request, [Header("X-Tenant")] string tenant, CancellationToken ct = default);

[Get("/api/orders/{id}")]
Task<Order?> GetOrderAsync(int id, CancellationToken ct = default);

[Get("/api/orders")]
Task<List<Order>> SearchOrdersAsync([QueryMap] IDictionary<string, string?> filters, CancellationToken ct = default);

[Get("/api/orders")]
Task<List<Order>> GetOrdersForTenantAsync([HeaderCollection] IDictionary<string, string?> headers, CancellationToken ct = default);

Static headers

Apply constant headers to every request generated for an interface or a specific method with [Headers("Name: Value")], similar to Refit:

using AutoHttpClient;

[HttpClient(BaseAddress = "https://api.example.com")]
[Headers("X-Api-Version: 1.0")]
public interface IOrdersApi
{
    [Get("/api/orders")]
    [Headers("Accept: application/json")]
    Task<List<Order>> GetOrdersAsync(CancellationToken ct = default);
}

Method-level [Headers] take priority over interface-level ones when the same header name is declared in both places. [Headers] can be applied multiple times on the same target.

Multipart form uploads

Mark a method [Multipart] and decorate its parameters with [Part] to send a multipart/form-data request — useful for file uploads:

using AutoHttpClient;

[HttpClient(BaseAddress = "https://api.example.com")]
public interface IUploadsApi
{
    [Post("/api/uploads")]
    [Multipart]
    Task<UploadResult> UploadAsync(
        [Part("file", "photo.png")] Stream file,
        [Part("description")] string description,
        [Part] UploadMetadata metadata,
        CancellationToken ct = default);
}

Part parameter types are handled automatically:

[Part(name, fileName)] controls the form field name and, optionally, the file name sent to the server; both default to the parameter name / no file name. A [Multipart] method cannot also declare a [Body] parameter (AH004).

Return types

Observable return types

Methods can also return IObservable<T> instead of Task<T> for interop with Rx-style code (a single HTTP call surfaced as an observable sequence, matching Refit's IObservable<T> support):

using AutoHttpClient;

[HttpClient]
public interface IOrdersApi
{
    [Get("/api/orders/{id}")]
    IObservable<Order> GetOrderAsync(int id);
}

// usage
ordersApi.GetOrderAsync(42).Subscribe(
    order => Console.WriteLine(order.Id),
    ex => Console.WriteLine($"Failed: {ex.Message}"));

• The call doesn't start until Subscribe is called; disposing the returned subscription cancels the in-flight request.
• On success, the observer receives exactly one OnNext followed by OnCompleted. On failure (including a non-success status code, which throws ApiException), the observer receives OnError instead.
• No dependency on System.Reactive is required — it's a minimal IObservable<T>/IObserver<T> bridge using only BCL types.
• A CancellationToken parameter isn't meaningful on an IObservable<T>-returning method (cancellation is via the subscription's IDisposable.Dispose() instead), so don't declare one there.

Streaming with IAsyncEnumerable

Methods can return IAsyncEnumerable<T> to lazily stream a large JSON array response one element at a time instead of buffering the whole array in memory — something Refit doesn't support:

using AutoHttpClient;
using System.Collections.Generic;
using System.Threading;

[HttpClient]
public interface IOrdersApi
{
    [Get("/api/orders")]
    IAsyncEnumerable<Order> StreamOrdersAsync(CancellationToken ct = default);
}

// usage
await foreach (var order in ordersApi.StreamOrdersAsync(ct))
{
    Console.WriteLine(order.Id);
}

• The response and its underlying stream are disposed automatically when enumeration completes or the await foreach is exited early (via break, an exception, or cancellation).
• Deserialization uses System.Text.Json.JsonSerializer.DeserializeAsyncEnumerable<T>, so elements are yielded as they're parsed instead of waiting for the entire response body.
• A non-success status code throws ApiException before any elements are yielded.
• Declare an explicit CancellationToken parameter (as shown above) to cancel enumeration — [EnumeratorCancellation]/.WithCancellation() support is intentionally not implemented to keep the generated code simple.
• [Retry] (below) can't be combined with IAsyncEnumerable<T> methods (diagnostic AH007) because C# iterator methods can't wrap yield return in a try/catch.

Resilience presets with [Resilience]

For a one-attribute resilience policy, use [Resilience] on a method. It applies timeout + retry defaults together:

• Conservative → 2 attempts, 500ms base delay, 15s timeout
• Standard (default) → 3 attempts, 200ms base delay, 30s timeout
• Aggressive → 5 attempts, 100ms base delay, 60s timeout

using AutoHttpClient;

[HttpClient]
public interface IOrdersApi
{
    [Get("/api/orders/{id}")]
    [Resilience(ResiliencePreset.Aggressive)]
    Task<Order> GetOrderAsync(int id, CancellationToken ct = default);
}

[Resilience] is method-level, so different endpoints can use different policies. If both [Resilience] and [Retry] are applied, explicit [Retry] values win for retry attempts/delay, while timeout still comes from the selected resilience preset.

Automatic retry with [Retry]

Decorate a method with [Retry(maxAttempts, delayMilliseconds)] to automatically retry on transient failures — no dependency on Polly required:

using AutoHttpClient;

[HttpClient]
public interface IOrdersApi
{
    [Get("/api/orders/{id}")]
    [Retry(maxAttempts: 5, delayMilliseconds: 100)]
    Task<Order> GetOrderAsync(int id, CancellationToken ct = default);
}

• Defaults are maxAttempts: 3, delayMilliseconds: 200 if omitted.
• A failure is considered transient (and retried) if it's an ApiException with a 5xx, 408, or 429 status code, or an HttpRequestException (e.g. a connection failure). Genuine cancellations (OperationCanceledException/TaskCanceledException) are never retried.
• Delay between attempts grows exponentially (attempt 1 waits the base delay, attempt 2 waits 2x, attempt 3 waits 4x, and so on).
• The entire request (URL/query/header/body construction and the HTTP call) is retried, not just the deserialization step, since a failed HttpClient.SendAsync call may not have reached the server at all.
• Not supported on IAsyncEnumerable<T>-returning methods — see Streaming with IAsyncEnumerable above.

Per-method JsonSerializerOptions override

By default every generated method uses the single JsonSerializerOptions instance passed to the client's constructor (or registered via AddAutoHttpClients(jsonOptions)). Override it for an individual method with [JsonSerializerOptions(providerType, memberName)], pointing at a public static property or field of type JsonSerializerOptions:

using AutoHttpClient;
using System.Text.Json;

public static class LegacyApiJsonOptions
{
    public static JsonSerializerOptions Options { get; } = new JsonSerializerOptions
    {
        PropertyNamingPolicy = null, // this endpoint still uses PascalCase
    };
}

[HttpClient]
public interface IOrdersApi
{
    [Get("/api/orders/{id}")]
    [JsonSerializerOptions(typeof(LegacyApiJsonOptions), nameof(LegacyApiJsonOptions.Options))]
    Task<Order> GetOrderAsync(int id, CancellationToken ct = default);
}

If the referenced member doesn't exist (or isn't a public static JsonSerializerOptions property/field), diagnostic AH006 is reported and the method falls back to the client-wide options.

Error handling

Non-success responses throw AutoHttpClient.ApiException (instead of a bare EnsureSuccessStatusCode() call) so you don't lose the response body:

try
{
    var order = await ordersApi.GetOrderAsync(404, ct);
}
catch (AutoHttpClient.ApiException ex)
{
    // ex.StatusCode, ex.ReasonPhrase, ex.Content (raw response body, best-effort)
}

If you need the raw HttpResponseMessage instead (no exception thrown), use a Task<HttpResponseMessage> return type.

BaseAddress configuration

You can configure a base address directly on the interface attribute:

using AutoHttpClient;

[HttpClient(BaseAddress = "https://api.example.com")]
public interface IOrdersApi
{
    [Get("/api/orders")]
    Task<List<Order>> GetOrdersAsync(CancellationToken ct = default);
}

The generated DI registration configures the typed client:

services.AddHttpClient<IOrdersApi, OrdersApiClient>(client =>
{
    client.BaseAddress = new Uri("https://api.example.com");
});

Scaffolding from OpenAPI/Swagger

AutoHttpClient.Generator now includes a small repo-side scaffolding tool for converting an OpenAPI/Swagger JSON document into a partial interface decorated with AutoHttpClient attributes.

Run it with:

dotnet run --project tools/AutoHttpClient.OpenApiScaffold -- --input swagger.json --output IMyApiClient.g.cs --namespace MyApp.Clients --interface-name IMyApiClient

The generated file is a one-time scaffold that you add to your project, then the existing AutoHttpClient.Generator source generator consumes it normally.

What it generates

• [HttpClient] or [HttpClient(BaseAddress = "...")] when the spec declares a simple server URL
• [Get], [Post], [Put], [Delete], [Patch] based on each OpenAPI operation
• Route parameters as normal method parameters
• Query parameters as [Query("name")]
• Request bodies as [Body]
• Task<T> return types using referenced schema names where possible

Current scope / limitations

• Optimized for common OpenAPI 3 JSON documents
• Swagger/OpenAPI 2 documents may work for basic paths/operations, but v3 is the primary target
• Best support is for JSON request/response bodies with named schemas, simple path/query/header parameters, and standard HTTP verbs
• Inline/anonymous schemas fall back to JsonElement (or collections/dictionaries of known types where possible)
• Advanced OpenAPI features such as oneOf, anyOf, callbacks, multipart form uploads, and full DTO generation are not scaffolded yet
• Named schemas are used as C# type names in the generated interface; you still need matching DTO types in your project

Comparison

Diagnostics

Generated attributes

The package emits these attributes at post-initialization time:

• HttpClientAttribute
• GetAttribute
• PostAttribute
• PutAttribute
• DeleteAttribute
• PatchAttribute
• BodyAttribute
• QueryAttribute
• HeaderAttribute
• HeadersAttribute
• HeaderCollectionAttribute
• QueryMapAttribute
• MultipartAttribute
• PartAttribute
• ApiException

Migrating from Refit

AutoHttpClient.Generator uses the same interface-first approach as Refit. Migration is mostly a find-and-replace of attributes.

1. Install and remove Refit

dotnet add package AutoHttpClient.Generator
dotnet remove package Refit
dotnet remove package Refit.HttpClientFactory

2. Replace Refit attributes with AutoHttpClient attributes

// Before (Refit)
using Refit;

public interface IOrdersApi
{
    [Get("/api/orders/{id}")]
    Task<Order?> GetOrderAsync(int id, CancellationToken ct = default);

    [Post("/api/orders")]
    Task<Order> CreateOrderAsync([Body] CreateOrderRequest request, CancellationToken ct = default);

    [Get("/api/orders")]
    Task<List<Order>> GetOrdersAsync([AliasAs("status")] string? status = null);
}

// After (AutoHttpClient.Generator)
using AutoHttpClient;

[HttpClient]
public interface IOrdersApi
{
    [Get("/api/orders/{id}")]
    Task<Order?> GetOrderAsync(int id, CancellationToken ct = default);

    [Post("/api/orders")]
    Task<Order> CreateOrderAsync([Body] CreateOrderRequest request, CancellationToken ct = default);

    [Get("/api/orders")]
    Task<List<Order>> GetOrdersAsync([Query("status")] string? status = null);
}

3. Update DI registration

// Before (Refit)
builder.Services.AddRefitClient<IOrdersApi>()
    .ConfigureHttpClient(c => c.BaseAddress = new Uri("https://api.example.com"));

// After (AutoHttpClient.Generator)
[HttpClient(BaseAddress = "https://api.example.com")]
public interface IOrdersApi { ... }

builder.Services.AddAutoHttpClients();

Attribute mapping

Feature parity with Refit — and beyond

IObservable<T> return types and per-method JSON serializer overrides ([JsonSerializerOptions]) are both supported — see Observable return types and Per-method JsonSerializerOptions override above. AutoHttpClient.Generator also goes further than Refit with three built-in differentiators Refit doesn't offer at all: IAsyncEnumerable<T> streaming responses, Polly-free automatic retry, and per-endpoint resilience presets.

Also by the same author

🌐 Full suite overview: swevo.github.io

Related Packages

Package	Downloads	Description
AutoWire		Compile-time dependency injection auto-registration for
AutoMap.Generator		Compile-time object mapping for
AutoQuery.Generator		Compile-time query composition for IQueryable using Roslyn incremental source generators
AutoArchitecture		Compile-time architecture/dependency-rule enforcement for
AutoDispatch.Generator		Compile-time CQRS dispatcher for
AutoLog.Generator		Compile-time high-performance logging for
AutoValidate.Generator		Compile-time FluentValidation wiring for

License

MIT