ModulusKit.Messaging.Abstractions 3.0.0

Modulus.Messaging.Abstractions

Abstractions for the Modulus messaging system — IMessageBus, IIntegrationEvent, and outbox pattern interfaces.

Installation

dotnet add package ModulusKit.Messaging.Abstractions

Key Types

Integration Events

// Define an integration event
public record OrderShipped(Guid OrderId, DateTime ShippedAt)
    : IntegrationEvent;

// IntegrationEvent base class auto-generates:
//   EventId      = Guid.NewGuid()
//   OccurredOn   = DateTime.UtcNow
//   CorrelationId = null (optional, settable via init)

Message Bus

public interface IMessageBus
{
    // Publish an event to all subscribers
    Task Publish<TEvent>(TEvent @event, CancellationToken ct = default)
        where TEvent : IIntegrationEvent;
}

Integration Event Handlers

public class OrderShippedHandler : IIntegrationEventHandler<OrderShipped>
{
    public Task Handle(OrderShipped @event, CancellationToken ct)
    {
        // React to the cross-module event
        return Task.CompletedTask;
    }
}

Outbox Pattern

The IOutboxStore interface enables the transactional outbox pattern — events are stored as database rows, then published reliably by a background processor with per-row retry backoff and dead-lettering. (Whether the row commits in the same transaction as your business data depends on how the store is configured — see the outbox documentation for the two supported setups.)

public interface IOutboxStore
{
    Task Save(IIntegrationEvent @event, CancellationToken cancellationToken = default);

    Task<IReadOnlyList<OutboxMessage>> GetPending(int batchSize, int maxAttempts, CancellationToken cancellationToken = default);

    Task<int> CountPending(int maxAttempts, CancellationToken cancellationToken = default);

    Task MarkAsProcessed(IEnumerable<Guid> ids, CancellationToken cancellationToken = default);

    Task MarkAsFailed(Guid messageId, string error, DateTime? nextAttemptOnUtc, CancellationToken cancellationToken = default);
}

GetPending skips dead-lettered rows (Attempts >= maxAttempts) and rows whose NextAttemptOnUtc backoff has not elapsed; MarkAsFailed records the failure and the next-attempt time computed from the retry policy. The inbox counterpart, IInboxStore, provides per-handler idempotent consumption (reserve → execute → mark processed, with reservation release on dead-letter).

Learn More

See the Modulus repository for full documentation.