AspNetCoreResponseKit 1.0.0

AspNetCoreResponseKit

Standardized API response envelope and global exception handling middleware for ASP.NET Core. Smart factory methods, automatic exception-to-status-code mapping, and native integration with AspNetCoreAuthKit and AspNetCoreHttpKit.

Why AspNetCoreResponseKit? Every project writes the same ApiResponse class and the same ExceptionHandlerMiddleware. AspNetCoreResponseKit gives you a production-ready implementation with zero boilerplate, consistent error formats, and smart factories that eliminate try/catch blocks in controllers.

✨ Features

• 📦 ApiResponse<T> — consistent response envelope for all endpoints
• 🧠 Smart factories — ApiResponse.From(value) and ApiResponse.FromAsync(() => ...) handle null and errors automatically
• 🌐 Middleware — app.UseApiExceptionHandler() catches all unhandled exceptions globally
• 🗺️ Automatic mapping — exceptions are mapped to HTTP status codes via a priority chain
• 🔗 AspNetCoreAuthKit integration — HttpServiceException, RefreshTokenException mapped automatically
• 🔗 AspNetCoreHttpKit integration — ApiResponse.From(HttpResult<T>) converts upstream results directly
• ⚙️ Configurable — null status code, upstream propagation, exception details, custom mappings

📋 Requirements

🚀 Installation

dotnet add package AspNetCoreResponseKit

🎯 Quick Start

1. Register services

// Program.cs
builder.Services.AddAspNetCoreResponseKit(opt =>
{
    opt.IncludeExceptionDetails    = builder.Environment.IsDevelopment();
    opt.NullResponseStatusCode     = HttpStatusCode.NotFound;
    opt.PropagateUpstreamStatusCodes = true;
    opt.DefaultErrorMessage        = "An unexpected error occurred.";
 
    // Custom exception mapping
    opt.MapException<MyDomainException>(ex => (HttpStatusCode.UnprocessableEntity, ex.Message));
});
 
// Must be first in the middleware pipeline
app.UseApiExceptionHandler();
app.UseAuthentication();
app.UseAuthorization();

2. Use in controllers

[HttpGet("{id}")]
public async Task<ApiResponse<UserDto>> GetUser(int id, CancellationToken ct)
{
    // Smart factory — returns 200 if found, configured null status code if not
    return await ApiResponse.FromAsync(() => _service.GetUserAsync(id), ct: ct);
}
 
[HttpPost]
public async Task<ApiResponse<UserDto>> CreateUser(CreateUserRequest req, CancellationToken ct)
{
    var user = await _service.CreateAsync(req, ct);
    return ApiResponse.Created(user.ToDto(), "User created successfully.");
}
 
[HttpDelete("{id}")]
public async Task<ApiResponse> DeleteUser(int id, CancellationToken ct)
{
    var deleted = await _service.DeleteAsync(id, ct);
    return ApiResponse.FromBool(deleted, "User deleted.", "User not found.");
}

3. Use in Minimal APIs

app.MapGet("/users/{id}", async (int id, IUserService svc, CancellationToken ct) =>
{
    var result = await ApiResponse.FromAsync(() => svc.GetUserAsync(id), ct: ct);
    return result.ToResult();
});

4. Use with AspNetCoreHttpKit

app.MapGet("/proxy/users/{id}", async (int id, IHttpService http, CancellationToken ct) =>
{
    var result = await http.GetAsync<UserDto>($"/users/{id}", ct);
 
    // Converts HttpResult<T> directly — status code propagated based on options
    return ApiResponse.FromHttpResult(result).ToResult();
});

📦 Response format

Success

{
  "isSuccess": true,
  "data": { "id": 1, "name": "Simone" },
  "message": null,
  "errors": [],
  "statusCode": 200
}

Error

{
  "isSuccess": false,
  "data": null,
  "message": "User not found.",
  "errors": [],
  "statusCode": 404
}

🗺️ Exception mapping priority chain

When an unhandled exception is caught by the middleware, it is resolved in this order:

1. Custom mappings — registered via opt.MapException<T>()
2. AspNetCoreAuthKit / AspNetCoreHttpKit — HttpServiceException, RefreshTokenException, etc.
3. Standard .NET exceptions — ArgumentException, UnauthorizedAccessException, etc.
4. Fallback — 500 Internal Server Error

Built-in mappings

📚 API Reference

ApiResponse factory methods

ApiResponse<T> fluent methods

⚙️ Configuration options

❤️ Support

If you find AspNetCoreResponseKit useful, consider sponsoring its development.

📄 License

MIT — see LICENSE for details.