AutoHttpClient.Generator 1.1.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.

Why AutoHttpClient.Generator?

• Compile-time generated clients — no dynamic proxy generation, no reflection-heavy dispatch layer
• AOT-safe — generated C# calls HttpClient directly, so it works cleanly with native AOT scenarios
• 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 is ergonomic, but relies on runtime plumbing and generated proxy behavior that is less predictable in AOT-focused deployments
• 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 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<IOrdersApi, OrdersApiClient>();

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);

Return types

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

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

What Refit supports that AutoHttpClient.Generator doesn't (yet)

• [HeaderCollection] dictionary headers
• [Multipart] / [AttachmentName] for multipart form uploads
• IObservable<T> return types
• Custom JsonSerializerSettings per method

For projects using any of these heavily, hold off on migrating until support lands.

Also by the same author

🌐 Full suite overview: swevo.github.io

License

MIT