DKNet.AspCore.SlimBus 9.5.17

DKNet.AspCore.SlimBus

Minimal API integration helpers for SlimMessageBus + FluentResults, enabling terse, consistent, and well-documented REST endpoints over a CQRS-ish message bus abstraction.

This package focuses on the ASP.NET Core surface (endpoint mapping & HTTP translation). Core CQRS contracts and EF Core behaviors live in DKNet.SlimBus.Extensions.

Key Features

• ✳️ One-Liner Endpoint Mapping for commands, queries, paged queries, and void commands
• 📦 Automatic Response Shaping using FluentResults + ProblemDetails
• 🧾 Standardized Problem Responses via ProducesCommons() contract
• 📄 Pagination Wrapper (PagedResult<T>) for IPagedList<T> → stable JSON shape
• 🔄 Uniform HTTP Semantics (POST = create vs update; null query response → 404)
• 🧪 Test-Friendly pure extension methods (logic inside bus + results)

Installation

dotnet add package DKNet.AspCore.SlimBus

Also install (if not already):

dotnet add package DKNet.SlimBus.Extensions

When To Use

Quick Start

var builder = WebApplication.CreateBuilder(args);
var services = builder.Services;

// SlimBus + handlers (from DKNet.SlimBus.Extensions)
services.AddSlimBusForEfCore(b =>
{
    b.WithProviderMemory()
     .AutoDeclareFrom(typeof(CreateProductHandler).Assembly)
     .AddJsonSerializer();
});

var app = builder.Build();
var products = app.MapGroup("/products");

products
    .MapGet<GetProduct, ProductResult>("/{id}")
    .WithName("GetProduct");

products
    .MapGetPage<GetProductsPage, ProductResult>("/")
    .WithName("GetProductsPage");

products
    .MapPost<CreateProduct, ProductResult>("/")
    .WithName("CreateProduct");

products
    .MapPut<UpdateProduct, ProductResult>("/{id}")
    .WithName("UpdateProduct");

products
    .MapDelete<DeleteProduct>("/{id}")
    .WithName("DeleteProduct");

app.Run();

Endpoint Mapping API

All methods extend RouteGroupBuilder and infer OpenAPI metadata.

All return a RouteHandlerBuilder enabling further customization (e.g., .RequireAuthorization()).

Common Response Metadata

Call .ProducesCommons() automatically (already applied internally by the mapping helpers) to register standardized error codes:

• 400 (ProblemDetails) validation / domain errors
• 401 / 403 auth/authz
• 404 not found (for null query result)
• 409 conflict
• 429 rate limiting
• 500 server error

FluentResults → HTTP Translation

ResultResponseExtensions define:

public static IResult Response<T>(this IResult<T> result, bool isCreated = false);
public static IResult Response(this IResultBase result, bool isCreated = false);

Rules:

• Failure → ProblemDetails (400 by default)
• Success + isCreated → 201 Created with payload
• Success + null value → 200 Ok (no body)
• Success + value → JSON body

ProblemDetails Extensions

result.ToProblemDetails();              // From IResultBase
modelState.ToProblemDetails();          // From ModelStateDictionary

Aggregates distinct error messages into extensions.errors.

Example output:

{
  "status": 400,
  "type": "BadRequest",
  "title": "Error",
  "detail": "Name is required",
  "errors": ["Name is required", "Price must be positive"]
}

Pagination Wrapper

PagedResult<T> converts an IPagedList<T> into a transport-friendly DTO:

{
  "pageNumber": 1,
  "pageSize": 20,
  "pageCount": 7,
  "totalItemCount": 123,
  "items": [ { /* ... */ } ]
}

Returned automatically by MapGetPage.

Defining Requests & Handlers (from DKNet.SlimBus.Extensions)

public record GetProduct : Fluents.Queries.IWitResponse<ProductDto>
{
    public Guid Id { get; init; }
}

public class GetProductHandler : Fluents.Queries.IHandler<GetProduct, ProductDto>
{
    private readonly AppDbContext _db; private readonly IMapper _m;
    public GetProductHandler(AppDbContext db, IMapper m) { _db = db; _m = m; }

    public async Task<ProductDto?> Handle(GetProduct q, CancellationToken ct) =>
        await _db.Products.Where(p => p.Id == q.Id)
            .Select(p => _m.Map<ProductDto>(p))
            .FirstOrDefaultAsync(ct);
}

Binding With [AsParameters]

For GET endpoints the query object is bound via [AsParameters] automatically when using the helpers, enabling clean record definitions:

public record GetProductsPage(int PageIndex = 0, int PageSize = 20) : Fluents.Queries.IWitPageResponse<ProductDto>;

Composing Policies / Filters

products
  .MapPost<CreateProduct, ProductResult>("/")
  .RequireAuthorization("ProductsWrite")
  .AddEndpointFilter(new LoggingFilter());

Error Scenarios & Status Codes

Extending

Add your own composite methods:

public static class ProductEndpointGroup
{
    public static RouteGroupBuilder MapProductEndpoints(this IEndpointRouteBuilder app)
    {
        var g = app.MapGroup("/products");
        g.MapGet<GetProduct, ProductDto>("/{id}");
        g.MapPost<CreateProduct, ProductDto>("/");
        return g;
    }
}

Testing Patterns

Because the endpoint methods only orchestrate bus + translation, prefer unit testing handlers and a minimal integration test asserting mapping correctness:

// Arrange: host with in-memory bus stub
// Act: HTTP call
// Assert: status + payload shape

Versioning & Compatibility

Targets .NET 9+. Uses ASP.NET Core Minimal APIs.

Roadmap / Ideas

• Optional Location URI delegate for Created responses
• Customizable default problem title / type mapping
• OpenTelemetry activity tagging
• Inline endpoint filter helpers (validation, caching)

Contributing

PRs welcome. Keep helpers minimal and side-effect free. Larger concerns (transactions, persistence, events) belong in the core extensions library.

License

MIT © DKNet

See Also

• DKNet.SlimBus.Extensions (core CQRS + EF integration)
• SlimMessageBus
• FluentResults