LinKit.Outbox 1.0.0

LinKit.Outbox

LinKit.Outbox provides high-performance, zero-reflection, and Native AOT compatible primitives for implementing the Transactional Outbox and Idempotent Inbox patterns in distributed .NET systems.

Guarantees At-Least-Once Delivery and Exactly-Once Processing across microservices and modular monoliths without runtime reflection or heavy external dependencies.

🚀 Key Features

• Zero Reflection & Native AOT Ready: All serializers and handlers run with compile-time safety and zero reflection overhead.
• Database Agnostic: Works seamlessly with Entity Framework Core, Dapper, Marten, or raw ADO.NET.
• Transactional Outbox: Reliably records outgoing integration messages within the business transaction boundary.
• Idempotent Inbox: Automatically deduplicates incoming messages to protect business logic against duplicate event deliveries.
• Optimized Background Worker: Efficient periodic polling with exponential backoff and batch dispatching.

📦 Installation

dotnet add package LinKit.Outbox

🛠️ Usage Guide

1. Store Outbox Messages in Business Transactions

When executing your CQRS Command Handler, record the outbox message inside the same database transaction:

using LinKit.Outbox;

public class CreateOrderHandler : ICommandHandler<CreateOrderCommand, Guid>
{
    private readonly IOutboxStore _outboxStore;
    private readonly AppDbContext _db;

    public CreateOrderHandler(IOutboxStore outboxStore, AppDbContext db)
    {
        _outboxStore = outboxStore;
        _db = db;
    }

    public async Task<Guid> HandleAsync(CreateOrderCommand command, CancellationToken ct)
    {
        var order = new Order(command.CustomerId, command.Amount);
        _db.Orders.Add(order);

        // Stage outbox message in the same local transaction
        await _outboxStore.SaveMessageAsync(new OutboxMessage
        {
            Id = Guid.NewGuid(),
            MessageType = typeof(OrderCreatedIntegrationEvent).AssemblyQualifiedName!,
            Payload = JsonSerializer.Serialize(new OrderCreatedIntegrationEvent(order.Id), AppJsonSerializerContext.Default.OrderCreatedIntegrationEvent),
            CreatedAt = DateTimeOffset.UtcNow
        }, ct);

        await _db.SaveChangesAsync(ct);
        return order.Id;
    }
}

2. Idempotent Inbox Consumer

Prevent duplicate execution when consuming messages:

using LinKit.Outbox;

public class OrderCreatedIntegrationEventHandler : ICommandHandler<OrderCreatedIntegrationEvent>
{
    private readonly IInboxStore _inboxStore;

    public OrderCreatedIntegrationEventHandler(IInboxStore inboxStore)
    {
        _inboxStore = inboxStore;
    }

    public async Task HandleAsync(OrderCreatedIntegrationEvent evt, CancellationToken ct)
    {
        // Check if message was already processed
        if (await _inboxStore.HasProcessedAsync(evt.MessageId, ct))
        {
            return; // Skip duplicate message safely
        }

        // Execute idempotently
        await ProcessOrderAsync(evt, ct);

        // Mark as processed
        await _inboxStore.MarkProcessedAsync(evt.MessageId, ct);
    }
}

3. Register Services in Program.cs

using LinKit.Outbox;

var builder = WebApplication.CreateBuilder(args);

// Register LinKit Core & Outbox
builder.Services.AddLinKitCqrs();
builder.Services.AddLinKitOutbox<MySqlOutboxStore, MySqlInboxStore>(options =>
{
    options.BatchSize = 100;
    options.PollIntervalSeconds = 5;
    options.MaxRetries = 3;
});

📄 License

Licensed under the MIT License.