Coder Legion - Recent posts tagged interceptors

Reliable Messaging in .NET: Domain Events and the Outbox Pattern with EF Core Interceptors

Mon, 13 Oct 2025 11:27:53 +0000

Introduction

Distributed systems are powerful — but they come with one big challenge: reliability.

What happens if your application updates a record in the database and then tries to publish a message to a message broker… but crashes in between?
You’ve just lost an event.

This problem is common in microservices, and it’s why the Outbox Pattern exists — a simple, elegant approach that guarantees message delivery without introducing distributed transactions or external coordinators.

In this article, we’ll implement a Domain Event + Outbox Pattern in .NET 9, using Entity Framework Core, SQLite, and an EF Core SaveChangesInterceptor.

⚙️ A Quick Look at Entity Framework Core

Entity Framework Core (EF Core) is Microsoft’s modern Object-Relational Mapper (ORM) for .NET.
It allows developers to work with a database using C# classes instead of raw SQL, automatically handling relationships, migrations, and change tracking.

When you call SaveChanges() or SaveChangesAsync(), EF Core:

Tracks your entity changes.
Generates SQL commands.
Executes them in a transaction.

This makes EF Core the perfect place to integrate the Outbox Pattern, since we can hook into its save pipeline and ensure domain events are written in the same transaction as the data itself.

What Are Interceptors?

In EF Core, interceptors are powerful hooks that allow you to intercept and extend the framework’s internal operations — such as saving, querying, or connecting to the database.

They work like middleware for EF Core:
you can observe, modify, or add logic before and after EF performs certain actions.

There are several types:

SaveChangesInterceptor
CommandInterceptor
ConnectionInterceptor
TransactionInterceptor

In this article, we’ll use SaveChangesInterceptor to detect domain events before EF saves, serialize them, and insert them into our Outbox table.

The Problem

In traditional architectures, your service might do something like this:

await _db.SaveChangesAsync();
await _bus.PublishAsync(new OrderPlacedEvent(orderId));

If your app crashes after saving but before publishing, your event never reaches other services — resulting in inconsistent state across systems.

We need a way to ensure atomicity: either both the data and the event are persisted, or neither are.

The Outbox Pattern (In a Nutshell)

The Outbox Pattern solves this by introducing a dedicated Outbox table inside your database.

When your aggregate raises a domain event, it’s captured and saved into the Outbox table within the same transaction as your entity.
A background worker (or a separate service) polls the Outbox table, publishes events, and marks them as processed.

This way, even if your app crashes, the events are safely stored and can be retried later.

The Architecture

┌──────────────────────────────┐
│         Application          │
│ ──────────────────────────── │
│  Order raises DomainEvent    │
│  → EF Interceptor writes     │
│    Outbox row                │
│  → Transaction commits       │
└──────────────┬───────────────┘
               │
               ▼
        Outbox Dispatcher
       ├─ Polls database
       ├─ Publishes messages
       └─ Marks them processed

This pattern elegantly blends Domain-Driven Design concepts with event-driven reliability.

Domain Events

Domain events capture something meaningful that happened in your domain model.
For example:

public sealed record OrderPlacedDomainEvent(Guid OrderId, decimal Total)
    : DomainEvent(DateTime.UtcNow);

And your aggregate raises them naturally:

public sealed class Order : IHasDomainEvents
{
    private readonly List<DomainEvent> _domainEvents = new();
    public Guid Id { get; private set; } = Guid.NewGuid();
    public decimal Total { get; private set; }

    public IReadOnlyCollection<DomainEvent> DomainEvents => _domainEvents;

    public Order(decimal total)
    {
        Total = total;
        AddEvent(new OrderPlacedDomainEvent(Id, Total));
    }

    private void AddEvent(DomainEvent @event) => _domainEvents.Add(@event);
    public void ClearDomainEvents() => _domainEvents.Clear();
}

⚙️ Capturing Events with an EF Core Interceptor

Instead of overriding SaveChangesAsync() directly inside AppDbContext, we can use a SaveChangesInterceptor — a clean, composable way to plug custom logic into EF’s lifecycle.


public sealed class OutboxSaveChangesInterceptor(IEventSerializer serializer) : SaveChangesInterceptor
{
    /// <summary>
    /// 
    /// </summary>
    /// <param name="eventData"></param>
    /// <param name="result"></param>
    /// <param name="cancellationToken"></param>
    /// <returns></returns>
    public override async ValueTask<InterceptionResult<int>> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult<int> result,
        CancellationToken cancellationToken = default)
    {
        var context = eventData.Context;
        if (context is null) 
            return await base.SavingChangesAsync(eventData, result, cancellationToken);

        var aggregates = context.ChangeTracker
                    .Entries()
                    .Where(e => e.Entity is IHasDomainEvents hasEvents && hasEvents.DomainEvents.Count > 0)
                    .Select(e => (IHasDomainEvents)e.Entity)
                    .ToList();

        if (aggregates.Count == 0)
            return await base.SavingChangesAsync(eventData, result, cancellationToken);

        var outbox = context.Set<OutboxMessage>();

        foreach (var aggregate in aggregates)
        {
            foreach (var @event in aggregate.DomainEvents)
            {
                outbox.Add(new OutboxMessage
                {
                    OccurredOnUtc = @event.OccurredOnUtc,
                    Type = @event.GetType().AssemblyQualifiedName!,
                    Payload = serializer.Serialize(@event)
                });
            }
        }

        return await base.SavingChangesAsync(eventData, result, cancellationToken);
    }

}

Now every time you call SaveChangesAsync(), domain events are written to your OutboxMessages table automatically — in the same transaction.

The Outbox Dispatcher

Once the transaction is committed, a background worker can safely process these messages.


public sealed class OutboxDispatcher(IServiceProvider sp, 
    ILogger<OutboxDispatcher> logger) : BackgroundService
{
    private readonly IServiceProvider _sp = sp;
    private readonly ILogger<OutboxDispatcher> _logger = logger;
    private readonly TimeSpan _pollInterval = TimeSpan.FromSeconds(2);
    private const int BatchSize = 50;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation(" Outbox Dispatcher started...");

        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                using var scope = _sp.CreateScope();
                var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();

                var jsonSerializer = scope.ServiceProvider.GetRequiredService<IEventSerializer>();

                var pending = await db.OutboxMessages
                    .Where(x => x.ProcessedOnUtc == null)
                    .OrderBy(x => x.Id)
                    .Take(BatchSize)
                    .ToListAsync(stoppingToken);

                foreach (var msg in pending)
                {
                    try
                    {
                        var evt = jsonSerializer.Deserialize(msg.Payload, msg.Type);
                        await SimulatedBusPublish(evt, stoppingToken);
                        msg.ProcessedOnUtc = DateTime.UtcNow;
                        msg.Error = null;
                    }
                    catch (Exception ex)
                    {
                        msg.Error = ex.Message;
                        _logger.LogError(ex, "❌ Error dispatching OutboxMessage {Id}", msg.Id);
                    }
                }

                if (pending.Count > 0)
                    await db.SaveChangesAsync(stoppingToken);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Outbox dispatcher loop error");
            }

            await Task.Delay(_pollInterval, stoppingToken);
        }
    }

    private Task SimulatedBusPublish(DomainEvent evt, CancellationToken ct)
        => evt switch
        {
            OrderPlacedDomainEvent e => HandleOrderPlaced(e),
            _ => Task.CompletedTask
        };

    private Task HandleOrderPlaced(OrderPlacedDomainEvent e)
    {
        Console.WriteLine($"[BUS] ✅ OrderPlaced published => OrderId={e.OrderId}, Total={e.Total}");

        return Task.CompletedTask;
    }
}

Why Use an Interceptor?

Using an interceptor instead of overriding SaveChangesAsync() has several advantages:

Approach	Pros	Cons
Override SaveChangesAsync	Simple to start	Harder to reuse across contexts
Use Interceptor	Decoupled, reusable, testable	Slightly more setup

Interceptors follow the Open/Closed Principle — your DbContext remains focused on persistence, while cross-cutting logic (like event logging, auditing, or outbox handling) is easily attachable.

Benefits of the Outbox Pattern

✅ Transactional Safety — data + events saved atomically
✅ Guaranteed Delivery — retries handled by dispatcher
✅ DDD Alignment — aggregates raise domain events naturally
✅ Resilience — works even if message broker is offline
✅ Extensibility — can integrate with RabbitMQ, Kafka, or Azure Service Bus later

References

✨ Closing Thoughts

The Domain Events + Outbox Pattern is one of the most practical ways to achieve reliable, eventually consistent event-driven systems in .NET.

By combining Entity Framework Core, SaveChangesInterceptor, and a simple background dispatcher, you can ensure every event is persisted and delivered — even in the face of failure.

Small pattern. Big reliability.

Author

Spyros Ponaris
LinkedIn
Senior Software Engineer & .NET Enthusiast

EF Core Interceptors: Supercharge Your Data Access with the Decorator Pattern

Thu, 20 Mar 2025 08:25:11 +0000

Learn how to hook into EF Core operations using interceptors, leverage the Decorator Pattern for clean cross-cutting concerns, and see real-world examples like SQL logging and auditing.

Table of Contents

A Brief History of EF Core Interceptors
What Are EF Core Interceptors?
EF Core Interceptors and the Decorator Pattern
Top Use Cases for EF Core Interceptors
Example 1: Logging SQL Queries
Example 2: Auditing SaveChanges
Final Thoughts

A Brief History of EF Core Interceptors

EF Core interceptors were first introduced in EF Core 3.0 (released in September 2019). This version marked a significant step forward in EF Core's extensibility, allowing developers to intercept low-level database operations like commands, connections, and transactions.

Since then, Microsoft has expanded interceptor capabilities in newer versions:

EF Core 5.0: Introduced SaveChanges interceptors for tracking changes at the context level.

EF Core 6.0+: Continued performance improvements and better support for asynchronous interception.

What Are EF Core Interceptors?

In Entity Framework Core (EF Core), interceptors allow developers to hook into the execution pipeline of EF Core's operations. Think of them as middleware for your database interactions. You can intercept events such as:

SQL command execution
Connection opening/closing
Transactions
SaveChanges lifecycle

This lets you inject custom logic like logging, auditing, validation, or performance metrics without modifying your application’s core logic.

EF Core Interceptors and the Decorator Pattern

EF Core interceptors are a real-world application of the Decorator Pattern, a classic design pattern where functionality is wrapped around existing behavior to extend or alter it.

The core EF operation is the base object.
Your interceptor is the decorator.
You add behavior before or after EF Core’s operation — without altering EF’s core.

This approach promotes clean code, separation of concerns, and makes your custom behavior reusable and testable.

Top Use Cases for EF Core Interceptors

– SQL Query Logging

– Track database queries for performance or debugging.

– Auditing – Automatically log user actions and timestamps.

– Soft Deletes – Intercept delete commands and convert them to updates.

– Command Modification – Change or enrich raw SQL before execution.

– Multi-Tenant Filtering – Inject filters dynamically for multi-tenant scenarios.

Example 1: Logging SQL Queries

Let’s log every SQL command executed by EF Core.

Step 1: Create a SQL Logging Interceptor

using Microsoft.EntityFrameworkCore.Diagnostics;
using System.Diagnostics;

public class SqlLoggingInterceptor : DbCommandInterceptor
{
    public override InterceptionResult<DbDataReader> ReaderExecuting(
        DbCommand command, 
        CommandEventData eventData, 
        InterceptionResult<DbDataReader> result)
    {
        Debug.WriteLine($"SQL Executed: {command.CommandText}");
        return base.ReaderExecuting(command, eventData, result);
    }
}

Output:

SQL Executed: SELECT * FROM [Users] WHERE [IsActive] = 1

Step 2: Register the Interceptor

public class AppDbContext : DbContext
{
    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder
            .UseSqlServer("YourConnectionString")
            .AddInterceptors(new SqlLoggingInterceptor());
    }
}

Example 2: Auditing SaveChanges

Let’s implement automatic auditing of entity modifications.

Step 1: Define an Auditable Entity Base Class

public abstract class AuditableEntity
{
    public DateTime ModifiedAt { get; set; }
    public string ModifiedBy { get; set; }
}

Step 2: Implement a SaveChangesInterceptor

public class AuditInterceptor : SaveChangesInterceptor
{
    private readonly string _currentUser;

    public AuditInterceptor(string currentUser)
    {
        _currentUser = currentUser;
    }

    public override int SavingChanges(DbContextEventData eventData, int result)
    {
        var context = eventData.Context;
        if (context == null) return base.SavingChanges(eventData, result);

        var entries = context.ChangeTracker
            .Entries<AuditableEntity>()
            .Where(e => e.State == EntityState.Modified);

        foreach (var entry in entries)
        {
            entry.Entity.ModifiedAt = DateTime.UtcNow;
            entry.Entity.ModifiedBy = _currentUser;
        }

        return base.SavingChanges(eventData, result);
    }
}

Final Thoughts

EF Core interceptors are an underutilized gem in the .NET ecosystem. They let you cleanly implement cross-cutting concerns without muddying your core application code. And because they follow the Decorator Pattern, you get flexibility, maintainability, and testability.

Whether you need to log queries, audit changes, enforce soft deletes, or handle custom behavior, interceptors offer a powerful and elegant solution.

References
EF Core Documentation – Interceptors
https://learn.microsoft.com/en-us/ef/core/logging-events-diagnostics/interceptors

EF Core 3.0 Release Notes (Interceptors introduced)
https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-3.0/whatsnew

EF Core SaveChanges Interceptor Docs
https://learn.microsoft.com/en-us/ef/core/logging-events-diagnostics/interceptors#savechanges-interception

Decorator Pattern - Refactoring Guru (for pattern explanation)
https://refactoring.guru/design-patterns/decorator

EF Core GitHub Repository (for latest updates and issues)
https://github.com/dotnet/efcore