Outbox

An output of some study time into exploration of the Transactional Outbox Pattern for reliable messaging in distributed systems.

Inspiration

• Milan Jovanovic Blog Post - Use of the Outbox Pattern in dotnet
• Microsoft Learn - CosmosDB Implementation
• Microsoft Learn - EF Interceptors

Update - May 2026

• Experimentation with Minimal API's and Vertical Slicing
• Tess Ferrandez Blog Post - Minimal API's
• Swapped out Api in Compose for this new approach
• Removed Swagger endpoint and added http file for testing
• Original API code still available in the src/Outbox.Api directory for reference

Local Development setup to run the example project

Requirements

• Docker

Usage

1. Build and run the project using Docker Compose
2. Navigate to the exposed UI endpoint, http://localhost:5002
3. Swagger UI is also available at http://localhost:5001 to interact with the API directly see May 2026 update above

# Common Commands

cd src                     # Navigate to the source code directory
docker compose up          # Will build and start the containers
docker compose up --build  # Will force a rebuild of the containers and start them
docker compose down        # Will stop and remove the containers and refresh the database

Overall Architecture

• API to add Users to the database
• EF Interceptor adds an entry to the Outbox table in the same transaction as the User creation
• Background Service to simulate a Worker/Processor role to poll the Outbox table and complete any unprocessed entries
• Basic UI to allow input and show the in flight processing of the Outbox entries (SignalR Hub for realtime updates to the UI)
• Uses SQL Server db container for persistence (originally planned to use CosmosDB, Azurite and Change Feed Function Triggers but ran into some issues with the local emulator and arm64 support, may revisit in the future. The vNext image currently has known Microsoft bugs)

Note

Lots not implemented here, e.g. retry processing on errors, lease locking for multiple workers, etc. This is a basic starting point to demonstrate the pattern and some of the implementation details.