GM.Messaging.Domain
2.0.0
See the version list below for details.
dotnet add package GM.Messaging.Domain --version 2.0.0
NuGet\Install-Package GM.Messaging.Domain -Version 2.0.0
<PackageReference Include="GM.Messaging.Domain" Version="2.0.0" />
<PackageVersion Include="GM.Messaging.Domain" Version="2.0.0" />
<PackageReference Include="GM.Messaging.Domain" />
paket add GM.Messaging.Domain --version 2.0.0
#r "nuget: GM.Messaging.Domain, 2.0.0"
#:package GM.Messaging.Domain@2.0.0
#addin nuget:?package=GM.Messaging.Domain&version=2.0.0
#tool nuget:?package=GM.Messaging.Domain&version=2.0.0
<p align="center"> <img src="https://raw.githubusercontent.com/gmetskhvarishvili/GM.Messaging/master/icon.png" alt="GM.Messaging" width="140" height="140" /> </p>
GM.Messaging
A lightweight messaging setup for .NET built on Wolverine and RabbitMQ.
One call wires up the message bus from configuration — connection, resilience (retry + circuit
breaker), and producer/consumer topology — with a transactional outbox/inbox for reliable,
integration events that are published at least once and handled once per consumer. Part of the GM.* family of packages. Targets net10.0.
Packages
This repository ships three packages that version and release in lockstep:
| Package | What it provides |
|---|---|
GM.Messaging |
AddGMMessaging (Wolverine + RabbitMQ wiring, resilience, topology) and AddGMOutboxRelay. |
GM.Messaging.Domain |
IntegrationEvent, [IntegrationEventName], and the InboxMessage / OutboxMessage entities. |
GM.Messaging.Persistence |
EF Core configurations, the transactional inbox (AddGMInbox), the inbox worker (AddGMInboxWorker), and telemetry names. |
Install
dotnet add package GM.Messaging
Register
using GM.Messaging;
builder.Services.AddGMMessaging(builder.Configuration);
Configure
Everything comes from the Messaging configuration section (shape matches MessagingOptions);
every value has a sensible default:
{
"Messaging": {
"ServiceName": "orders-service",
"RabbitMq": {
"HostName": "localhost",
"Port": 5672,
"VirtualHost": "/",
"UserName": "guest",
"Password": "guest"
},
"Retry": { "MaxAttempts": 5, "InitialDelayMilliseconds": 250 },
"CircuitBreaker": { "Enabled": true, "FailurePercentageThreshold": 25 },
"OutboxRelay": {
"BatchSize": 50,
"PollingIntervalSeconds": 5,
"MaxRetries": 5,
"RetryBaseDelaySeconds": 5,
"RetryMaxDelaySeconds": 300,
"LeaseSeconds": 60,
"RetentionDays": 7,
"CleanupIntervalMinutes": 60
},
"Inbox": {
"RetentionDays": 30,
"CleanupIntervalMinutes": 60,
"BatchSize": 50,
"PollingIntervalSeconds": 5,
"MaxConcurrency": 10,
"MaxAttempts": 5,
"RetryBaseDelaySeconds": 5,
"RetryMaxDelaySeconds": 300,
"LeaseSeconds": 60,
"ConsumerNames": []
}
}
}
Optional ProducerTopology / ConsumerTopology sections declare exchange/queue routes, and the
configureWolverine callback on AddGMMessaging lets you customize Wolverine directly.
Publish an integration event
[IntegrationEventName("orders.order-placed")] // optional, see "Event names" below
public record OrderPlaced(Guid OrderId) : IntegrationEvent;
// Save the event in the same transaction as the change that raised it.
dbContext.Add(order);
dbContext.Add(OutboxMessage.From(new OrderPlaced(order.Id)));
await dbContext.SaveChangesAsync();
The outbox relay then publishes it through Wolverine.
Wire the outbox and inbox
Both work directly on your DbContext. Map the tables with OutboxMessageConfiguration<T> and
InboxMessageConfiguration<T>, then:
// Producer: publishes the outbox and deletes published messages after RetentionDays
builder.Services.AddGMOutboxRelay<OutboxMessage, AppDbContext>();
// Consumer: a scoped IInboxProcessor, plus deletion of handled rows after RetentionDays
builder.Services.AddGMInbox<InboxMessage, AppDbContext>();
TOutboxMessage / TInboxMessage can be your own subclasses of the base entities; a private
parameterless constructor is enough (use Populate(evt) in a derived outbox type's factory).
The outbox relay
- Retries with backoff. A failed publish waits
RetryBaseDelaySeconds, doubling each time up toRetryMaxDelaySeconds. - Dead-letters. After
MaxRetriesfailures the message getsDeadLetteredAtUtc, is logged at error level, and is no longer tried. Fix the cause, then callmessage.Requeue()and save to try it again. - Runs in several processes. Each message is leased to one relay (
LockedBy,LockedUntilUtc) with a compare-and-set update before it is published, so an API and a worker can both run the relay. A message is published twice only if a relay stops mid-publish and its lease (LeaseSeconds) runs out; the consumer's inbox absorbs that. - Keeps the table small. Published messages are deleted after
RetentionDays(0 keeps them).
The project that calls AddGMOutboxRelay needs the GM.Messaging package, not just
GM.Messaging.Persistence. If you'd rather keep the persistence layer on GM.Messaging.Persistence
alone, call AddGMOutboxRelay from the host's Program.cs, or pass a flag into your persistence
registration (AddPersistence(configuration, runOutboxRelay: true)) to pick which hosts relay.
Handle an event once: ProcessAsync
public class OrderPlacedHandler(IInboxProcessor inbox, AppDbContext db)
{
public Task Handle(OrderPlaced message, CancellationToken ct) =>
inbox.ProcessAsync(message, "billing", () =>
{
db.Add(Invoice.For(message.OrderId));
return Task.CompletedTask; // ProcessAsync saves and commits
}, ct);
}
- One transaction. The inbox row and everything the handler saves through the same
DbContextcommit together. Changes made elsewhere (another database, an HTTP call) aren't covered. - Failures are retried. When the handler throws, its changes roll back, the error and attempt count are recorded on the row, and the exception reaches Wolverine, whose retry policy runs the handler again. Only a successful run marks the event handled.
- Duplicates are skipped, including two deliveries arriving at the same moment: the second waits on the first's row lock and then skips.
- Inside a transaction you opened yourself, the row joins it and you commit.
Handle it later: IngestAsync and the inbox worker
For work that shouldn't block the consumer (sending email, calling a slow API), store the event and let the inbox worker handle it:
builder.Services.AddGMInboxWorker<InboxMessage, AppDbContext>();
builder.Services.AddGMInboxHandler<UserRegistered, SendWelcomeEmail>();
// In the Wolverine handler:
public Task Handle(UserRegistered message, IInboxProcessor inbox, CancellationToken ct) =>
inbox.IngestAsync(message, "notifications", ct);
public class SendWelcomeEmail(IEmailSender email) : IInboxHandler<UserRegistered>
{
public Task HandleAsync(UserRegistered e, CancellationToken ct) => email.SendWelcomeAsync(e.Email, ct);
}
The worker leases rows like the relay (so it can run in several processes), runs up to
MaxConcurrency handlers at once, retries failures with backoff, and dead-letters a row after
MaxAttempts. InboxMessage.Requeue() makes a dead-lettered row pending again. Set ConsumerNames
to handle only some consumers' rows.
Event names
Each row stores the event's name: its [IntegrationEventName] if it has one, otherwise its full
type name (namespace and class, without the assembly). Moving an event to another assembly is safe.
Renaming the class or its namespace strands rows already written, unless the event keeps its old name
through [IntegrationEventName("…")]. Rows written by 1.x (assembly-qualified names) still resolve.
Observability
Add the GM.Messaging source and meter (MessagingTelemetry.Name) to OpenTelemetry:
builder.Services.AddOpenTelemetry()
.WithTracing(t => t.AddSource(MessagingTelemetry.Name))
.WithMetrics(m => m.AddMeter(MessagingTelemetry.Name));
The outbox stores the W3C trace context of the request that raised each event, and the relay publishes it in that trace, so a request, its published event and the consumer's handling show up as one trace. Metrics cover published, failed and dead-lettered messages, pending counts, publish lag, handled and duplicate inbox messages, and cleanup.
Upgrading from 1.x
2.0 adds columns to both tables, so add an EF Core migration in each service that maps them:
outbox_messages:next_attempt_at_utc,dead_lettered_at_utc,locked_by,locked_until_utc,trace_parent, and theix_outbox_messages_pendingindex.inbox_messages:attempts,ingested,next_attempt_at_utc,dead_lettered_at_utc,locked_by,locked_until_utc,trace_parent, and theix_inbox_messages_pendingindex.
Also changed:
IInboxStore<T>,IOutboxDbContext<T>andAddGMInboxProcessor<T>()are gone;AddGMInboxandAddGMOutboxRelaywork on theDbContextdirectly.IInboxProcessoris scoped (it shares the handler'sDbContext), so resolve it per message or scope, not from the root provider.- New rows store the event's full type name instead of its assembly-qualified name. Existing rows still resolve.
- Published outbox messages (after 7 days) and handled inbox rows (after 30 days) are now deleted.
Set
RetentionDaysto 0 to keep them. - Rows ingested by 1.x have
ingested = falseafter the migration, so the inbox worker ignores them. Finish them with your existing poller, or setingested = trueon them.
Local infrastructure
A docker-compose.yml is included to run PostgreSQL + RabbitMQ locally:
docker compose up gm.messaging.postgres gm.messaging.rabbitmq
Requirements
- .NET 10 SDK
- RabbitMQ (and a relational database for the outbox/inbox).
Contributing & releases
Versioning is automated from Conventional Commits — see CONTRIBUTING.md. All three packages release together under one version.
License
MIT — see LICENSE.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- No dependencies.
NuGet packages (3)
Showing the top 3 NuGet packages that depend on GM.Messaging.Domain:
| Package | Downloads |
|---|---|
|
GM.Messaging.Persistence
EF Core persistence for the GM.Messaging outbox/inbox: entity configurations, a transactional inbox with a retrying worker, retention cleanup, and DI wiring. Part of the GM.Messaging family. |
|
|
GM.Messaging
A lightweight messaging setup for .NET built on Wolverine and RabbitMQ. One call (AddGMMessaging) wires up the message bus with config-driven RabbitMQ connection, resilience (retry + circuit breaker) and producer/consumer topology, plus an outbox relay that retries with backoff, dead-letters, leases messages so it can run in several processes, cleans up old rows and continues traces. Part of the GM.Messaging family. |
|
|
GM.Testing.Messaging
Published-event capture for testing GM.Messaging consumers — assert "this integration event was published" without a real RabbitMQ broker. CapturingMessageBus stands in for Wolverine's IMessageBus and records every published/sent/scheduled message; PublishedMessages / Published<TEvent>() / ShouldHavePublished<TEvent>() make the assertions terse. Register with AddCapturingMessageBus() in a GmWebApplicationFactory override, or use the recorder directly in a unit test. Test-only (DevelopmentDependency). |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 5.0.0 | 83 | 11/17/2026 |
| 4.14.0 | 149 | 11/17/2026 |
| 4.13.0 | 72 | 11/17/2026 |
| 4.12.0 | 73 | 11/17/2026 |
| 4.11.0 | 71 | 11/17/2026 |
| 4.10.0 | 171 | 11/17/2026 |
| 4.9.0 | 72 | 11/17/2026 |
| 4.8.0 | 73 | 11/17/2026 |
| 4.7.0 | 74 | 11/17/2026 |
| 4.6.0 | 145 | 11/17/2026 |
| 4.5.0 | 90 | 11/16/2026 |
| 4.4.0 | 114 | 11/16/2026 |
| 4.3.0 | 125 | 11/16/2026 |
| 4.2.0 | 109 | 11/16/2026 |
| 4.1.0 | 241 | 11/16/2026 |
| 4.0.0 | 100 | 11/16/2026 |
| 3.0.0 | 153 | 11/16/2026 |
| 2.0.1 | 81 | 11/16/2026 |
| 2.0.0 | 83 | 11/16/2026 |
| 1.3.1 | 121 | 11/15/2026 |