CSharpEssentials.HttpHelper 5.2.10

CSharpEssentials.HttpHelper

Targets: net8.0 · net9.0 · net10.0

CSharpEssentials.HttpHelper wraps IHttpClientFactory with a small fluent API: named clients configured in appsettings.json, retry (Polly), per-call timeout, rate limiting, per-request callbacks and built-in mocking for tests. Transport failures come back as a HttpResponseMessage (408 / 502 / 500) instead of exceptions.

• Quick Start
• Features
• Examples — JSON, form, headers & auth, retry, timeout, callbacks
• Comparison
• Documentation & Demo

🚀 Quick Start

1. Install

dotnet add package CSharpEssentials.HttpHelper

2. Configure a named client in appsettings.json:

{
  "HttpClientOptions": [
    { "Name": "github", "UseCompression": true }
  ]
}

3. Register in Program.cs:

builder.Services.AddHttpClients(builder.Configuration);

4. Call — inject IhttpsClientHelperFactory, then CreateOrGet(name):

public class GitHubService(IhttpsClientHelperFactory factory)
{
    public async Task<string> GetUserAsync(string user, CancellationToken ct)
    {
        var response = await factory.CreateOrGet("github")
            .addRetryCondition(r => (int)r.StatusCode >= 500, retryCount: 3, backoffFactor: 2)
            .addTimeout(TimeSpan.FromSeconds(10))
            .SendAsync($"https://api.github.com/users/{user}", HttpMethod.Get,
                       headers: new Dictionary<string, string> { ["User-Agent"] = "my-app" },
                       cancellationToken: ct);

        return await response.Content.ReadAsStringAsync(ct);
    }
}

CreateOrGet returns the same helper for the same name, so its settings (retry, timeout, headers, callbacks) stick across calls.

✨ Features

No exceptions for transport failures. SendAsync returns:

📚 Examples

JSON body

JsonContentBuilder sends body.ToString() as application/json, so pass an already serialized string:

using System.Text.Json;

var json = JsonSerializer.Serialize(new { name = "Alice", age = 30 });

var response = await factory.CreateOrGet("api")
    .SendAsync("https://api.example.com/users", HttpMethod.Post,
               new JsonContentBuilder(), json);

response.EnsureSuccessStatusCode();
var created = await response.Content.ReadFromJsonAsync<User>();   // System.Net.Http.Json

Form data

var form = new Dictionary<string, string> { ["grant_type"] = "client_credentials", ["scope"] = "read" };

var response = await factory.CreateOrGet("auth")
    .SendAsync("https://auth.example.com/token", HttpMethod.Post,
               new FormUrlEncodedContentBuilder(), form);

Fluent: headers, auth, retry, timeout

Every configuration method returns the helper, so settings chain:

var helper = factory.CreateOrGet("api")
    .setHeadersAndBearerAuthenticationSync(
        new Dictionary<string, string> { ["Accept"] = "application/json" },
        new httpsClientHelper.httpClientAuthenticationBearer(token))
    .addRetryCondition(r => r.StatusCode == HttpStatusCode.TooManyRequests || (int)r.StatusCode >= 500,
                       retryCount: 3, backoffFactor: 2)       // waits 2s, 4s, 8s
    .addTimeout(TimeSpan.FromSeconds(5));

var response = await helper.SendAsync("https://api.example.com/orders", HttpMethod.Get);

setHeaders…Sync replaces the client's default headers. Per-request headers (the headers: argument of SendAsync) don't touch shared state — prefer them when the same named client is used concurrently.

Rate limiting and compression (config)

{
  "HttpClientOptions": [
    {
      "Name": "api",
      "UseCompression": true,
      "RateLimitOptions": {
        "IsEnabled": true,
        "PermitLimit": 10,
        "Window": "00:00:01",
        "SegmentsPerWindow": 2,
        "QueueLimit": 0,
        "AutoReplenishment": true
      }
    }
  ]
}

Per-request callbacks

factory.CreateOrGet("api").AddRequestAction(async (request, response, retryAttempt, elapsed) =>
{
    Console.WriteLine($"{request.Method} {request.RequestUri} -> {(int)response.StatusCode} (retry #{retryAttempt})");
    await Task.CompletedTask;
});

// all clients:
factory.AddActionOnRequest((req, res, attempt, elapsed) => Task.CompletedTask);

A throwing callback is logged and ignored — it never fails the HTTP call.

🧪 Testing with mock scenarios

Register a scenario in DI; requests it matches are answered by your factories (round-robin) and never hit the network:

services.AddSingleton<IHttpMockScenario>(new HttpMockScenario(
    match: r => r.RequestUri?.Host == "mock.local",
    responseFactory: new List<Func<Task<HttpResponseMessage>>>
    {
        () => Task.FromResult(new HttpResponseMessage(HttpStatusCode.TooManyRequests)),
        () => Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)),
    }));
services.AddHttpClients(configuration);

With addRetryCondition(r => r.StatusCode == HttpStatusCode.TooManyRequests, 3, 0) the first call returns 429, the retry returns 200. Last matching scenario wins; a factory may also throw HttpRequestException to simulate a network failure.

Mocks honour timeout and caller cancellation. Use the (request, ct) => ... overload to observe the token:

services.AddSingleton<IHttpMockScenario>(new HttpMockScenario(
    match: r => r.RequestUri?.Host == "slow.local",
    responseFactory: new List<Func<HttpRequestMessage, CancellationToken, Task<HttpResponseMessage>>>
    {
        async (request, ct) => {
            await Task.Delay(TimeSpan.FromSeconds(30), ct);
            return new HttpResponseMessage(HttpStatusCode.OK);
        },
    }));

With addTimeout(TimeSpan.FromSeconds(1)) the call returns 408; cancelling the caller's token throws OperationCanceledException. The token inside the factory is only available via HttpMockScenario; custom IHttpMockScenario implementations still get timeout/cancellation (the engine stops waiting) but not the token in their factory.

⚖️ Comparison with Refit, Flurl and plain HttpClient

They solve different problems; this table is about what you get out of the box.

Pick HttpHelper when you call a handful of third-party APIs and want retry, timeout, rate limit and logging configured in one place, with failures as plain status codes. Pick Refit for a large, stable API surface you want typed. Pick Flurl for ad-hoc fluent calls with automatic JSON. They can coexist in one app.

📖 Documentation & Demo

• HttpHelper page — Quick Start, examples, comparison
• Full site

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to open a pull request or issue.

📜 License

Distributed under the MIT License. See LICENSE for more information.