AspNetCoreHttpKit 1.0.0

AspNetCoreHttpKit

A lightweight HTTP client toolkit for ASP.NET Core with typed results, structured logging (StructLog or ILogger), named clients, and configurable timeout via appsettings.json.

Why AspNetCoreHttpKit? HttpClient in .NET is powerful but verbose. Every project ends up writing the same boilerplate: JSON serialization, error handling, logging, timeout management. AspNetCoreHttpKit wraps all of this in a clean, testable abstraction with a consistent API.

✨ Features

• 🌐 GET, POST, PUT, PATCH, DELETE with automatic JSON serialization/deserialization
• 📦 Result pattern — HttpResult<T> with fluent OnSuccess / OnError
• 💥 Typed exceptions — HttpNotFoundException, HttpUnauthorizedException, and more
• ⏱️ Configurable timeout — globally and per named client
• 🔑 Named clients — one client per external service, configured in appsettings.json
• 📝 StructLog integration — uses StructLog with typed EventCodes if registered, falls back to ILogger automatically
• 🧪 DI-ready — register with one line, mock IHttpService in tests

📋 Requirements

🚀 Installation

dotnet add package AspNetCoreHttpKit

🎯 Quick Start

1. Configure appsettings.json

{
  "HttpServiceOptions": {
    "BaseUrl": "https://api.myservice.com",
    "TimeoutSeconds": 30,
    "Clients": {
      "PaymentApi": {
        "BaseUrl": "https://api.payment.com",
        "TimeoutSeconds": 10
      },
      "UserApi": {
        "TimeoutSeconds": 5
      }
    }
  }
}

UserApi inherits the global BaseUrl but uses its own TimeoutSeconds of 5 seconds. PaymentApi overrides both.

2. Register services

// With StructLog (automatic detection)
builder.Services.AddStructLog(); // register StructLog first
builder.Services.AddAspNetCoreHttpKit(builder.Configuration); // HttpKit detects it automatically

// Without StructLog — falls back to ILogger automatically
builder.Services.AddAspNetCoreHttpKit(builder.Configuration);

// Without appsettings (uses defaults)
builder.Services.AddAspNetCoreHttpKit();

3. Use the global client

[ApiController]
public class UsersController : ControllerBase
{
    private readonly IHttpService _http;

    public UsersController(IHttpService http)
    {
        _http = http;
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetUser(int id, CancellationToken ct)
    {
        var result = await _http.GetAsync<User>($"/users/{id}", ct);

        return result.IsSuccess ? Ok(result.Data) : NotFound();
    }
}

4. Use a named client

public class PaymentService
{
    private readonly IHttpService _client;

    public PaymentService(IHttpServiceFactory factory)
    {
        _client = factory.Create("PaymentApi");
    }

    public async Task<PaymentResult?> ChargeAsync(ChargeRequest request, CancellationToken ct)
    {
        var result = await _client.PostAsync<PaymentResult>("/charge", request, ct);

        // Option A — result pattern (fluent)
        result
            .OnSuccess(data => Console.WriteLine($"Charged: {data?.TransactionId}"))
            .OnError((msg, code) => Console.WriteLine($"Failed: {code} — {msg}"));

        // Option B — throw typed exception
        HttpServiceHelper.ThrowIfFailed(result);

        return result.Data;
    }
}

📝 Logging

AspNetCoreHttpKit resolves the logger automatically at startup:

StructLog EventCodes

When StructLog is active, every HTTP operation is logged with a dedicated EventCode:

📚 API Reference

IHttpService methods

HttpResult<T> properties

Fluent result handling

var result = await _http.GetAsync<User>("/users/1", ct);

result
    .OnSuccess(user => _logger.LogInformation("Found user {Id}", user?.Id))
    .OnError((msg, code) => _logger.LogWarning("Error {Code}: {Msg}", code, msg));

Typed exceptions

Use HttpService.ThrowIfFailed(result) to convert a failed result into a typed exception:

⚙️ Configuration options

Global options

Per-client options

🧪 Testing

IHttpService is a plain interface — mock it directly in unit tests:

var httpMock = new Mock<IHttpService>();

httpMock
    .Setup(h => h.GetAsync<User>("/users/1", It.IsAny<CancellationToken>()))
    .ReturnsAsync(HttpResult<User>.Success(new User { Id = 1, Name = "Simone" }, HttpStatusCode.OK));

❤️ Support

If you find AspNetCoreHttpKit useful, consider sponsoring its development.

📄 License

MIT — see LICENSE for details.