Voltimax.Messaging

Azure Service Bus messaging library with a minimal API-style programming model.

Quick Start

var messaging = builder.Services.AddMessaging(options =>
{
    options.ConnectionString = "your-connection-string";
});

// Map a queue entity and attach a handler
messaging.MapQueue<OrderCreated>("orders")
    .MapHandler(async (OrderCreated msg, IOrderRepository orders, CancellationToken ct) =>
    {
        await orders.CreateAsync(msg, ct);
    });

// Typed sender is auto-registered - inject IMessageSender<OrderCreated>
app.MapPost("/orders", async (CreateOrderRequest req, IMessageSender<OrderCreated> sender, CancellationToken ct) =>
{
    await sender.SendAsync(new OrderCreated(req.CustomerId, req.Items), ct);
    return Results.Accepted();
});

Documentation

Topic	Description
Patterns	Fire-and-forget, targeted commands, request/reply, polymorphic queues
Core Concepts	Handlers, message context, entity-first registration API
Configuration	Builder options, handler config, topology introspection
Error Handling	Custom error handlers, dead letter processing
Sessions	Session-enabled queues and subscriptions
Request/Reply	RPC-style request/response messaging
Middleware	Message processing pipeline
Batching	High-throughput batch processing
Observability	OpenTelemetry metrics and tracing
Azure Functions	Functions integration
Analyzers	Roslyn analyzers for compile-time checks
Testing	Integration testing with the Service Bus Emulator

Key Features

• Entity-first API - MapQueue<T>() / MapTopic<T>() return builders for handlers
• Polymorphic queues - MapPolymorphicQueue() routes multiple message types on one queue via MessageType discriminator
• Typed senders - IMessageSender<T> auto-registered per entity
• Minimal API-style handlers - delegates with automatic parameter binding
• DI integration - inject services directly into handler parameters
• Fluent configuration - handler-level options for concurrency, prefetch, auto-complete
• Topology introspection - discover required infrastructure at runtime
• Test harness - in-memory transport for unit testing
• Analyzers - catch common mistakes at compile time

Package Structure

Voltimax.Messaging                    # Core library
Voltimax.Messaging.HealthChecks       # Health check integration
Voltimax.Messaging.OpenTelemetry      # Telemetry instrumentation
Voltimax.Messaging.Testing            # Test harness and fakes
Voltimax.Messaging.Analyzers          # Roslyn analyzers (ships automatically)