Oragon.RabbitMQ 1.8.0

Oragon.RabbitMQ

Minimal APIs for RabbitMQ in .NET — Consume queues with the same MapQueue() pattern you already know from MapPost().

Oragon.RabbitMQ is not HTTP/Kestrel-based. It is a fully custom implementation built on RabbitMQ.Client 7.x natively.

Quality

Releases

Project

What is Oragon.RabbitMQ?

If you know ASP.NET Core Minimal APIs, you already know Oragon.RabbitMQ:

// ASP.NET Core — HTTP
app.MapPost("/orders", ([FromServices] OrderService svc, [FromBody] OrderCreated msg) => svc.HandleAsync(msg));

// Oragon.RabbitMQ — AMQP
app.MapQueue("orders", ([FromServices] OrderService svc, [FromBody] OrderCreated msg) => svc.HandleAsync(msg));

It provides everything you need to create resilient RabbitMQ consumers without the need to study numerous books and articles or introduce unknown risks to your environment. All queue consumption settings are configurable through a friendly, fluent, and consistent API.

Why Oragon.RabbitMQ?

• Minimal API design — familiar MapQueue() pattern, zero learning curve for ASP.NET Core developers
• RabbitMQ.Client 7.x native — no HTTP, no Kestrel, pure AMQP
• Near-zero overhead — benchmarks prove 0-1% overhead for I/O-bound workloads
• Built-in resilience — automatic Ack/Nack/Reject with manual acknowledgment by default
• DI-first — [FromServices], [FromBody], [FromAmqpHeader] attribute binding
• Pluggable serialization — System.Text.Json or Newtonsoft.Json out of the box
• Composable flow control — Ack, Nack, Reject, Reply, Forward, and Compose results
• .NET Aspire integration — first-class support via Oragon.RabbitMQ.AspireClient
• OpenTelemetry native — via RabbitMQ.Client 7.x built-in instrumentation
• Multi-framework — targets .NET 9 and 10

Quick Start

Standalone

dotnet add package Oragon.RabbitMQ
dotnet add package Oragon.RabbitMQ.Serializer.SystemTextJson

using Oragon.RabbitMQ;
using Oragon.RabbitMQ.Serializer;
using RabbitMQ.Client;

var builder = Host.CreateApplicationBuilder(args);

// 1. Register consumer infrastructure
builder.AddRabbitMQConsumer();

// 2. Register serializer
builder.Services.AddAmqpSerializer(options: JsonSerializerOptions.Default);

// 3. Register RabbitMQ connection
builder.Services.AddSingleton<IConnectionFactory>(sp => new ConnectionFactory()
{
    Uri = new Uri("amqp://guest:guest@localhost:5672"),
    DispatchConsumersAsync = true
});
builder.Services.AddSingleton(sp =>
    sp.GetRequiredService<IConnectionFactory>().CreateConnectionAsync().GetAwaiter().GetResult());

// 4. Register your service
builder.Services.AddSingleton<OrderService>(); // singleton, scoped or transient

var app = builder.Build();

Example 1

// 5. Map queue to handler
app.MapQueue("orders", ([FromServices] OrderService svc, OrderCreated msg) =>
    svc.HandleAsync(msg));

app.Run();

Example 2

Assume the service has a method CanProcess that returns a boolean.

app.MapQueue("orders", async ([FromServices] OrderService svc, OrderCreated msg) =>
{
    if (svc.CanProcess(msg))
    {
        await svc.HandleAsync(msg);
        return AmqpResults.Ack();
    }
    return AmqpResults.Nack(requeue: true);
});

Example 3

You can also handle exceptions yourself and return a valid IAmqpResult:

app.MapQueue("orders", async ([FromServices] OrderService svc, OrderCreated msg) =>
{
    try
    {
        await svc.HandleAsync(msg);
        return AmqpResults.Ack();
    }
    catch (Exception ex)
    {
        // Log the exception
        return AmqpResults.Nack(requeue: true);
    }
});

With .NET Aspire

Replace Aspire.RabbitMQ.Client with Oragon.RabbitMQ.AspireClient to get RabbitMQ.Client 7.x support and a built-in RabbitMQ health check without the AspNetCore.HealthChecks.Rabbitmq dependency:

dotnet add package Oragon.RabbitMQ.AspireClient

builder.AddRabbitMQClient("rabbitmq");

After Aspire.RabbitMQ.Client gains RabbitMQ.Client 7.x support, the Oragon.RabbitMQ.AspireClient package will be deprecated.

Packages

Configuration Reference

All configuration is done through fluent methods on the ConsumerDescriptor returned by MapQueue():

app.MapQueue("orders", ([FromServices] OrderService svc, OrderCreated msg) =>
    svc.HandleAsync(msg))
    .WithPrefetch(100)
    .WithDispatchConcurrency(8)
    .WhenProcessFail((ctx, ex) => AmqpResults.Nack(requeue: true));

Flow Control

By default, Oragon handles acknowledgments automatically:

• Success → BasicAck
• Serialization failure → BasicReject (no requeue) — use dead-lettering
• Processing failure → BasicNack (no requeue) — use dead-lettering

For explicit control, return an IAmqpResult from your handler:

Model Binding

Attributes

Auto-bound Types

These types are resolved automatically by the model binder without any attribute:

Auto-bound String Parameters

String parameters are matched by name convention:

Telemetry

RabbitMQ.Client 7.x implements native OpenTelemetry instrumentation via System.Diagnostics.ActivitySource. Your existing OpenTelemetry collectors will capture AMQP operations automatically without any additional configuration in this library.

Benchmarks

All benchmarks compare Oragon.RabbitMQ against hand-written native RabbitMQ.Client code performing the same DI scoping, serialization, try/catch, and ack/nack logic.

Environment: AMD Ryzen 9 9950X3D (16 cores / 32 threads), .NET 9.0.12, Windows 11, GC Server=True, BenchmarkDotNet v0.14.0.

Performance Summary

RPC Performance

Oragon is 7% faster and allocates 17% less memory for RPC by reusing pre-warmed infrastructure.

Memory Allocation Summary

Concurrency Scaling (I/O-Bound)

1000 messages with Task.Delay(5) handler. This is the most representative scenario for real-world workloads.

Conclusion: Ratio consistently between 0.98 - 1.01. Zero latency overhead for I/O-bound workloads.

Key Takeaways

1. I/O-bound workloads (the most common real-world scenario) — zero measurable overhead.
2. CPU-bound with small messages (worst case) — 5-10% overhead from DI scope + dispatch pipeline.
3. RPC — Oragon is faster and more memory-efficient than hand-written code.
4. The overhead is predictable and constant: ~3.5 ms fixed per message + ~2.5 KB of fixed allocation. In production workloads with larger messages and heavier handlers, this fixed cost becomes irrelevant.
5. Fair trade-off: For ~5% overhead in the worst case, Oragon provides: integrated DI, pluggable serialization, automatic error handling, declarative flow control, and a clean API.

Full benchmark results are available in benchmarks/Oragon.RabbitMQ.Benchmarks/BenchmarkDotNet.Artifacts/results/.

<details> <summary><strong>Design Philosophy</strong></summary>

Decoupling Business Logic from Infrastructure

Oragon.RabbitMQ is designed to decouple RabbitMQ consumers from business logic. Your business code remains completely unaware of the queue consumption context — resulting in simple, decoupled, agnostic, reusable, and highly testable code.

Manual Acknowledgment by Default

This consumer is focused on creating resilient consumers using manual acknowledgments (autoAck: false). The automatic flow handles Ack/Nack/Reject so you don't have to, but you can take control at any time by returning IAmqpResult.

Dead-Lettering as Recommended Pattern

Both serialization failures (Reject) and processing failures (Nack) default to no requeue. This is intentional — configure dead-letter exchanges on your queues to capture failed messages for inspection, replay, or alerting.

</details>

Samples

• Standalone sample — minimal console worker
• .NET Aspire sample — full Aspire integration

Tech

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT — LUIZ CARLOS FARIA - ACADEMIA.DEV - MENSAGERIA.NET