Chapar.Zamin.Outbox 0.1.0

🐎 Chapar

Chapar is a clean, extensible, and business‑friendly messaging abstraction for .NET. It hides the complexity of RabbitMQ and MassTransit behind a minimal API, while providing out‑of‑the‑box support for the Outbox, Inbox, and Pipeline patterns.

Inspired by the ancient Persian courier system – fast, reliable, and invisible to the message sender.

Why Chapar?

• Zero ceremony: PublishAsync and SendAsync are all you need.
• Transparent Outbox / Inbox: Add one NuGet package and every message is automatically stored in the database before delivery. No code changes.
• Pipeline: a chain of configurable behaviours (logging, error handling, validation, …) that wrap every handler.
• Framework agnostic: works standalone or on top of Zamin.
• Transport agnostic: currently uses MassTransit v8 (free & community‑supported), with Wolverine coming soon.

Packages

Quick start (standalone)

dotnet add package Chapar
dotnet add package Chapar.MassTransit

services.AddChaparMassTransit(opt => opt.Host = "localhost");

// Define a message
public record OrderPlaced(Guid OrderId) : IEvent;

// Publish
var bus = provider.GetRequiredService<IChaparBus>();
await bus.PublishAsync(new OrderPlaced(Guid.NewGuid()));

// Handle
public class OrderPlacedHandler : IMessageHandler<OrderPlaced>
{
    public Task HandleAsync(OrderPlaced message, CancellationToken ct)
    {
        Console.WriteLine($"Order {message.OrderId} received.");
        return Task.CompletedTask;
    }
}

EF Core Outbox

Chapar.Outbox.EntityFrameworkCore stores outgoing messages in the application's EF Core context before they are delivered by the background publisher.

By default, outbox messages are staged and committed with the caller's unit of work:

services.AddChaparOutboxEntityFramework(options =>
{
    options.DefaultSaveMode = OutboxSaveMode.Transactional;
});

await bus.PublishAsync(new OrderPlaced(orderId));
await dbContext.SaveChangesAsync(ct);

This keeps the business data and the outbox row in the same database transaction.

For messages that should be persisted after the business transaction has already completed, use the EF outbox extension overloads:

using Chapar.Outbox.EntityFrameworkCore;
using Chapar.Outbox.EntityFrameworkCore.Extensions;

await dbContext.SaveChangesAsync(ct);

await bus.PublishAsync(
    new WelcomeSmsRequested(userId),
    OutboxSaveMode.Immediate,
    cancellationToken: ct);

Immediate performs a separate SaveChangesAsync through the outbox store. Use it after committing any business changes that must not be part of the outbox transaction.

Documentation

• Complete Guide – from simple publish/subscribe to advanced Outbox/Inbox, Pipeline, and Zamin integration.
• API Reference

Roadmap / Backlog

We welcome contributions! If you are interested in any of the items below, feel free to open an issue or send a pull request.

✅ Completed

🚧 In Progress (by core team)

💡 Backlog (up for grabs – contributions welcome!)

License

MIT