OutboxPattern

KO | EN

gitlite — search

#hacktoberfest #llm #go #machine-learning #linux #docker #macos #awesome #cli #vue #security #ios #mcp #open-source

(★ 9)

No description available.

OutboxPattern Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🧩 Domain Events & Outbox Pattern (.NET 9)

This challenge demonstrates how to implement **Domain Events** and the **Outbox Pattern** using **Entity Framework Core** with **SQLite** and **Background Services** in .NET 9.

It ensures domain events are saved atomically with aggregate changes and then published reliably from an **Outbox** table by a background dispatcher.

---

## 🚀 Tech Stack

| Component                  | Purpose                            |
| -------------------------- | ---------------------------------- |
| **.NET 9**                 | Framework                          |
| **EF Core + SQLite**       | Persistence layer                  |
| **SaveChangesInterceptor** | Captures domain events before save |
| **BackgroundService**      | Dispatches outbox messages         |
| **System.Text.Json**       | Serializes domain events           |
| **Swashbuckle.AspNetCore** | Swagger UI for testing endpoints   |

---

## 🏗️ Architecture Overview

```
┌────────────────────────────────────────┐
│           API  +  EF Core              │
│ ───────────────────────────────────── │
│  Order Aggregate raises Domain Event   │
│  → EF Interceptor saves Outbox row     │
│  → Transaction commits atomically      │
└──────────────┬─────────────────────────┘
               │
               ▼
       📨 Outbox Dispatcher (Hosted Service)
           ├─ Reads unprocessed messages
           ├─ Publishes events (console bus)
           └─ Marks as processed
```

---

## 📂 Project Structure

```
Challenge05_Outbox/
│
├── Program.cs
│
├── Domain/
│   ├── DomainEvent.cs
│   ├── IHasDomainEvents.cs
│   ├── Order.cs
│   └── OrderPlacedDomainEvent.cs
│
└── Infrastructure/
    ├── AppDbContext.cs
    ├── OutboxMessage.cs
    ├── OutboxDispatcher.cs
    ├── OutboxSaveChangesInterceptor.cs
    ├── IEventSerializer.cs
    └── SystemTextJsonEventSerializer.cs
```

---

## ⚙️ Setup Instructions

### 1️⃣ Clone the Repository

```bash
git clone https://github.com/YOUR_USERNAME/Challenge05_Outbox.git
cd Challenge05_Outbox
```

### 2️⃣ Install Dependencies

```bash
dotnet restore
dotnet add package Microsoft.EntityFrameworkCore.Sqlite
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Swashbuckle.AspNetCore
```

### 3️⃣ Create and Apply Migration

```bash
dotnet tool install --global dotnet-ef
dotnet ef migrations add Init
dotnet ef database update
```

This will create a local SQLite file: **`challenge05.db`**

---

## 🧩 Run the Project

```bash
dotnet run
```

Open:

* Swagger UI → [http://localhost:5000/swagger](http://localhost:5000/swagger)

---

## 🧪 Try It Out

### ➕ Create an Order

```bash
curl -X POST "http://localhost:5000/orders?total=49.99"
```

### 📬 Check Outbox Messages

```bash
curl "http://localhost:5000/outbox"
```

Console output example:

```
[BUS] ✅ OrderPlaced published => OrderId=6fdc..., Total=49.99
```

---

## 💾 Database Schema (Simplified)

| Table              | Purpose                         |
| ------------------ | ------------------------------- |
| **Orders**         | Domain aggregate                |
| **OutboxMessages** | Stores serialized domain events |

SQLite DDL:

```sql
CREATE TABLE "OutboxMessages" (
    "Id" INTEGER PRIMARY KEY AUTOINCREMENT,
    "OccurredOnUtc" TEXT NOT NULL,
    "Type" TEXT NOT NULL,
    "Payload" TEXT NOT NULL,
    "ProcessedOnUtc" TEXT NULL,
    "Error" TEXT NULL
);
CREATE INDEX "IX_OutboxMessages_ProcessedOnUtc"
ON "OutboxMessages" ("ProcessedOnUtc");
```

---

## 🔁 Event Flow

1. **Aggregate raises event**

```csharp
   AddEvent(new OrderPlacedDomainEvent(Id, Total));
   ```

2. **Interceptor captures it** during `SaveChangesAsync`
   and writes an `OutboxMessage` in the same transaction.

3. **Background service polls** for unprocessed messages
   and “publishes” them (here, simulated with console output).

4. **Marks processed** → `ProcessedOnUtc` is updated.

---

## 🧠 Key Files

* **OutboxSaveChangesInterceptor.cs** → Captures domain events pre-save
* **OutboxDispatcher.cs** → Processes messages asynchronously
* **SystemTextJsonEventSerializer.cs** → Serializes/deserializes events
* **AppDbContext.cs** → Entity mappings + EF setup

---

## 📦 NuGet Packages

| Package                              | Purpose               |
| ------------------------------------ | --------------------- |
| Microsoft.EntityFrameworkCore.Sqlite | SQLite provider       |
| Microsoft.EntityFrameworkCore.Design | CLI migrations        |
| Swashbuckle.AspNetCore               | Swagger documentation |
| Microsoft.Extensions.Hosting         | Background services   |
| Microsoft.Extensions.Logging.Console | Logging               |

---

## 🧱 Future Improvements

* Add retry & backoff policy in dispatcher
* Use a real message bus (e.g., RabbitMQ or Kafka)
* Introduce event versioning and handlers registry
* Add unit tests with InMemory EF provider

---

## 📜 License

This project is licensed under the **MIT License**.
Feel free to use / modify / share.

---

## 👤 Author

**Spyros Ponaris**
💼 [LinkedIn](https://www.linkedin.com/in/spyros-ponaris-913a6937/)

---

OutboxPattern

OutboxPattern Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

OutboxPattern

OutboxPattern Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README