WebBoost 1.0.0

WebBoost - Custom Binders & Exception Middleware for ASP.NET Core

WebBoost extends the ASP.NET Core Model Binding pipeline and adds middleware utilities to standardize cross-cutting behavior. The goal is to provide practical tools not offered by the framework in the way this project implements, such as declarative binders that populate objects from QueryString and Headers, plus a Global Exception Handler that removes repetitive try/catch code and avoids leaking exception details.

Motivation

While ASP.NET Core has powerful Model Binding, everyday scenarios require populating objects from multiple request sources (query, headers) without cluttering controllers. Likewise, consistent exception handling often leads to boilerplate and scattered logic.

WebBoost addresses these by providing:

• Custom binders via attributes ([QueryBinder], [HeaderBinder]) that reduce boilerplate and standardize type conversion.
• A GlobalExceptionHandlerMiddleware that catches unhandled errors, prevents sensitive details from leaking, and returns uniform JSON responses.
• An extensible base for adding more utilities (additional binders and middlewares).

Features

• Direct binding from query and headers into complex objects.
• Automatic type conversion (int, decimal, DateTime, enum, etc.).
• Clear error messages when a property is missing or a conversion fails.
• Global exception middleware that logs with ILogger and returns HTTP 500 JSON by default.

Installation

Planned NuGet package:

dotnet add package WebBoost.Binders

For now, clone and reference the repo:

git clone https://github.com/PedroHenriqDev/WebBoost

Using the Binders

Example model: UserDto

namespace WebBoost.Test.Models
{
    public class UserDto
    {
        public int Id { get; set; }              // QueryBinder("Id")
        public string Name { get; set; } = "";   // QueryBinder("Name")
        public int Version { get; set; }         // HeaderBinder("Version")
        public string Email { get; set; } = "";  // QueryBinder("Email")
    }
}

1) Bind from QueryString

[HttpPost("qs")]
public IActionResult BindUserByQs([QueryBinder("Id", "Name", "Email")] UserDto userDto)
{
    return Ok(userDto);
}

Request example:

POST /api/users/qs?Id=10&Name=Pedro&Email=pedro@email.com

Response:

{ "id": 10, "name": "Pedro", "version": 0, "email": "pedro@email.com" }

2) Bind from Headers

[HttpPost("header")]
public IActionResult BindUserByHeader([HeaderBinder("Version")] UserDto userDto)
{
    return Ok(userDto);
}

Example:

POST /api/users/header
Header: Version: 2

Response:

{ "id": 0, "name": "", "version": 2, "email": "" }

GlobalExceptionHandlerMiddleware

Middleware that captures unhandled exceptions, logs them, and returns a consistent JSON response - eliminating repetitive try/catch blocks.

What it does

• Intercepts exceptions during request processing.
• Logs message, stack trace, and source using ILogger.
• Sets StatusCode 500 by default and returns:

  { "Message": "Internal server error" }
  

• Can evolve to map specific exception types to specific status codes (e.g., ArgumentException → 400).

How to register (Program.cs)

Extension methods: WebBoost.Middlewares.MiddlewareExtension

1. Add to DI

using WebBoost.Middlewares;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddGlobalExceptionHandler(); // registers the middleware

2. Add to the pipeline

var app = builder.Build();

app.UseHttpsRedirection();

// Place it early, before auth
app.UseGlobalExceptionHandler();

app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();
app.Run();

Important

• Order matters: place it before middlewares that can throw (auth).
• Use either this middleware or UseExceptionHandler("/error") (not both).

Available signatures

IServiceCollection AddGlobalExceptionHandler(this IServiceCollection services); // Singleton (no per-request state)
IApplicationBuilder UseGlobalExceptionHandler(this IApplicationBuilder app);

Singleton is fine while the middleware keeps no per-request state. If you later inject scoped services (e.g., DbContext), consider AddTransient.

Quick test

[ApiController]
[Route("api/test")]
public class TestController : ControllerBase
{
    [HttpGet("boom")]
    public IActionResult Boom() => throw new InvalidOperationException("Sample error");
}

Request: GET /api/test/boom Expected: 500 + {"Message":"Internal server error"} (and a critical log entry).

Exceptions

• ComplexBindNotFoundPropertyException: the target property is missing on the model.
• InvalidOperationException: the value cannot be converted to the target type.

License

MIT © 2025 — Pedro Henrique Rodrigues Oliveira