RepletoryLib.Messaging.Outbox 1.0.0

RepletoryLib.Messaging.Outbox

Transactional outbox pattern for reliable at-least-once message delivery with EF Core.

Part of the RepletoryLib ecosystem -- standalone, reusable .NET 10 libraries with zero business logic.

Overview

RepletoryLib.Messaging.Outbox implements the transactional outbox pattern to guarantee that messages are published reliably, even if the message broker is temporarily unavailable. Instead of publishing directly to RabbitMQ, messages are saved to an OutboxMessage table within the same database transaction as your business data. A background processor then publishes pending messages and handles retries.

Key Features

• Transactional consistency -- Messages saved in the same DB transaction as business data
• At-least-once delivery -- Background processor retries failed messages
• Configurable retry -- Max retry count with exponential backoff
• Batch processing -- Process multiple messages per polling cycle
• EF Core integration -- OutboxMessage entity with fluent configuration

Installation

dotnet add package RepletoryLib.Messaging.Outbox

Dependencies

Quick Start

using RepletoryLib.Messaging.Outbox;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRepletoryOutbox<AppDbContext>(builder.Configuration);

Add the outbox table to your DbContext:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.ApplyOutboxConfiguration();
}

{
  "Messaging": {
    "Outbox": {
      "PollingIntervalSeconds": 10,
      "BatchSize": 50,
      "MaxRetryCount": 5,
      "RetryBackoffSeconds": 30
    }
  }
}

Configuration

OutboxOptions

Usage Examples

Writing to the Outbox in a Transaction

using RepletoryLib.Messaging.Outbox.Interfaces;
using RepletoryLib.Messaging.Outbox.Entities;

public class OrderService
{
    private readonly AppDbContext _context;
    private readonly IOutboxRepository _outbox;

    public OrderService(AppDbContext context, IOutboxRepository outbox)
    {
        _context = context;
        _outbox = outbox;
    }

    public async Task CreateOrderAsync(Order order)
    {
        // Both saved in the same transaction
        _context.Orders.Add(order);

        await _outbox.AddAsync(new OutboxMessage
        {
            Type = nameof(OrderCreatedEvent),
            Payload = JsonSerializer.Serialize(new OrderCreatedEvent
            {
                OrderId = order.Id,
                Total = order.Total
            })
        });

        await _context.SaveChangesAsync();
        // OutboxProcessor will pick up the message and publish it
    }
}

How the Processor Works

The OutboxProcessor is a BackgroundService that:

1. Polls the OutboxMessage table every PollingIntervalSeconds
2. Fetches up to BatchSize unprocessed messages
3. Publishes each message via IMessagePublisher
4. Marks successful messages as processed
5. On failure, increments RetryCount and schedules NextRetryAt with backoff
6. After MaxRetryCount failures, stops retrying and logs the error

Integration with Other RepletoryLib Packages

Troubleshooting

License

This project is licensed under the MIT License.

Copyright (c) 2024-2026 Repletory.

For complete documentation, infrastructure setup, and configuration reference, see the RepletoryLib main repository.