https://github.com/underground-dotnet/outbox
https://github.com/underground-dotnet/outbox
dotnet outbox
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/underground-dotnet/outbox
- Owner: underground-dotnet
- License: mit
- Created: 2025-08-02T14:03:10.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-01-03T11:07:25.000Z (5 months ago)
- Last Synced: 2026-01-07T04:37:41.611Z (5 months ago)
- Topics: dotnet, outbox
- Language: C#
- Homepage:
- Size: 143 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Outbox Library
The Outbox Library is a .NET Core library designed to simplify the implementation of the outbox pattern in your applications. The outbox pattern ensures reliable message delivery by storing messages in a database and processing them asynchronously, making it ideal for distributed systems and event-driven architectures.
## Transactional outbox
There are usually two different types of implementations when it comes to the outbox pattern:
### Using multiple transactions
The outbox processor is fetching a batch of outbox messages and marks them as `in processing` by updating a column in the outbox table. Then using a second transaction to process the messages.
Using this approach you have short lived transactions, but you need to deal with cases of releasing the lock on the rows when a processor fails.
### Using one transaction
The outbox processor is fetching a batch of outbox messages (sometimes with the addition of `SELECT FOR UPDATE SKIP LOCKED`) and uses the same transaction to process the messages.
This ensure that updating the messages table as well as any business logic tables is done in the same transaction (all or nothing). For larger batches it increases the risk of long running transactions.
For this library the single transaction approach was chosen. Messages in a batch will be processed until processing of one message fails.
## Features
- **EF Core**: This library is fully built on top of EF Core.
- **Inbox and Outbox Support**: Provides interfaces and implementations for managing inbox and outbox messages.
- **Transactional**: Message batches are processed within one transaction.
- **Distributed Lock**: When multiple instances of the application are running then a distributed lock ensures that the outbox is only processed by a single conusmer.
- **Error Handling**: Built-in exception handling for common scenarios.
## Getting Started
### Installation
To use the Underground Outbox Library in your project, add the NuGet package:
```bash
dotnet add package Underground.Outbox
```
### Configuration
1. **Add Services**: Configure the outbox services in your `Program.cs` file:
```csharp
builder.Services.AddOutboxServices(cfg =>
{
cfg.AddHandler();
});
builder.Services.AddInboxServices(cfg =>
{
cfg.AddHandler();
});
```
2. **Adjust DbContext**: Add interfaces and message types to your DbContext. This ensures that you can use EF migrations to add the tables to your database.
```csharp
sealed class AppDbContext(DbContextOptions options) : DbContext(options), IOutboxDbContext, IInboxDbContext
{
public DbSet OutboxMessages { get; set; }
public DbSet InboxMessages { get; set; }
}
```
3. **Handle Messages**: Create message handlers by implementing `IInboxMessageHandler` and `IOutboxMessageHandler`.
```csharp
using Underground.Outbox;
public class ExampleMessageHandler : IOutboxMessageHandler
{
public Task HandleAsync(ExampleMessage message, CancellationToken cancellationToken)
{
// Process the message
return Task.CompletedTask;
}
}
```
### Usage
1. **Add Messages to the Outbox**:
```csharp
using var transaction = await dbContext.Database.BeginTransactionAsync();
await outbox.AddMessageAsync(new ExampleMessage { Content = "Hello, World!" });
await transaction.CommitAsync();
```
2. **The background processor will call the handlers during the next run.**
## Example
Run example:
```bash
dotnet run --project example/ConsoleApp/
```
## License
This project is licensed under the MIT License.