Skip to content

Publish integration messages

When an outbox publisher is registered, every committed EventLoom event creates one durable outbox message in the same storage transaction. EventLoom does not create outbox messages when no publisher is configured. The message ID is the event’s UUIDv7 event ID. Register one transport-neutral publisher to deliver those messages:

builder.Services
.AddEventLoom()
.UsePostgreSql(builder.Configuration.GetConnectionString("EventStore")!)
.AddAggregate<Order, Guid>(aggregate => aggregate
.ConstructWith(id => new Order(id))
.UseStream("order", id => id.ToString("D")))
.AddOutboxPublisher<OrderIntegrationPublisher>();
public sealed class OrderIntegrationPublisher : IOutboxPublisher
{
public Task PublishAsync(OutboxMessage message, CancellationToken cancellationToken)
{
// Send message.Payload and message.Metadata to a broker or HTTP endpoint.
// Supply message.MessageId as the destination's idempotency key.
throw new NotImplementedException();
}
}

Register exactly one publisher. Its registration starts the hosted outbox worker. The worker reads each tenant’s unpublished messages in tenant-offset order and uses the fenced lease name outbox:publisher. PostgreSQL and MongoDB support multiple application instances; SQLite is appropriate only for one controlled instance.

Successfully published messages and their attempt history are deleted immediately by default. AddOutboxPublisher groups every outbox worker control—instance identity, polling interval, batch size, lease duration and renewal, retry attempts, and successful-delivery retention—behind one cohesive options callback:

builder.Services
.AddEventLoom()
.UsePostgreSql(builder.Configuration.GetConnectionString("EventStore")!)
.AddAggregate<Order, Guid>(aggregate => aggregate
.ConstructWith(id => new Order(id))
.UseStream("order", id => id.ToString("D")))
.AddOutboxPublisher<OrderIntegrationPublisher>(options =>
{
options.SuccessfulDeliveryRetention = TimeSpan.FromDays(7);
options.PollInterval = TimeSpan.FromSeconds(1);
options.BatchSize = 100;
options.MaxRetryAttempts = 5;
});

Outbox delivery is at least once. A process can publish a message successfully and stop before EventLoom records its success. EventLoom will then deliver the same message again. A publisher must make external effects idempotent using OutboxMessage.MessageId.

While a message exists, EventLoom persists every completed delivery attempt, including whether it succeeded and the exception type for failures. It deliberately does not store exception messages or payload copies in attempt history. Failed messages remain unpublished and are retried with bounded exponential backoff during the current worker iteration, then again on later polls. A successful message and its attempts remain inspectable only when a positive retention period is configured.

Configure a positive successful-delivery retention period, then use explicit tenant scope for administrative reads:

var message = await outboxAdministration.GetAsync("acme", messageId);
var attempts = await outboxAdministration.ReadAttemptsAsync("acme", messageId);

Normal appends commit independently. When application state and EventLoom events must commit or roll back together, use EventStore.BeginUnitOfWorkAsync().

Both contexts must first receive the same scoped DbConnection instance:

using System.Data.Common;
using EventLoom.EntityFrameworkCore;
using EventLoom.Storage;
using Microsoft.EntityFrameworkCore;
using Npgsql;
builder.Services.AddScoped<DbConnection>(_ =>
new NpgsqlConnection(builder.Configuration.GetConnectionString("App")!));
builder.Services.AddDbContext<OrderDbContext>((services, options) =>
options.UseNpgsql(services.GetRequiredService<DbConnection>()));
builder.Services
.AddEventLoom()
.UsePostgreSql(services => services.GetRequiredService<DbConnection>())
.AddAggregate<Order, Guid>(aggregate => aggregate
.ConstructWith(id => new Order(id))
.UseStream("order", id => id.ToString("D")));

Then enlist the application context into the shared transaction:

await using var unitOfWork = await eventStore.BeginUnitOfWorkAsync(cancellationToken);
await unitOfWork.EnlistAsync(orderDbContext, cancellationToken);
orderDbContext.Orders.Add(order);
await orderDbContext.SaveChangesAsync(cancellationToken);
await unitOfWork.AppendAsync(append, cancellationToken);
await unitOfWork.CommitAsync(cancellationToken);

MongoDB exposes the shared IClientSessionHandle through unitOfWork.Session:

using EventLoom.MongoDb;
using EventLoom.Storage;
using MongoDB.Driver;
await using var unitOfWork = await eventStore.BeginUnitOfWorkAsync(cancellationToken);
var orders = mongoClient.GetDatabase("eventloom").GetCollection<OrderDocument>("orders");
await orders.InsertOneAsync(unitOfWork.Session, new OrderDocument { Id = order.Id.ToString("D") }, cancellationToken: cancellationToken);
await unitOfWork.AppendAsync(append, cancellationToken);
await unitOfWork.CommitAsync(cancellationToken);

If a shared transaction is not required, prefer the normal append path plus the transactional outbox.