DEV Community: Milan Jovanović

Building a Custom Domain Events Dispatcher in .NET

Milan Jovanović — Sat, 24 May 2025 00:00:00 +0000

Domain events are a powerful way to decouple parts of your system. Instead of tightly coupling your logic, you can publish events and have other parts of your code subscribe to those events. This pattern is especially valuable in Domain-Driven Design (DDD) where business logic should remain focused and cohesive.

In this article, we'll walk through how to implement a lightweight, custom domain event dispatcher in .NET. The core dispatching logic should not depend on third-party libraries.

We'll cover:

Why you might want to use publish-subscribe in your application
How to define basic domain event abstractions
How to implement and register handlers
How to build a domain events dispatcher
Trade-offs and when to consider other options

Let's get started.

Why Domain Events Matter

Before diving into implementation, let's understand the problem domain events solve. Consider this tightly coupled code:

public class UserService
{
    public async Task RegisterUser(string email, string password)
    {
        var user = new User(email, password);
        await _userRepository.SaveAsync(user);

        // Directly coupled to email service
        await _emailService.SendWelcomeEmail(user.Email);

        // Directly coupled to analytics
        await _analyticsService.TrackUserRegistration(user.Id);

        // What if we need to add more features?
        // This method will keep growing...
    }
}

With domain events, we can decouple this:

public class UserService
{
    public async Task RegisterUser(string email, string password)
    {
        var user = new User(email, password);
        await _userRepository.SaveAsync(user);

        // Publish event - let other parts of the system react
        await _domainEventsDispatcher.DispatchAsync(
            [new UserRegisteredDomainEvent(user.Id, user.Email)]);
    }
}

Now the UserService focuses solely on user registration, while other concerns are handled through event handlers.

Basic Abstractions

Let's start by defining two simple interfaces that form the foundation of our event system:

// Marker interface for all domain events.
public interface IDomainEvent
{
    // We could add common properties here like:
    // DateTime OccurredAt { get; }
    // Guid EventId { get; }
}

// Generic interface for handling domain events.
public interface IDomainEventHandler<in T> where T : IDomainEvent
{
    Task Handle(T domainEvent, CancellationToken cancellationToken = default);
}

This design gives us type safety through generic constraints while keeping publishers and handlers completely decoupled. You can add new events or handlers without touching existing code, and everything remains easily testable in isolation.

Implementing Sample Handlers

Let's add some sample handlers that demonstrate how different parts of your system can react to the same event:

// Handles sending welcome emails when users register
internal sealed class SendWelcomeEmailHandler(IEmailService emailService) 
    : IDomainEventHandler<UserRegisteredDomainEvent>
{
    public async Task Handle(
        UserRegisteredDomainEvent domainEvent,
        CancellationToken cancellationToken = default)
    {
        // Send welcome email
        var welcomeEmail = new WelcomeEmail(domainEvent.Email, domainEvent.UserId);

        await emailService.SendAsync(welcomeEmail, cancellationToken);
    }
}

// Handles analytics tracking for new user registrations
internal sealed class TrackUserRegistrationHandler(IAnalyticsService analyticsService) 
    : IDomainEventHandler<UserRegisteredDomainEvent>
{
    public async Task Handle(
        UserRegisteredDomainEvent domainEvent,
        CancellationToken cancellationToken = default)
    {
        // Track registration in analytics
        await analyticsService.TrackEvent(
            "user_registered",
            new
            {
                user_id = domainEvent.UserId,
                registration_date = domainEvent.RegisteredAt
            },
            cancellationToken);
    }
}

To make this work, we need to register our handlers with the DI container.

Here's how to do it manually:

// In your Program.cs or Startup.cs
services.AddScoped<IDomainEventHandler<UserRegisteredDomainEvent>, SendWelcomeEmailHandler>();
services.AddScoped<IDomainEventHandler<UserRegisteredDomainEvent>, TrackUserRegistrationHandler>();

Or you can automate this registration using assembly scanning with Scrutor:

services.Scan(scan => scan.FromAssembliesOf(typeof(DependencyInjection))
    .AddClasses(classes => classes.AssignableTo(typeof(IDomainEventHandler<>)), publicOnly: false)
    .AsImplementedInterfaces()
    .WithScopedLifetime());

The important thing is that multiple handlers can react to the same event.

The Dispatcher (Strongly Typed)

Now we need something to orchestrate calling the handlers. The dispatcher will take the domain events and call the appropriate handlers for each event.

public interface IDomainEventsDispatcher
{
    Task DispatchAsync(
        IEnumerable<IDomainEvent> domainEvents,
        CancellationToken cancellationToken = default);
}

internal sealed class DomainEventsDispatcher(IServiceProvider serviceProvider)
    : IDomainEventsDispatcher
{
    private static readonly ConcurrentDictionary<Type, Type> HandlerTypeDictionary = new();
    private static readonly ConcurrentDictionary<Type, Type> WrapperTypeDictionary = new();

    public async Task DispatchAsync(
        IEnumerable<IDomainEvent> domainEvents,
        CancellationToken cancellationToken = default)
    {
        foreach (IDomainEvent domainEvent in domainEvents)
        {
            using IServiceScope scope = serviceProvider.CreateScope();

            Type domainEventType = domainEvent.GetType();

            Type handlerType = HandlerTypeDictionary.GetOrAdd(
                domainEventType,
                et => typeof(IDomainEventHandler<>).MakeGenericType(et));

            IEnumerable<object?> handlers = scope.ServiceProvider.GetServices(handlerType);

            foreach (object? handler in handlers)
            {
                if (handler is null) continue;

                var handlerWrapper = HandlerWrapper.Create(handler, domainEventType);

                await handlerWrapper.Handle(domainEvent, cancellationToken);
            }
        }
    }

    // Abstract base class for strongly-typed handler wrappers
    private abstract class HandlerWrapper
    {
        public abstract Task Handle(IDomainEvent domainEvent, CancellationToken cancellationToken);

        public static HandlerWrapper Create(object handler, Type domainEventType)
        {
            Type wrapperType = WrapperTypeDictionary.GetOrAdd(
                domainEventType,
                et => typeof(HandlerWrapper<>).MakeGenericType(et));

            return (HandlerWrapper)Activator.CreateInstance(wrapperType, handler)!;
        }
    }

    // Generic wrapper that provides strong typing for handler invocation
    private sealed class HandlerWrapper<T>(object handler) : HandlerWrapper where T : IDomainEvent
    {
        private readonly IDomainEventHandler<T> _handler = (IDomainEventHandler<T>)handler;

        public override async Task Handle(
            IDomainEvent domainEvent,
            CancellationToken cancellationToken)
        {
            await _handler.Handle((T)domainEvent, cancellationToken);
        }
    }
}

The dispatcher uses a wrapper to eliminate reflection during handler execution while maintaining type safety. When we encounter a UserRegisteredDomainEvent, we create a HandlerWrapper<UserRegisteredDomainEvent>that holds a strongly-typed reference to IDomainEventHandler<UserRegisteredDomainEvent>. The wrapper casts the generic IDomainEvent to the specific event type at runtime, but the actual handler invocation uses compile-time types.

This gives us the performance benefits of avoiding reflection in the hot path (handler execution) while only using reflection once during wrapper creation. The trade-off is additional complexity, but the performance gain is significant if you're dispatching many events.

Don't forget to register the dispatcher with DI:

services.AddTransient<IDomainEventsDispatcher, DomainEventsDispatcher>();

Usage Example

Here's how to use the domain events dispatcher in your application:

public class UserController(
    IUserService userService, 
    IDomainEventsDispatcher domainEventsDispatcher) : ControllerBase
{
    [HttpPost("register")]
    public async Task<IActionResult> Register([FromBody] RegisterUserRequest request)
    {
        try
        {
            // Create the user
            var user = await userService.CreateUserAsync(request.Email, request.Password);

            // Publish the domain event
            var userRegisteredEvent = new UserRegisteredDomainEvent(user.Id, user.Email);

            await domainEventsDispatcher.DispatchAsync([userRegisteredEvent]);

            return Ok(new { UserId = user.Id, Message = "User registered successfully" });
        }
        catch (Exception ex)
        {
            return BadRequest(new { Error = ex.Message });
        }
    }
}

You could also integrate domain events directly into your domain entities.

Limitations and Tradeoffs

This implementation runs entirely in-process, which has important implications. All handlers execute synchronously within the same request context, but each gets its own DI scope. This means:

Immediate feedback : If any handler fails, the exception bubbles up to the caller immediately. No silent failures or eventual consistency surprises.
Caller control : The code that dispatches events decides how to handle failures — rollback transactions, retry operations, or continue despite errors. The dispatcher doesn't make these decisions for you.
Reliability concerns : If the process crashes after some handlers succeed but before others complete, there's no automatic recovery. Events aren't persisted or retried.

For critical side effects that can't be lost, consider the Outbox pattern. Instead of dispatching events immediately, store them alongside your business data in the same transaction. A background service can later retry failed events, ensuring nothing gets lost. This decouples reliability from performance — your main operation completes quickly while events are processed reliably in the background.

Wrapping Up

Domain events are a powerful pattern for decoupling business logic, and you don't need a heavyweight framework to use them effectively. The implementation we've built here provides a solid foundation that you can extend as your needs grow.

The beauty of rolling your own solution is that you understand every piece, making debugging and customization straightforward. This pattern fits excellently in Domain-Driven Design andClean Architecture systems where decoupling business logic is crucial.

For systems requiring bulletproof reliability or cross-service communication, invest in proper message infrastructure. But for many applications, this simple approach hits the sweet spot between coupling and complexity.

The key insight is understanding your trade-offs upfront rather than discovering them in production. Start simple, measure what matters, and evolve based on real requirements.

P.S. Whenever you're ready, there are 3 ways I can help you:

Pragmatic Clean Architecture: Join 3,700+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.
Modular Monolith Architecture: Join 1,600+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.
Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.

CQRS Pattern the Way It Should've Been From the Start

Milan Jovanović — Sat, 17 May 2025 00:00:00 +0000

MediatR is going commercial.

Jimmy Bogard recently announcedthat MediatR will adopt a commercial license model for companies above a certain size.

For many teams, this is a trigger to re-evaluate their usage and possibly look for alternatives.

And it's not a bad time to do so. MediatR became almost synonymous with CQRS in .NET, despite the fact that CQRS and MediatR are not the same thing. Most projects use it as a thin dispatching layer for commands and queries — a use case that can be covered with a few straightforward abstractions.

By removing MediatR, you gain:

Full control over your CQRS infrastructure
Predictable, explicit handler dispatching
Simpler debugging and onboarding
Cleaner DI setup and better testability

In this article, I'll walk you through building a minimal CQRS setup with just a few interfaces and support for decorators. No hidden DI magic. Just clean, predictable code.

We'll cover:

Defining ICommand, IQuery, and handler contracts
Adding support for decorators (logging, validation, etc.)
Registering everything with DI
A full working example in a real-world scenario

Let's get started.

Commands, Queries, and Handlers

Let's start by defining the basic contracts for commands and queries.

// ICommand.cs
public interface ICommand;
public interface ICommand<TResponse>;

// IQuery.cs
public interface IQuery<TResponse>;

These interfaces exist purely as markers. They allow us to structure application logic around intention — write operations go through ICommand, read operations through IQuery.

The handler interfaces follow the same model:

// ICommandHandler.cs
public interface ICommandHandler<in TCommand>
    where TCommand : ICommand
{
    Task<Result> Handle(TCommand command, CancellationToken cancellationToken);
}

public interface ICommandHandler<in TCommand, TResponse>
    where TCommand : ICommand<TResponse>
{
    Task<Result<TResponse>> Handle(TCommand command, CancellationToken cancellationToken);
}


// IQueryHandler.cs
public interface IQueryHandler<in TQuery, TResponse>
    where TQuery : IQuery<TResponse>
{
    Task<Result<TResponse>> Handle(TQuery query, CancellationToken cancellationToken);
}

These are nearly identical to MediatR's IRequest and IRequestHandler APIs, making migration trivial if you're moving off of MediatR.

You'll notice we're using a Result wrapper for all return types. This is optional, but it promotes explicit success/failure handling and encourages consistency across the application boundary. You can learn more about it in my previous article.

These interfaces form a lightweight CQRS infrastructure, focused purely on intent and separation of concerns. No mediator, no runtime indirection — just clear contracts for handling reads and writes.

Practical Example: Command Handler

To see these abstractions in action, let's implement a command that marks a todo item as completed.

// CompleteTodoCommand.cs
public sealed record CompleteTodoCommand(Guid TodoItemId) : ICommand;

// CompleteTodoCommandHandler.cs
internal sealed class CompleteTodoCommandHandler(
    IApplicationDbContext context,
    IDateTimeProvider dateTimeProvider,
    IUserContext userContext)
    : ICommandHandler<CompleteTodoCommand>
{
    public async Task<Result> Handle(CompleteTodoCommand command, CancellationToken cancellationToken)
    {
        TodoItem? todoItem = await context.TodoItems
            .SingleOrDefaultAsync(
                t => t.Id == command.TodoItemId && t.UserId == userContext.UserId,
                cancellationToken);

        if (todoItem is null)
        {
            return Result.Failure(TodoItemErrors.NotFound(command.TodoItemId));
        }

        if (todoItem.IsCompleted)
        {
            return Result.Failure(TodoItemErrors.AlreadyCompleted(command.TodoItemId));
        }

        todoItem.IsCompleted = true;
        todoItem.CompletedAt = dateTimeProvider.UtcNow;

        todoItem.Raise(new TodoItemCompletedDomainEvent(todoItem.Id));

        await context.SaveChangesAsync(cancellationToken);

        return Result.Success();
    }
}

A few important things to note:

The command is an immutable value object (just data, no behavior).
The handler encapsulates all business logic: validation, state change, raising domain events, and persistence.
There's no mediator, no ISender, no hidden dispatching. The handler is invoked directly via our custom abstractions.

This makes intent explicit, avoids magic, and keeps the dependencies minimal.

We'll look at how to add decorators next, so we can introduce things like logging, validation, or transactions without modifying the handler itself.

Decorators

To support cross-cutting concerns like logging, validation, and transactions, we apply the decorator pattern around our handlers. Technically, this is closer to the proxy pattern , since we're injecting behavior before/after delegating to the real handler. But in the context of cross-cutting concerns, most people refer to this as a decorator — which is fine for our purposes.

Let's look at two examples: one for logging, one for validation.

using Serilog.Context;

internal sealed class LoggingCommandHandler<TCommand, TResponse>(
    ICommandHandler<TCommand, TResponse> innerHandler,
    ILogger<CommandHandler<TCommand, TResponse>> logger)
    : ICommandHandler<TCommand, TResponse>
    where TCommand : ICommand<TResponse>
{
    public async Task<Result<TResponse>> Handle(TCommand command, CancellationToken cancellationToken)
    {
        string commandName = typeof(TCommand).Name;

        logger.LogInformation("Processing command {Command}", commandName);

        Result<TResponse> result = await innerHandler.Handle(command, cancellationToken);

        if (result.IsSuccess)
        {
            logger.LogInformation("Completed command {Command}", commandName);
        }
        else
        {
            using (LogContext.PushProperty("Error", result.Error, true))
            {
                logger.LogError("Completed command {Command} with error", commandName);
            }
        }

        return result;
    }
}

This class wraps any ICommandHandler<TCommand, TResponse>, injecting the decorated handler as innerHandler. It adds structured logging around the command execution without touching the core business logic.

Now a validation example with FluentValidation:

using FluentValidation;
using FluentValidation.Results;

internal sealed class ValidationCommandHandler<TCommand, TResponse>(
    ICommandHandler<TCommand, TResponse> innerHandler,
    IEnumerable<IValidator<TCommand>> validators)
    : ICommandHandler<TCommand, TResponse>
    where TCommand : ICommand<TResponse>
{
    public async Task<Result<TResponse>> Handle(TCommand command, CancellationToken cancellationToken)
    {
        // Validate the command using all registered validators
        ValidationFailure[] validationFailures = await ValidateAsync(command, validators);

        if (validationFailures.Length == 0)
        {
            return await innerHandler.Handle(command, cancellationToken);
        }

        // If validation fails, return a failure result with the errors
        return Result.Failure<TResponse>(CreateValidationError(validationFailures));
    }

    private static async Task<ValidationFailure[]> ValidateAsync<TCommand>(
        TCommand command,
        IEnumerable<IValidator<TCommand>> validators)
    {
        if (!validators.Any())
        {
            return [];
        }

        var context = new ValidationContext<TCommand>(command);

        ValidationResult[] validationResults = await Task.WhenAll(
            validators.Select(validator => validator.ValidateAsync(context)));

        ValidationFailure[] validationFailures = validationResults
            .Where(validationResult => !validationResult.IsValid)
            .SelectMany(validationResult => validationResult.Errors)
            .ToArray();

        return validationFailures;
    }

    private static ValidationError CreateValidationError(ValidationFailure[] validationFailures) =>
        new(validationFailures.Select(f => Error.Problem(f.ErrorCode, f.ErrorMessage)).ToArray());
}

Each decorator handles a single concern and can be layered transparently around the core handler.

Important: Since we're working with generic interfaces (ICommandHandler<,>, IQueryHandler<,>), each decorator must explicitly target the same generic contract. That means you'll need separate decorator classes for each handler abstraction you're using (e.g. command with result, command without result, query with result).

In the next section, we'll wire this up using Scrutor. It's a simple assembly scanning library that helps us register and decorate handlers cleanly. Yes, it uses reflection, but only during startup — and it's fully transparent and predictable.

DI Setup

With our handlers and decorators in place, we can register everything using Scrutor.

services.Scan(scan => scan.FromAssembliesOf(typeof(DependencyInjection))
    .AddClasses(classes => classes.AssignableTo(typeof(IQueryHandler<,>)), publicOnly: false)
        .AsImplementedInterfaces()
        .WithScopedLifetime()
    .AddClasses(classes => classes.AssignableTo(typeof(ICommandHandler<>)), publicOnly: false)
        .AsImplementedInterfaces()
        .WithScopedLifetime()
    .AddClasses(classes => classes.AssignableTo(typeof(ICommandHandler<,>)), publicOnly: false)
        .AsImplementedInterfaces()
        .WithScopedLifetime());

This scans the application assembly and registers all command and query handlers (including internal types) as their respective interfaces.

Next, we apply decorators for validation and logging:

services.Decorate(typeof(ICommandHandler<,>), typeof(ValidationDecorator.CommandHandler<,>));
services.Decorate(typeof(ICommandHandler<>), typeof(ValidationDecorator.CommandBaseHandler<>));

services.Decorate(typeof(IQueryHandler<,>), typeof(LoggingDecorator.QueryHandler<,>));
services.Decorate(typeof(ICommandHandler<,>), typeof(LoggingDecorator.CommandHandler<,>));
services.Decorate(typeof(ICommandHandler<>), typeof(LoggingDecorator.CommandBaseHandler<>));

Each Decorate call wraps the previous registration. Order matters , but it might not be intuitive at first glance.

The last decorator applied will be the outermost one at runtime. So in this example:

The base handler is first decorated by validation
That composite is then decorated again by logging

Which means the logging decorator runs first , followed by validation , and then the core handler.

This order allows logging to capture the full command lifecycle, including any early exits from validation failures.

With this setup, you now have a fully functional and extensible CQRS pipeline:

Custom handler interfaces
Clean decorator chain
Assembly-scanned DI setup

Usage from Minimal API

Once everything is wired up, using a command handler from a Minimal API endpoint is straightforward:

internal sealed class Complete : IEndpoint
{
    public void MapEndpoint(IEndpointRouteBuilder app)
    {
        app.MapPut("todos/{id:guid}/complete", async (
            Guid id,
            ICommandHandler<CompleteTodoCommand> handler,
            CancellationToken cancellationToken) =>
        {
            var command = new CompleteTodoCommand(id);

            Result result = await handler.Handle(command, cancellationToken);

            return result.Match(Results.NoContent, CustomResults.Problem);
        })
        .WithTags(Tags.Todos)
        .RequireAuthorization();
    }
}

We're injecting the appropriate ICommandHandler<CompleteTodoCommand> directly into the endpoint. No need for ISender, no mediator layer, no runtime lookup.

This keeps the endpoint clean and focused on its primary responsibility: handling HTTP requests.

Everything is resolved explicitly by the container. This makes the code easier to test, reason about, and trace while maintaining all the benefits of CQRS and separation of concerns.

Conclusion

CQRS doesn't require a complex framework.

With a few small interfaces, some decorator classes, and a clean DI setup, you can build a simple and flexible pipeline for handling commands and queries. It's easy to understand, easy to test, and easy to extend.

If you want to see this pattern applied in a complete solution, my free Clean Architecture template includes everything covered in this article (fully wired up).

Use it as a reference or as a starting point for your next project.

P.S. Whenever you're ready, there are 3 ways I can help you:

Pragmatic Clean Architecture: Join 3,700+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.
Modular Monolith Architecture: Join 1,600+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.
Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.

From Anemic Models to Behavior-Driven Models: A Practical DDD Refactor in C#

Milan Jovanović — Sat, 10 May 2025 00:00:00 +0000

If you've ever worked with a legacy C# codebase, you know the pain of an anemic domain model. You have probably opened an OrderService (all similarities to production code are merely a coincidence) and thought _"this file does everything."_Pricing logic, discount rules, stock checks, database writes — all jam-packed into one class. It works — until it doesn't. New features turn into regression roulette , and test coverage plummets because the domain is buried under infrastructure.

This is the classic symptom of an anemic domain model, where entities are nothing but data holders, and all logic lives elsewhere. It makes the system harder to reason about, and every change becomes a guessing game. But what if we could push behavior back into the domain, one rule at a time?

In this article, we'll:

Inspect a typical anemic implementation.
Identify hidden business rules that make it brittle.
Refactor toward a behavior-rich aggregate one refactor at a time.
Highlight the concrete payoffs so you can justify the change to teammates.

Everything fits in a 6-minute read, but the pattern scales to any legacy system.

Starting Point: God-like Service Class

Below is an (unfortunately common) OrderService. Besides calculating totals it also:

applies a 5 % VIP discount ,
throws if any product is out of stock , and
rejects orders that would exceed the customer's credit limit.

// OrderService.cs
public void PlaceOrder(Guid customerId, IEnumerable<OrderItemDto> items)
{
    var customer = _db.Customers.Find(customerId);
    if (customer is null)
    {
        throw new ArgumentException("Customer not found");
    }

    var order = new Order { CustomerId = customerId };

    foreach (var dto in items)
    {
        var inventory = _inventoryService.GetStock(dto.ProductId);
        if (inventory < dto.Quantity)
        {
            throw new InvalidOperationException("Item out of stock");
        }

        var price = _pricingService.GetPrice(dto.ProductId);
        var lineTotal = price * dto.Quantity;
        if (customer.IsVip)
        {
            lineTotal *= 0.95m; // 5% discount for VIPs
        }

        order.Items.Add(new OrderItem
        {
            ProductId = dto.ProductId,
            Quantity = dto.Quantity,
            UnitPrice = price,
            LineTotal = lineTotal
        });
    }

    order.Total = order.Items.Sum(i => i.LineTotal);

    if (customer.CreditUsed + order.Total > customer.CreditLimit)
    {
        throw new InvalidOperationException("Credit limit exceeded");
    }

    _db.Orders.Add(order);
    _db.SaveChanges();
}

What's Wrong Here?

Scattered rules: Discount application, stock validation, and credit-limit checks are buried inside the service.
Tight coupling: OrderService must know about pricing, inventory, and EF Core just to place an order.
Painful testing: Each unit test needs fakes for DB access, pricing, inventory, and VIP vs. non-VIP flows.

Goal: Embed these rules inside the domain so the application layer only deals with orchestration.

Guiding Principles Before We Touch Code

Protect invariants close to the data. Stock, discounts, and credit checks belong where the data lives — inside the Order aggregate.
Expose intent, hide mechanics. The application layer should read like a story: "place order", not "calculate totals, check credit, write to DB".
Refactor in slices. Each move is safe and compilable; no big-bang rewrites.
Balance purity with pragmatism. Move rules only when the payoff (clarity, safety, testability) beats the extra lines of code.

Step-by-Step Refactor

The goal here isn't to chase purity or academic DDD. It's to incrementally improve cohesion and make room for the domain to express itself.

At every step, we ask: Is this behavior something the domain should own? If yes, we pull it inward.

Embed Creation & Validation Logic

The first move is to make the aggregate responsible for building itself. A static Create method gives us a single entry point where all invariants can fail fast.

While pushing stock validation into Order improves testability, it does couple the order flow with inventory availability. In some domains, you'd instead model this as a domain event and validate asynchronously.

// Order.cs (Factory Method)
public static Order Create(
    Customer customer,
    IEnumerable<(Guid productId, int quantity)> lines,
    IPricingService pricingService,
    IInventoryService inventoryService)
{
    var order = new Order(customer.Id);

    foreach (var (productId, quantity) in lines)
    {
        if (inventoryService.GetStock(productId) < quantity)
        {
            throw new InvalidOperationException("Item out of stock");
        }

        var unitPrice = pricingService.GetPrice(productId);
        order.AddItem(productId, quantity, unitPrice, customer.IsVip);
    }

    order.EnsureCreditWithinLimit(customer);

    return order;
}

Why? Creation now fails fast if any invariant is broken. The service no longer micromanages stock or discounts.

Notice how we're now following the "Tell, Don't Ask" principle. Rather than the service checking conditions and then manipulating the Order, we're telling the Order to create itself with the necessary validations built in. This is a fundamental shift toward encapsulation.

💡 On Double-Dispatch in Domain Methods

Passing services into domain methods like Order.Create might raise a few eyebrows. But in this case, it's an explicit form of double-dispatch that enables us to keep complex logic inside the domain model without bloating the application service. It gives the entity autonomy while still respecting dependency injection principles — the services are passed explicitly, not resolved implicitly. That said, this approach is best used sparingly and only when the operation truly belongs inside the domain object.

Guard the Aggregate's Internal State

// Order.cs (excerpt)
private readonly List<OrderItem> _items = new();
public IReadOnlyCollection<OrderItem> Items => _items.AsReadOnly(); // C# 12 -> [.._items]

private void AddItem(Guid productId, int quantity, decimal unitPrice, bool isVip)
{
    if (quantity <= 0)
    {
        throw new ArgumentException("Quantity must be positive");
    }

    var finalPrice = isVip ? unitPrice * 0.95m : unitPrice;
    _items.Add(new OrderItem(productId, quantity, finalPrice));

    RecalculateTotal();
}

private void EnsureCreditWithinLimit(Customer customer)
{
    if (customer.CreditUsed + Total > customer.CreditLimit)
    {
        throw new InvalidOperationException("Credit limit exceeded");
    }
}

Why bother?

Encapsulation : Consumers can't mutate _items directly, ensuring invariants hold.
Self-protection : The domain model protects its own consistency rather than relying on service-level checks.
True OOP : Objects now combine data and behavior, as object-oriented programming intended.
Simpler services : Application services can focus on coordination rather than business rules.

Shrink the Application Layer to Pure Orchestration

public void PlaceOrder(Guid customerId, IEnumerable<OrderLineDto> lines)
{
    var customer = _db.Customers.Find(customerId);
    if (customer is null)
    {
        throw new ArgumentException("Customer not found");
    }
    var input = lines.Select(l => (l.ProductId, l.Quantity));

    var order = Order.Create(customer, input, _pricingService, _inventoryService);

    _db.Orders.Add(order);
    _db.SaveChanges();
}

The PlaceOrder method drops from 44 lines to 14 , with zero business logic.

What We Gained

Before the refactor

Service owned pricing, stock, discount, and credit checks.
Unit tests required heavy EF Core and service fakes.
Adding a new rule meant touching multiple files.

After the refactor

Aggregate owns all business rules; service only orchestrates.
Pure domain tests — no database container required.
Most changes are isolated to the Order aggregate.

Wrapping Up

The real value in refactoring anemic models isn't technical — it's strategic.

By moving business logic closer to the data, you:

Reduce the blast radius of changes
Make business rules explicit and testable
Open the door for tactical patterns like validation, events, and invariants

But you don't need a big rewrite. Start with one rule. Refactor it. Then the next.

That's how legacy systems evolve into maintainable architectures.

If you enjoyed this breakdown and want a hands-on, real-world guide to untangling messy services, check out my course Domain-Driven Design Refactoring. It's packed with before-and-after examples like this one.

P.S. Whenever you're ready, there are 3 ways I can help you:

Pragmatic Clean Architecture: Join 4,000+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.
Modular Monolith Architecture: Join 1,800+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.
Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.

Event-Driven Architecture in .NET with RabbitMQ

Milan Jovanović — Sat, 03 May 2025 00:00:00 +0000

Event-driven architecture (EDA) can make applications more flexible and reliable. Instead of one part of the system calling another directly, we let events flow through a message broker. In this quick guide, I'll show you how to set up a simple event-driven system in .NET using RabbitMQ.

We'll build a small example with a producer that sends events and a consumer that receives them. For testing, I'll run RabbitMQ in a Docker container (with the Management UI enabled so we can see what's happening). We'll use the official RabbitMQ.Client NuGet package in a .NET console app.

Note: If you don't have RabbitMQ installed, you can run it quickly with Docker. For example:

docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:4-management

This starts a RabbitMQ broker on localhost (AMQP port 5672) and a management website at http://localhost:15672.

RabbitMQ Basics

Before coding, let's cover the basic components in RabbitMQ:

Producer : an application that sends messages (events) to RabbitMQ.
Queue : a mailbox inside RabbitMQ that stores messages. Consumers read from queues. Many producers can send to the same queue.
Consumer : an application that receives messages from a queue.
Exchange : a routing mechanism that receives messages from producers and directs them to queues. Producers actually send to an exchange instead of directly to a queue. This decouples producers from specific queues - the exchange can decide where messages go, based on rules.

In RabbitMQ, you can have multiple producers and multiple consumers. Producers never send directly to a queue by name; instead, they send to an exchange. The exchange decides which queues (if any) should get each message based on routing rules.

For now, we'll use a simple setup where the exchange will deliver all messages to one queue.

Producer - Sending Events

Let's start with the producer. In our .NET console app, we'll use RabbitMQ.Client to connect to the RabbitMQ broker and send a message.

For instance, an OrderPlaced event could trigger downstream services - inventory, email notifications, etc. - without the ordering system needing to call them directly.

var factory = new ConnectionFactory() { HostName = "localhost" };
using var connection = await factory.CreateConnectionAsync();
using var channel = await connection.CreateChannelAsync();

// Ensure the queue exists (create it if not already there)
await channel.QueueDeclareAsync(
    queue: "orders",
    durable: true, // save to disk so the queue isn’t lost on broker restart
    exclusive: false, // can be used by other connections
    autoDelete: false, // don’t delete when the last consumer disconnects
    arguments: null);

// Create a message
var orderPlaced = new OrderPlaced
{
     OrderId = Guid.NewGuid(),
     Total = 99.99,
     CreatedAt = DateTime.UtcNow
};
var message = JsonSerializer.Serialize(orderPlaced);
var body = Encoding.UTF8.GetBytes(message);

// Publish the message
await channel.BasicPublishAsync(
    exchange: string.Empty, // default exchange
    routingKey: "orders",
    mandatory: true, // fail if the message can’t be routed
    basicProperties: new BasicProperties { Persistent = true }, // message will be saved to disk
    body: body);

Console.WriteLine($"Sent: {message}");

This code connects to RabbitMQ on localhost, declares a queue named orders (creates it if it doesn't exist already), and publishes an OrderPlaced message to that queue. We use an empty string for the exchange parameter, which tells RabbitMQ to use the default exchange. The default exchange routes the message directly to the orders queue.

What's happening here:

We declare a durable queue , so it survives RabbitMQ restarts
We mark the message as persistent , which tells RabbitMQ to write it to disk
We serialize an object into JSON and send it as a UTF-8 encoded byte array

Now let's look at the consumer side.

Consumer - Receiving Events

Next, let's set up a consumer to receive messages from the queue. The consumer will also connect to RabbitMQ and subscribe to the same queue.

To test this out, start the consumer application first (it will wait for messages), then run the producer application to send an event.

var factory = new ConnectionFactory() { HostName = "localhost" };
using var connection = await factory.CreateConnectionAsync();
using var channel = await connection.CreateChannelAsync();

// Declare (or check) the queue to consume from
await channel.QueueDeclareAsync(
    queue: "orders",
    durable: true, // must match the producer's queue settings
    exclusive: false, // can be used by other connections
    autoDelete: false, // don’t delete when the last consumer disconnects
    arguments: null);

// Define a consumer and start listening
var consumer = new AsyncEventingBasicConsumer(channel);
consumer.ReceivedAsync += async (sender, eventArgs) =>
{
    byte[] body = eventArgs.Body.ToArray();
    string message = Encoding.UTF8.GetString(body);
    var orderPlaced = JsonSerializer.Deserialize<OrderPlaced>(message);

    Console.WriteLine($"Received: OrderPlaced - {orderPlaced.OrderId}");

    // Acknowledge the message
    await ((AsyncEventingBasicConsumer)sender)
        .Channel.BasicAckAsync(eventArgs.DeliveryTag, multiple: false);
};
await channel.BasicConsumeAsync("orders", autoAck: false, consumer);

Console.WriteLine("Waiting for messages...");

The consumer code declares the same orders queue and sets up an event handler for incoming messages. We call BasicConsumeAsync to start listening on the queue. RabbitMQ will push any new messages to our consumer's event handler. Whenever a message arrives, the consumer.ReceivedAsync event fires, and we print out the message.

What's important here:

autoAck: false ensures we only acknowledge messages we actually process
If processing fails, we could use BasicNack to requeue or route to a dead-letter queue
Deserializing into a strongly typed object makes it easy to reason about the event

So far we've had one consumer. But what if we run multiple consumers on the same queue?

Competing Consumers - Scaling Out

What if you have multiple consumers for the same queue? RabbitMQ allows competing consumers on a queue.

If two or more consumers listen on the same queue, each message from that queue will be delivered to only one of them:

RabbitMQ will distribute messages among the consumers (roughly in round-robin order)
This is great for scaling: you can run multiple instances of a worker to process messages in parallel

In other words, consumers compete for messages on that queue. This pattern helps spread the workload, but note that each individual message is still processed by a single consumer.

Fanout Exchange: Broadcast to Multiple Consumers

Competing consumers share the work by dividing messages, but sometimes you want every service to get the event. That's where a fanout exchange comes in.

In RabbitMQ, a fanout exchange is used for broadcasting events to multiple consumers. Instead of all consumers sharing one queue, each consumer has its own queue. When the producer sends a message to a fanout exchange, the exchange copies and routes the message to all bound queues. This way, every consumer receives a copy via its own queue.

To set this up in code, we declare a fanout exchange and bind queues to it.

Producer :

// Producer setup for fanout
await channel.ExchangeDeclareAsync(
    exchange: "orders",
    durable: true, // durable exchange
    autoDelete: false, // don’t delete when the last consumer disconnects
    type: ExchangeType.Fanout);

// Publish a message to the fanout exchange (routingKey is ignored for fanout)
var orderPlaced = new OrderPlaced
{
     OrderId = Guid.NewGuid(),
     Total = 99.99,
     CreatedAt = DateTime.UtcNow
};
var message = JsonSerializer.Serialize(orderPlaced);
var body = Encoding.UTF8.GetBytes(message);

await channel.BasicPublishAsync(
    exchange: "orders",
    routingKey: string.Empty,
    mandatory: true,
    basicProperties: new BasicProperties { Persistent = true },
    body: body);

Consumer :

// Consumer setup for fanout
await channel.ExchangeDeclareAsync(
    exchange: "orders",
    durable: true,
    autoDelete: false,
    type: ExchangeType.Fanout);

// Create a queue for this consumer and bind it
await channel.QueueDeclareAsync(
    queue: "orders-consumer-1",
    durable: true,
    exclusive: false,
    autoDelete: false,
    arguments: null);

await channel.QueueBindAsync("orders-consumer-1", "orders", routingKey: string.Empty);

// Then consume messages from queueName as usual...

In the producer, we call ExchangeDeclareAsync to make sure an orders exchange exists (of type fanout). We then BasicPublishAsync to that exchange. For a fanout exchange, the routingKey can be an empty string because it's ignored (fanout sends to all queues regardless of any routing key). On the consumer side, we declare the same exchange and then create a new orders-consumer-1 queue. We bind that queue to the orders exchange. Now any message sent to the exchange will be delivered to this queue, and we can consume it.

If you run multiple consumer programs (each with its own queue bound to orders exchange), each one will get every message (unlike the competing consumers scenario). You can also peek into RabbitMQ's Management UI to see the exchange and queues in action.

Next Steps

You can expand this basic setup with more advanced RabbitMQ features. For example, you might use a direct exchange or topic exchange to route events to specific services, set up acknowledgment and retry policies for robustness, or implement dead-letter queues for error handling. The core idea throughout is the same: decouple senders and receivers with an event broker, making your system more flexible and resilient.

If you want to explore event-driven architecture further, including patterns like the ones we touched on (and beyond), check out my Modular Monolith Architecture course. It covers these concepts in depth with practical examples, so you can apply EDA in real-world projects.

Good luck out there, and see you next week.

P.S. Whenever you're ready, there are 3 ways I can help you:

Pragmatic Clean Architecture: Join 4,000+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.
Modular Monolith Architecture: Join 1,800+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.
Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.

Refactoring Overgrown Bounded Contexts in Modular Monoliths

Milan Jovanović — Sat, 26 Apr 2025 00:00:00 +0000

When you're building a modular monolith, it's easy to let bounded contexts grow too large over time. What started as a clean domain boundary slowly turns into a dumping ground for unrelated logic. Before you know it, you have a massive context responsible for users, payments, notifications, and reporting - all tangled together.

This article is about tackling that mess. We'll walk through how to identify an overgrown bounded context, and refactor it step-by-step into smaller, well-defined contexts. You'll see practical techniques in action, with real .NET code and without theoretical fluff.

Identifying an Overgrown Context

You know you have a problem when:

You're afraid to touch code because everything is interconnected
The same entity is used for 4 unrelated use cases
You see classes with 1000+ lines or services that do too much
Business logic from different subdomains bleeds into each other

Here's a classic example.

We start with a BillingContext that now handles everything from notifications to reporting:

public class BillingService
{
    public void ChargeCustomer(int customerId, decimal amount) { ... }
    public void SendInvoice(int invoiceId) { ... }
    public void NotifyCustomer(int customerId, string message) { ... }
    public void GenerateMonthlyReport() { ... }
    public void DeactivateUserAccount(int userId) { ... }
}

This service has no clear boundaries. It mixes Billing , Notifications , Reporting , and User Management into a single, bloated class. Changing one feature could easily break another.

Step 1: Identify Logical Subdomains

We start by breaking this apart logically. Think like a product owner.

Just ask: "What domains are we really working with?"

Group the methods:

Billing : ChargeCustomer, SendInvoice
Notifications : NotifyCustomer
Reporting : GenerateMonthlyReport
User Management : DeactivateUserAccount

Code within a bounded context should model a coherent domain. When multiple domains are jammed into the same context, your architecture becomes misleading.

You can validate these groupings by checking:

Which parts of the system change together?
Do teams use different vocabulary for each area?
Would you give each domain to a different team?

If yes, it's a sign you're dealing with distinct contexts.

Step 2: Extract One Context at a Time

Don't try to do it all at once. Start with something low-risk.

Let's begin by extracting Notifications.

Why Notifications? Because it's a pure side-effect. It doesn't impact business state, so it's easier to decouple safely.

Create a new module and move the logic there:

// New module: Notifications
public class NotificationService
{
    public void Send(int customerId, string message) { ... }
}

Then simplify the original BillingService:

public class BillingService
{
    private readonly NotificationService _notificationService;

    public BillingService(NotificationService notificationService)
    {
        _notificationService = notificationService;
    }

    public void ChargeCustomer(int customerId, decimal amount)
    {
        // Charge logic...
        _notificationService.Send(customerId, $"You were charged ${amount}");
    }
}

This works. But now Billing depends on Notifications. That's a coupling we want to avoid long-term.

Why? Because a failure in Notifications could block a billing operation. It also means Billing can't evolve independently.

Let's decouple with domain events:

public class CustomerChargedEvent
{
    public int CustomerId { get; init; }
    public decimal Amount { get; init; }
}

// Module: Billing
public class BillingService
{
    private readonly IDomainEventDispatcher _dispatcher;

    public BillingService(IDomainEventDispatcher dispatcher)
    {
        _dispatcher = dispatcher;
    }

    public void ChargeCustomer(int customerId, decimal amount)
    {
        // Charge logic...
        _dispatcher.Dispatch(new CustomerChargedEvent
        {
            CustomerId = customerId,
            Amount = amount
        });
    }
}

// Module: Notifications
public class CustomerChargedEventnHandler : IDomainEventHandler<CustomerChargedEvent>
{
    public Task Handle(CustomerChargedEvent @event)
    {
        // Send notification
    }
}

Now Billing doesn't even know about Notifications. That's real modularity. You can replace, remove, or enhance the Notifications module without touching Billing.

Step 3: Migrate Data (If Needed)

Most monoliths start with a single database. That's fine. But real modularity comes when each module controls its own schema.

Why? Because the database structure reflects ownership. If everything touches the same tables, it's hard to enforce boundaries.

You don't have to do it all at once. Start with:

Creating a separate DbContext per module
Gradually migrate the tables to their own schemas
Read-only projections or database views for cross-context reads

// Module: Billing
public class BillingDbContext : DbContext
{
    public DbSet<Invoice> Invoices { get; set; }
}

// Module: Notifications
public class NotificationsDbContext : DbContext
{
    public DbSet<NotificationLog> Logs { get; set; }
}

This separation enables independent schema evolution. It also makes testing faster and safer.

When migrating, use a transitional phase where both contexts read from the same underlying data. Only switch write paths when confidence is high.

Step 4: Repeat for Other Areas

Apply the same playbook. Target a clean split per subdomain.

Next up: Reporting and User Management.

Before:

billingService.GenerateMonthlyReport();
billingService.DeactivateUserAccount(userId);

After:

reportingService.GenerateMonthlyReport();
userService.DeactivateUser(userId);

Or via events:

_dispatcher.Dispatch(new MonthEndedEvent());
_dispatcher.Dispatch(new UserInactiveEvent(userId));

The goal here isn't just technical cleanliness - it's clarity. Anyone looking at your solution should know what each module is responsible for.

And remember: boundaries should be enforced by code, not just by folder structure. Different projects, separate EF models, and explicit interfaces help enforce the split.Architecture tests can also help ensure that modules don't break their boundaries.

Takeaway

Once you've finished the refactor, you'll have:

Smaller services focused on one job
Decoupled modules that evolve independently
Better tests and easier debugging
Bounded contexts that actually match the domain

This is more than structure, it's design that supports change. You get loose coupling, testability, and clearer mental models.

You don't need microservices to get modularity. You need to treat your monolith like a set of cooperating, isolated parts.

Start with one module. Ship the change. Repeat.

Want to go deeper into modular monolith design? My full video course, Modular Monolith Architecture, walks you through building a real-world system from scratch - with clear boundaries, isolated modules, and practical patterns that scale. Join 1,800+ students and start building better systems today.

That's all for today.

See you next Saturday.

P.S. Whenever you're ready, there are 3 ways I can help you:

Pragmatic Clean Architecture: Join 4,000+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.
Modular Monolith Architecture: Join 1,800+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.
Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.

Understanding Microservices: Core Concepts and Benefits

Milan Jovanović — Sat, 19 Apr 2025 00:00:00 +0000

I've been revisiting Sam Newman's excellent book "Monolith to Microservices" recently, and it's reminded me just how transformative this architectural approach can be when applied correctly.

As someone who's implemented microservices in various organizations, I wanted to share some valuable insights I've gained through both study and practical experience.

What exactly are microservices, and why might they be the right architectural choice for your organization?

Let's dive into the core concepts and benefits of microservices architecture.

What Are Microservices?

Microservices are independently deployable services modeled around a business domain. Business domain is key here, but more on that later. They communicate with each other via networks and offer many options for solving complex architectural problems.

Think of microservices as small, focused teams rather than a large department. Each team has a specific responsibility, operates somewhat independently, and communicates clearly with other teams when needed. Instead of one massive codebase that handles everything, you have multiple smaller codebases, each focusing on a specific business capability.

As Sam Newman defines them in "Monolith to Microservices":

Microservices are independently deployable services modeled around a business domain. They communicate with each other via networks, and as an architecture choice offer many options for solving the problems you may face.

Microservices give you a strategy to design a modular system and decompose it into bounded contexts. However, the problem I often see is that developers use microservices to enforce code boundaries. This is a mistake. We'll fix that in a moment.

Key Characteristics of Microservices

Let's explore some of the key characteristics that define microservices:

Independent Deployability

You can make changes to a microservice and deploy it to production without having to deploy anything else. This isn't just a theoretical ability - it's a discipline you practice for most of your releases.

The value here is significant: smaller deployments carry less risk , enable faster release cycles , and allow teams to test their changes in isolation.

When a critical bug appears in one service, you can fix and deploy just that service rather than orchestrating a full system release. This is especially valuable in large systems where coordinating releases can be a logistical nightmare.

Business Domain Focus

Microservices are organized around business capabilities rather than technical layers. Instead of having separate frontend, backend, and database teams (and the coordination that requires), you might have teams dedicated to "Event Management," "Customer Accounts," or "Attendance."

This alignment makes it easier to implement business functionality changes since all the related code - from UI to data storage - is grouped together. When a business requirement changes, you can often change just one service rather than coordinating changes across multiple layers.

Data Ownership

Microservices encapsulate data storage and retrieval, exposing data only via well-defined interfaces. Databases are hidden inside the service boundary rather than shared between services.

This stands in stark contrast to traditional approaches where multiple applications share a common database, often leading to tight coupling and risky schema changes.

When a service owns its data exclusively, it can:

Evolve its internal data model without breaking other services
Implement the most appropriate storage technology for its needs
Provide a stable API for other services to access its data.

It's not uncommon for multiple services to share the same database, but you're giving up some of the benefits of microservices by doing so. In practice, one database per service is the most common approach.

Network Communication

Services communicate with each other via networks, making microservices a form of distributed system. This network-based communication could use REST APIs, message queues, gRPC, GraphQL, or other protocols depending on the specific needs.

This explicit communication over networks allows services to be deployed independently and even run on different infrastructure. But it also means dealing with network latency, potential failures, and serialization concerns.

Teams building microservices need to carefully design their inter-service communication patternsto balance performance, reliability, and flexibility.

The Origins of Microservices

The term "microservices" has an interesting origin story. In 2011, a software consultant named James Lewis became interested in what he called "micro-apps" - small services optimized to be easily replaceable.

The distinguishing feature was how small in scope these services were. Some could be written or rewritten in just a few days. As discussions evolved, the term "microservices" was adopted since these weren't self-contained applications but rather services working together.

It's worth noting that while "micro" is in the name, the size of a microservice isn't its defining characteristic. Rather, it's about having services with well-defined boundaries that can be developed, deployed, and scaled independently.

Key Benefits of Microservices

What are the benefits of adopting a microservices architecture?

Why should you consider it for your organization?

Let's explore some of the key advantages:

Flexibility and Adaptability

Microservices give you options. They provide flexibility in how you can scale, evolve, and maintain your system over time.

When business requirements change, you can modify just the affected services rather than risking changes to the entire system.
New capabilities can be introduced as new services without disrupting existing functionality.
As your understanding of the domain grows, service boundaries can evolve to better reflect that understanding.

This ability to evolve incrementally is particularly valuable in rapidly changing business environments where time-to-market is critical.

Technology Diversity

With microservices, you can mix and match technology stacks. Each service can use the programming language, database, or framework best suited for its specific requirements. This practice is known as polyglot programming and polyglot persistence.

For example, a recommendation engine might use Python with specialized machine learning libraries. On the other hand, a transaction processing service might use .NET for its strong typing and performance characteristics.

A reporting service might use a columnar database optimized for analytics, while a user profile service could use a document database that better fits its data model.

This flexibility allows teams to choose the right tool for each job rather than compromising on a one-size-fits-all approach.

Parallel Development

Multiple teams can work on different services simultaneously without stepping on each other's toes. This parallelization can significantly accelerate development velocity in larger organizations.

Each team can maintain its own release schedule, make technology decisions, and optimize for their specific service's needs without coordinating with every other team. I've seen firsthand how this autonomy can reduce dependencies between teams, minimizing bottlenecks and wait times.

Organizations commonly structure their teams around services or groups of related services. You might know this concept as Conway's Law:

Organizations, who design systems, are constrained to produce designs which are copies of the communication structures of these organizations.

Targeted Scaling

You can scale just the services that need it, rather than scaling the entire system. This provides more efficient resource utilization and can reduce operational costs.

For example, if your product catalog needs to handle high traffic during a sale, you can scale just the catalog service without scaling your payment processing service.

This granular scaling becomes especially valuable as systems grow and different components have different performance characteristics. Some services might be CPU-intensive while others are memory-intensive, and with microservices, you can optimize the infrastructure for each service's specific needs.

This approach can lead to significant cost savings compared to scaling a monolith, where all components must scale together regardless of their individual requirements.

Organizational Alignment

Microservices can help align your technical architecture with your organizational structure. Teams can own specific services that correspond to their business domain expertise, promoting clearer ownership and accountability.

This alignment reduces handoffs and coordination costs between teams, as each team has clear boundaries of responsibility. It supports Conway's Law in a positive way. Instead of having your communication structure accidentally create your architecture, you deliberately design both your teams and your services around business capabilities.

This approach can lead to more stable team structures and software boundaries over time, as business domains tend to evolve more slowly than technical implementations.

Challenges to Consider With Microservices

While microservices offer numerous benefits, they're not without challenges:

Distributed System Complexity

Network communication introduces latency, reliability challenges, and makes debugging more difficult. Services must handle network failures gracefully, implement retries with backoff strategies, and deal with the reality that a request might succeed but the response might get lost.

Distributed tracing becomes essential to understand how requests flow through the system.

You'll need to develop strategies for handling partial system failures. Concepts like circuit breakers and bulkheads become part of your everyday vocabulary.

Operational Overhead

Managing many services requires robust deployment pipelines, monitoring, and debugging tools. You'll need to invest in automation for deployment, health checking, scaling, and perhaps service discovery. Each service needs monitoring, logging, and alerting.

This overhead can be substantial. Organizations successfully running microservices typically have a strong DevOps culture and tooling to manage this complexity.

Data Consistency

Maintaining consistency across service boundaries becomes more challenging without the safety of database transactions.

Implementing business processes that span multiple services often requires eventual consistency models and compensation mechanisms to handle failures. You'll need to design your services with idempotency in mind and may need to implement patterns like theSaga pattern to manage distributed transactions.

These approaches add complexity but can actually lead to more resilient systems when implemented correctly.

Service Coordination

Orchestrating workflows that span multiple services requires careful design. Simple processes in a monolith can become complex choreographies in a microservice architecture.

You'll need to decide whether to use orchestration (where a central service directs the process) or choreography (where services react to events without central coordination). These patterns have different trade-offs in terms of coupling, resilience, and observability.

Designing these cross-service workflows often reveals subdomain boundaries you might have missed in initial modeling.

Key Takeaway

From my experience, the most important thing to remember is that microservices ultimately buy you options. They provide flexibility but come with costs.

Are these costs worth the options you want to exercise?

For organizations with a large engineering team working on a complex system that needs to evolve quickly, microservices may be worth the overhead. For smaller teams or systems with more stable requirements, a well-designed monolith might be more appropriate. Forget about resume-driven development for a moment. It's about what solves your specific problems with acceptable trade-offs.

In my work, I've found that the most successful microservice adoptions start small, often by breaking off just one or two services from a monolith. Then, gradually expanding as the organization builds the necessary skills and infrastructure. This evolutionary approach reduces risk and allows teams to learn as they go.

I always like to reflect on these questions:

What parts of the current architecture would benefit most from independent deployability?
What challenges might the organization face when adopting microservices?
How well does the current system align with business domains?

If you want to dive deeper into building microservices - but starting from a monolith, check out Modular Monolith Architecture. There's an entire chapter dedicated to developing microservices, including advanced techniques such as API gateways, using message queues, and system integration testing.

Thanks for reading.

And stay awesome!

P.S. Whenever you're ready, there are 3 ways I can help you:

Pragmatic Clean Architecture: Join 4,000+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.
Modular Monolith Architecture: Join 1,800+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.
Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.

What is Vector Search? A Concise Guide

Milan Jovanović — Sat, 12 Apr 2025 00:00:00 +0000

Vector search is changing how we find information. Unlike old search methods that look for exact words, vector search finds content based on meaning. This makes search results more helpful and human-like.

When you search for "quick healthy breakfast ideas," vector search can find articles about "nutritious morning meals" even if they don't use your exact words. This happens because vector search understands what you mean, not just what you type.

In this week's newsletter, we'll break down how vector search works and why it's important.

Understanding Vector Embeddings

At the heart of vector search are vector embeddings. These are lists of numbers that represent data. But how do we get from words or images to numbers?

Here's how it works:

We feed text, images, or other data into a large language model (LLM)
The LLM turns each piece of data into a list of numbers (a vector)
These numbers capture the meaning of the data
Similar things get similar number patterns

Think of each number in the vector as describing one aspect of the data. With hundreds or thousands of these numbers, vectors can capture complex meanings and relationships.

For example, in vector form, the words "lion" and "bobcat" would have similar number patterns because they refer to similar animals. Meanwhile, "cat" would have a different pattern, though still somewhat similar since it's also a feline.

How Vector Search Works

When you search using vector search:

Your search question gets turned into a vector
The system compares this vector to all the vectors in its database
It finds the vectors that are most similar to your search vector
It returns the data connected to those similar vectors

To find similar vectors, the system measures how close they are to each other. Think of each vector as a point in space - the closer two points are, the more similar their meanings.

Vector Databases

To make vector search work well with lots of data, we need special storage systems called vector databases. These databases are built to store and quickly search through millions or billions of vectors.

Vector databases do more than just store vectors - they organize them in smart ways that make searching faster. They use special methods called "Approximate Nearest Neighbor" (ANN) algorithms that can find similar vectors without checking every single one in the database.

Source: What are Vector Databases? A Beginner's
Guide

These databases also store the original content along with its vector, so when you get search results, you see the actual text, images, or other data you were looking for. Popular vector databases include Weaviate, Pinecone, and Qdrant. But you can also turn PostgreSQL into a vector database using the pgvector extension.

The combination of vector embeddings and vector databases makes search extremely fast, even with millions of items to search through. This speed makes vector search practical for real-world applications where users expect instant results.

Key Differences from Traditional Search

Traditional keyword search works like this:

You type "red shoes"
The system finds pages with the words "red" and "shoes"
Results that mention these words more often rank higher

This approach has problems:

It misses related terms ("scarlet footwear")
It doesn't understand context
It can't handle questions well

An improvement to keyword search is full-text search, which looks at the whole text of documents. However, this still has some shortcomings that vector search solves.

Vector search fixes these issues by focusing on meaning rather than exact words. It can:

Find content with related concepts
Understand the context of your search
Return helpful results even for complex questions

This is why vector search powers many modern AI applications. It helps chatbots find relevant information and makes recommendation systems more accurate.

Summary

Vector search represents a major step forward in how computers understand and retrieve information. By converting data into number patterns that capture meaning, vector search can find connections that keyword search would miss.

This technology is behind many of the smart search features we now take for granted - from finding similar products in online stores to helping AI assistants answer our questions. As AI continues to advance, vector search will play an increasingly important role in helping us navigate the growing sea of digital information.

While not perfect, vector search bridges the gap between how computers store data and how humans think about meaning - making our digital tools more helpful and intuitive to use.

In a future newsletter, we'll dive into the practical side of vector search. You'll learn how to implement your own vector search system using popular tools and libraries, with step-by-step code examples and best practices.

That's all for today.

See you next week.

P.S. Whenever you're ready, there are 3 ways I can help you:

Pragmatic Clean Architecture: Join 3,700+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.
Modular Monolith Architecture: Join 1,600+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.
Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.

MediatR and MassTransit Going Commerical: What This Means For You

Milan Jovanović — Sat, 05 Apr 2025 00:00:00 +0000

Big changes are happening in the .NET ecosystem. Three powerhouse libraries - MediatR, AutoMapper, and MassTransit - are moving to commercial licenses. Not so long ago, Fluent Assertions also announced its plans to move to a commercial license.

As someone who's built countless systems with these tools over the past decade, I have thoughts. And some strong opinions.

The Libraries We Love (And Sometimes Hate)

If you're a .NET developer, you likely use at least one of these:

AutoMapper (794.7M downloads) transforms objects from one type to another. It removes mountains of tedious mapping code that nobody enjoys writing. One line replaces twenty. I personally despise AutoMapper and mapping libraries in general , but I can't deny their popularity.

MediatR (286.6M downloads) implements the mediator pattern. It decouples requests from the objects handling them, promoting separation of concerns. There's also the pipeline behavior feature, which allows you to add cross-cutting concerns. I'm a huge fan and use it regularly in my projects.

MassTransit (130.0M downloads) makes distributed messaging simple. It wraps message brokers like RabbitMQ and Azure Service Bus with an elegant API. Building event-driven systems becomes approachable. This is another tool I love and often recommend.

These libraries aren't just popular - they're transformative. They've shaped how we build .NET applications.

The Maintainer's Reality

Both announcements tell a similar story.

Source: AutoMapper and MediatR Going
Commercial

Jimmy Bogard (AutoMapper, MediatR) writes:

You can see exactly where my contributions cratered and flat-lined. And that's just commits—issues, PRs, discussions, all my time dried up.

His OSS work was previously sponsored by his former employer. When he went independent, that support vanished. His focus shifted to his consulting business.

Source: Announcing MassTransit
v9

Similarly, MassTransit has grown from "a single assembly that supported MSMQ" in 2007 to over thirty NuGet packages. Its success created demands that are impossible to meet through volunteer work alone:

Full-time development resources
Enterprise-grade support
Long-term sustainability

Both maintainers face the same dilemma: how do you support widely used libraries when nobody pays you to do it?

The Commercial Transition

Here's what's happening:

AutoMapper and MediatR : Jimmy hasn't shared specific timing or pricing yet. He states, "Short term, nothing will change."

MassTransit : Moving from v8 (open source) to v9 (commercial) with this timeline:

Q3 2025: v9 prerelease for early adopters
Q1 2026: v9 official release under commercial license
Through 2026: v8 security patches continue

MassTransit's pricing targets:

Small/medium businesses: $400/month or $4000/year
Large enterprises: $1200/month or $12000/year
Support for ISVs and consultants who build client applications

None of this is set in stone. The pricing aspect should be final by the time the commercial version is released.

Why I Respect This Decision

Both maintainers waited over a decade before making this move. They've contributed immense value to our community for free.

Their announcements show careful consideration. They're not abandoning users:

Existing versions remain open source
Security patches will continue
Commercial licenses support sustainable development

I honestly hope none of the above changes in the future. The work they do is valuable.

Writing these libraries from scratch would cost your team far more than their license fees.

Your Options Now (With My Take)

If your project uses these libraries, you have choices:

Purchase the commercial license

This supports continued development and gets you new features and official support.
Stay on the current open source version

MassTransit v8 and current MediatR/AutoMapper will remain available. Security patches will continue through 2026 for MassTransit. For MassTransit specifically, I'd consider staying on v8 for the long term if possible.
Switch to alternatives

For AutoMapper: consider Mapster or manual mapping (my recommendation).

For MediatR: explore FastEndpoints or build a simple mediator yourself.

For MassTransit: look at raw client libraries like RabbitMQ.Client and Azure.Messaging.ServiceBus, and another option to consider is Rebus.

Write equivalent functionality yourself MediatR isn't too complex to build on your own. I recommend giving it a try as an excellent coding exercise - it's probably the simplest way to move away from MediatR.

For AutoMapper, many teams have deep integrations with business logic in custom mappers. This makes extracting and replacing it difficult. Expect significant tech debt if you don't address this.

MassTransit, on the other hand, does so many things (and does them well) that migrating away would be challenging. Saga support or the request-response messaging features are hard to replicate. The only real alternative is diving into raw client libraries for your chosen message transport.

Each option involves tradeoffs. The right choice depends on your project needs and budget.

A Shift to Fundamentals

These changes have made me reflect on something important: we should never lose sight of fundamentals.

We've been pampered and spoiled by these awesome libraries. It's easy to lose sight of the actual problems they're solving and how they work under the hood. People know how to use MediatR, but they don't understand the mechanisms behind it.

The same goes for MassTransit. It abstracts away so many complexities of working with message brokers that it's possible to use it without knowing how RabbitMQ or Azure Service Bus actually works.

Remember this: using a library that abstracts something away doesn't excuse you from understanding the patterns and tools you're using. The fundamentals are still there and always have been. This might be the perfect opportunity to deepen your knowledge of what's happening beneath these abstractions.

A Reality Check

Open source isn't free. Someone pays - either with time or money.

I'm honestly tired of seeing developers complain about these changes. Who are they to demand software for free? The entitlement is astounding. These maintainers have provided immense value for over a decade without asking for anything in return.

We've enjoyed years of exceptional tooling without directly funding it. Now we face a reckoning.

As businesses reap massive productivity gains from these libraries, it's reasonable to ask: shouldn't some of that value flow back to the creators?

I hope these projects thrive under their new models. They've earned support after years of thankless work.

Both my Pragmatic Clean Architecture andModular Monolith Architecture courses currently use MediatR and MassTransit extensively. I plan to keep them on MediatR v12 and MassTransit v8 in the short term. However, I'll also be updating them to show migration paths away from these libraries.

What's your take? Will you stick with the open versions, pay for licenses, or explore alternatives?

Thanks for reading.

And stay awesome!

P.S. Whenever you're ready, there are 3 ways I can help you:

Pragmatic Clean Architecture: Join 3,700+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.
Modular Monolith Architecture: Join 1,600+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.
Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.

How .NET Aspire Simplifies Service Discovery

Milan Jovanović — Sat, 29 Mar 2025 00:00:00 +0000

Unless you've been living under a rock, you know that .NET Aspire is changing (for the better) how we build distributed applications in .NET. A simple way to think about Aspire: it makes all the difficult things in software development easy.

.NET Aspire is a cloud-native application stack that simplifies the development and deployment of distributed applications. One of the key challenges when building multi-service applications is building reliable communication between services.

In this week's newsletter, I want to focus on one aspect of .NET Aspire - service discovery. Service discovery lets our services figure out how to locate other services they want to integrate with. .NET Aspire tackles this challenge with a simple, configuration-based approach that reduces complexity and boilerplate code.

Understanding Service Discovery

Service discoveryis the process by which services in a distributed application locate and communicate with each other. As applications scale and evolve, keeping track of service endpoints becomes increasingly challenging. Services might run on different ports during development or be deployed to different environments in production, making hard-coded service URLs impractical.

Traditional approaches to service discovery often introduce complexity:

Manual configuration of service endpoints that must be updated as environments change
Complex intermediary systems that require additional maintenance
Custom code to handle service resolution and connection management

While many service discovery implementations rely on centralized registries, .NET Aspire takes a different approach by leveraging application configuration to connect services. This design choice simplifies the development experience while maintaining flexibility for various deployment scenarios. Aspire automatically takes care of wiring up the correct service URLs and injecting them into your application settings.

Practical Example of Service Discovery

To understand how .NET Aspire handles service discovery, let's look at a practical example of an application with multiple services:

var builder = DistributedApplication.CreateBuilder(args);

// Add services to the app
var apiService = builder.AddProject<Projects.WeatherApi>("weather-api");
var webFrontend = builder.AddProject<Projects.WebFrontend>("web-frontend")
    .WithReference(apiService);

builder.Build().Run();

In this App Host definition, we're creating two services: a weather API and a web frontend. The .WithReference() method establishes a connection between these services, which enables service discovery. This simple declaration tells .NET Aspire that the web frontend depends on the weather API and needs to communicate with it. Note that the web-frontend has to be a server-side application (like Blazor Server) for Aspire to be able to inject the service URL.

With this configuration in place, the web frontend can now reach the API using the service name weather-apiwithout additional service discovery code:

// Configures the default Aspire services, including service discovery
builder.AddServiceDefaults();

// In Program.cs of the web-frontend project
builder.Services.AddHttpClient("weather-api", (_, client) => {
    // The service name "weather-api" automatically resolves to the correct address
    client.BaseAddress = new Uri("http://weather-api");
});

This works because .NET Aspire manages the mapping between service names and their actual endpoints. When the application runs, service discovery ensures that requests to http://weather-api are routed to the appropriate destination.

Service Discovery Under the Hood

The previous example contains a bit of "magic" that might not be immediately clear. The AddServiceDefaults() method configures the default services for the application, including service discovery.

If we were to configure everything manually, it would look something like this:

builder.Services.AddServiceDiscovery();

builder.Services.AddHttpClient("weather-api", (_, client) => {
    client.BaseAddress = new Uri("http://weather-api");
})
.AddServiceDiscovery();

The first AddServiceDiscovery() method registers the necessary services to enable service discovery in the application. The second AddServiceDiscovery() method on the HTTP client configures it to use service discovery for resolving the base address. This means that when the HTTP client makes requests to http://weather-api, it will automatically resolve the correct endpoint based on the service discovery configuration.

We can also configure service discovery globally for all HTTP clients in the application:

builder.Services.ConfigureHttpClientDefaults(static http =>
{
    // Turn on service discovery by default
    http.AddServiceDiscovery();
});

This configuration ensures that all HTTP clients in the application will use service discovery by default, eliminating the need to configure it for each client individually.

What Aspire does at runtime for all of this to work is inject a set of configuration values. The configuration value names are derived from the service names we defined in the App Host, plus the respective scheme (http or https). Here's an example of what the weather-api configuration might look like:

{
  "Services": {
    "weather-api": {
      "http": [
        "localhost:8080"
      ]
    }
  }
}

We can also configure service discovery to work with HTTPS by adding the https scheme to the service name:

// Specify the https scheme explicitly in the service name
builder.Services.AddHttpClient("weather-api", (_, client) => {
    client.BaseAddress = new Uri("https://weather-api");
});

// Alternatively, we can use the https+http scheme and let Aspire handle the conversion
builder.Services.AddHttpClient("weather-api-2", (_, client) => {
    client.BaseAddress = new Uri("https+http://weather-api");
});

A significant advantage of Aspire's service discovery is its consistent behavior across environments:

During development, services might run on localhost with different ports
In testing environments, services could be containerized
In production, services might be deployed to Kubernetes or other platforms

Your code remains unchanged across these scenarios because the service name abstraction shields you from the underlying networking details.

Note that you don't have to use .NET Aspire to benefit from service discovery. It's available as a standalone library (Microsoft.Extensions.ServiceDiscovery) and you can use it in any .NET application.

Service Discovery with YARP as a Proxy

A powerful application of .NET Aspire's service discovery capabilities is in API gateway scenarios usingYARP (Yet Another Reverse Proxy). Let's explore how to implement this pattern:

// In the App Host
var apiService = builder.AddProject<Projects.WeatherApi>("weather-api");
var userService = builder.AddProject<Projects.UserApi>("user-api");
var proxyService = builder.AddProject<Projects.ApiGateway>("api-gateway")
    .WithReference(apiService)
    .WithReference(userService);

We'll need to add the YARP NuGet package to the API gateway project:

Install-Package Yarp.ReverseProxy # Adds the YARP package
Install-Package Microsoft.Extensions.ServiceDiscovery.Yarp # Adds the YARP service discovery package

In the gateway project, we can configure YARP to use service discovery:

// In Program.cs of the api-gateway project
var builder = WebApplication.CreateBuilder(args);

// Cofigures the service discovery services
builder.Services.AddServiceDiscovery();

// Add YARP services
builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"))
    // Configures a destination resolver that can use service discovery
    .AddServiceDiscoveryDestinationResolver();

var app = builder.Build();

// Configure the HTTP request pipeline
app.MapReverseProxy();

app.Run();

The YARP configuration in appsettings.json leverages the service names for endpoint resolution:

{
  "ReverseProxy": {
    "Routes": {
      "weather-route": {
        "ClusterId": "weather-cluster",
        "Match": {
          "Path": "/weather/{**catch-all}"
        },
        "Transforms": [
          { "PathRemovePrefix": "/weather" }
        ]
      },
      "user-route": {
        "ClusterId": "user-cluster",
        "Match": {
          "Path": "/users/{**catch-all}"
        },
        "Transforms": [
          { "PathRemovePrefix": "/users" }
        ]
      }
    },
    "Clusters": {
      "weather-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "http://weather-api"
          }
        }
      },
      "user-cluster": {
        "Destinations": {
          "destination1": {
            "Address": "http://user-api"
          }
        }
      }
    }
  }
}

This configuration creates an API gateway that:

Routes requests with path /weather/* to the weather API service
Routes requests with path /users/* to the user API service
Uses service names (weather-api and user-api) that service discovery resolves at runtime

The beauty of this approach is that the gateway doesn't need to know the actual endpoints of the backend services. It simply uses the service names, and .NET Aspire handles providing the configuration at runtime. This makes the gateway configuration more portable and easier to maintain as the application evolves.

Conclusion

.NET Aspire transforms service discovery from a complex infrastructure challenge into a straightforward configuration concern. By using a configuration-based approach rather than a centralized registry, it simplifies the development experience while maintaining the flexibility needed for various deployment scenarios.

The key advantages of Aspire's service discovery include:

Declarative service relationships in the App Host
Simple service name resolution that works across environments
Seamless integration with the .NET ecosystem and dependency injection
Powerful applications in patterns like API gateways with YARP

As the .NET Aspire stack continues to evolve, its approach to service discovery represents one of the ways it's making cloud-native development more accessible to .NET developers. By reducing the complexity of service-to-service communication, Aspire enables teams to focus on building features rather than wrestling with infrastructure concerns.

If you want to explore more robust service discovery solutions for large-scale distributed systems, check out my previous article on implementing service discovery with Consul. It provides a complementary approach for scenarios that might require a more traditional service registry.

For those who found the YARP integration particularly interesting, my Modular Monolith Architecture course dives deeper into building scalable applications with YARP as an API gateway. You'll learn how to leverage these patterns to create maintainable, evolvable systems regardless of whether you're using microservices or a monolith.

That's all for today.

See you next Saturday.

P.S. Whenever you're ready, there are 3 ways I can help you:

Pragmatic Clean Architecture: Join 3,700+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.
Modular Monolith Architecture: Join 1,600+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.
Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.

Options Pattern Validation in ASP.NET Core With FluentValidation

Milan Jovanović — Sat, 22 Mar 2025 00:00:00 +0000

If you've worked with the Options Pattern in ASP.NET Core, you're likely familiar with the built-in validation using Data Annotations. While functional, Data Annotations can be limiting for complex validation scenarios.

The Options Pattern lets you use classes to obtain strongly typed configuration objects at runtime.

The problem? You can't be certain that the configuration is valid until you try to use it.

So why not validate it at application startup?

In this article, we'll explore how to integrate the more powerful FluentValidationlibrary with ASP.NET Core's Options Pattern, to build a robust validation solution that executes at application startup.

Why FluentValidation Over Data Annotations?

Data Annotations work well for simple validations, but FluentValidation offers several advantages:

More expressive and flexible validation rules
Better support for complex conditional validations
Cleaner separation of concerns (validation logic separate from model)
Easier testing of validation rules
Better support for custom validation logic
Allows for injecting dependencies into validators

Understanding the Options Pattern Lifecycle

Before diving deep into validation, it's important to understand the lifecycle of options in ASP.NET Core:

Options are registered with the DI container
Configuration values are bound to options classes
Validation occurs (if configured)
Options are resolved when requested via IOptions<T>, IOptionsSnapshot<T>, or IOptionsMonitor<T>

The ValidateOnStart() method forces validation to occur during application startup rather than when options are first resolved.

Common Configuration Failures Without Validation

Without validation, configuration issues can manifest in several ways:

Silent failures : An incorrectly configured option may result in default values being used without warning
Runtime exceptions : Configuration issues may only surface when the application tries to use invalid values
Cascading failures : One misconfigured component can cause failures in dependent systems

By validating at startup, you create a fast feedback loop that prevents these issues.

Setting Up the Foundation

First, let's add the FluentValidation package to our project:

Install-Package FluentValidation # base package
Install-Package FluentValidation.DependencyInjectionExtensions # for DI integration

For our example, we'll use a GitHubSettings class that requires validation:

public class GitHubSettings
{
    public const string ConfigurationSection = "GitHubSettings";

    public string BaseUrl { get;init; }
    public string AccessToken { get; init; }
    public string RepositoryName { get; init; }
}

Creating a FluentValidation Validator

Next, we'll create a validator for our settings class:

public class GitHubSettingsValidator : AbstractValidator<GitHubSettings>
{
    public GitHubSettingsValidator()
    {
        RuleFor(x => x.BaseUrl).NotEmpty();

        RuleFor(x => x.BaseUrl)
            .Must(baseUrl => Uri.TryCreate(baseUrl, UriKind.Absolute, out _))
            .When(x => !string.IsNullOrWhiteSpace(x.BaseUrl))
            .WithMessage($"{nameof(GitHubSettings.BaseUrl)} must be a valid URL");

        RuleFor(x => x.AccessToken)
            .NotEmpty();

        RuleFor(x => x.RepositoryName)
            .NotEmpty();
    }
}

Building the FluentValidation Integration

To integrate FluentValidation with the Options Pattern, we need to create a custom IValidateOptions<T> implementation:

using FluentValidation;
using Microsoft.Extensions.Options;

public class FluentValidateOptions<TOptions>
    : IValidateOptions<TOptions>
    where TOptions : class
{
    private readonly IServiceProvider _serviceProvider;
    private readonly string? _name;

    public FluentValidateOptions(IServiceProvider serviceProvider, string? name)
    {
        _serviceProvider = serviceProvider;
        _name = name;
    }

    public ValidateOptionsResult Validate(string? name, TOptions options)
    {
        if (_name is not null && _name != name)
        {
            return ValidateOptionsResult.Skip;
        }

        ArgumentNullException.ThrowIfNull(options);

        using var scope = _serviceProvider.CreateScope();

        var validator = scope.ServiceProvider.GetRequiredService<IValidator<TOptions>>();

        var result = validator.Validate(options);
        if (result.IsValid)
        {
            return ValidateOptionsResult.Success;
        }

        var type = options.GetType().Name;
        var errors = new List<string>();

        foreach (var failure in result.Errors)
        {
            errors.Add($"Validation failed for {type}.{failure.PropertyName} " +
                       $"with the error: {failure.ErrorMessage}");
        }

        return ValidateOptionsResult.Fail(errors);
    }
}

A few important notes about this implementation:

We create a scoped service provider to properly resolve the validator (since validators are typically registered as scoped services)
We handle named options through the _name property
We build informative error messages that include the property name and error message

How the FluentValidation Integration Works

When adding our custom FluentValidation integration, it's helpful to understand how it connects to ASP.NET Core's options system:

The IValidateOptions<T> interface is the hook that ASP.NET Core provides for options validation
Our FluentValidateOptions<T> class implements this interface to bridge to FluentValidation
When ValidateOnStart() is called, ASP.NET Core resolves all IValidateOptions<T> implementations and runs them
If validation fails, an OptionsValidationException is thrown, preventing the application from starting

Creating Extension Methods for Easy Integration

Now, let's create a few extension methods to make our validation easier to use:

public static class OptionsBuilderExtensions
{
    public static OptionsBuilder<TOptions> ValidateFluentValidation<TOptions>(
        this OptionsBuilder<TOptions> builder)
        where TOptions : class
    {
        builder.Services.AddSingleton<IValidateOptions<TOptions>>(
            serviceProvider => new FluentValidateOptions<TOptions>(
                serviceProvider,
                builder.Name));

        return builder;
    }
}

This extension method allows us to call .ValidateFluentValidation() when configuring options, similar to the built-in .ValidateDataAnnotations() method.

For even more convenience, we can create another extension method to simplify the entire configuration process:

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddOptionsWithFluentValidation<TOptions>(
        this IServiceCollection services,
        string configurationSection)
        where TOptions : class
    {
        services.AddOptions<TOptions>()
            .BindConfiguration(configurationSection)
            .ValidateFluentValidation() // Configure FluentValidation validation
            .ValidateOnStart(); // Validate options on application start

        return services;
    }
}

Registering and Using the Validation

There are a few ways to use our FluentValidation integration:

Option 1: Standard Registration with Manual Validator Registration

// Register the validator
builder.Services.AddScoped<IValidator<GitHubSettings>, GitHubSettingsValidator>();

// Configure options with validation
builder.Services.AddOptions<GitHubSettings>()
    .BindConfiguration(GitHubSettings.ConfigurationSection)
    .ValidateFluentValidation() // Configure FluentValidation validation
    .ValidateOnStart();

Option 2: Using the Convenience Extension Method

// Register the validator
builder.Services.AddScoped<IValidator<GitHubSettings>, GitHubSettingsValidator>();

// Use the convenience extension
builder.Services.AddOptionsWithFluentValidation<GitHubSettings>(GitHubSettings.ConfigurationSection);

Option 3: Automatic Validator Registration

If you have many validators and want to register them all at once, you can use FluentValidation's assembly scanning:

// Register all validators from assembly
builder.Services.AddValidatorsFromAssembly(typeof(Program).Assembly);

// Use the convenience extension
builder.Services.AddOptionsWithFluentValidation<GitHubSettings>(GitHubSettings.ConfigurationSection);

What Happens at Runtime?

With .ValidateOnStart(), the application will throw an exception during startup if any validation rules fail. For example, if your appsettings.json is missing the required AccessToken, you'll see something like:

Microsoft.Extensions.Options.OptionsValidationException:
    Validation failed for GitHubSettings.AccessToken with the error: 'Access Token' must not be empty.

This prevents your application from even starting with invalid configuration, ensuring issues are caught as early as possible.

Working with Different Configuration Sources

ASP.NET Core's configuration system supports multiple sources. When using the Options Pattern with FluentValidation, remember that validation works regardless of the source:

Environment variables
Azure Key Vault
User secrets
JSON files
In-memory configuration

This is particularly useful for containerized applications where configuration comes from environment variables or mounted secrets.

Testing Your Validators

One benefit of using FluentValidation is that validators are easy to test:

// Uses helper methods from FluentValidation.TestHelper
[Fact]
public void GitHubSettings_WithMissingAccessToken_ShouldHaveValidationError()
{
    // Arrange
    var validator = new GitHubSettingsValidator();
    var settings = new GitHubSettings { RepositoryName = "test-repo" };

    // Act
    TestValidationResult<GitHubSettings>? result = await validator.TestValidate(settings);

    // Assert
    result.ShouldNotHaveAnyValidationErrors();
}

Summary

By combining FluentValidation with the Options Pattern and ValidateOnStart(), we create a powerful validation system that ensures our application has correct configuration at startup.

This approach:

Provides more expressive validation rules than Data Annotations
Separates validation logic from configuration models
Catches configuration errors at application startup
Supports complex validation scenarios
Is easily testable

This pattern is particularly valuable in microservice architectures or containerized applications where configuration errors should be detected immediately rather than at runtime.

Remember to register your validators appropriately and use .ValidateOnStart() to ensure validation happens during application startup.

That's all for today.

See you next Saturday.

P.S. Whenever you're ready, there are 3 ways I can help you:

Pragmatic Clean Architecture: Join 3,700+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.
Modular Monolith Architecture: Join 1,600+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.
Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.

Streamlining .NET 9 Deployment With GitHub Actions and Azure

Milan Jovanović — Sat, 15 Mar 2025 00:00:00 +0000

I remember the days of deploying .NET applications by hand: publishing locally, copying files to servers, running scripts, and crossing my fingers that nothing would break. It was stressful, time-consuming, and honestly, a bit scary.

But those days are over.

After implementing CI/CD pipelines for dozens of projects, I've seen firsthand how automation transforms the deployment process from a dreaded chore into a reliable, even boring, part of development.

And boring deployments are good deployments.

In this article, I'll walk you through setting up a robust CI/CD pipeline for .NET 9 applications usingGitHub Actions and Azure App Service. I'll cover:

What CI/CD is and why it matters for .NET developers
A complete workflow that builds, tests, and deploys your application
How to extend your pipeline with database migrations, code coverage, and more
Practical tips I've learned from real-world deployments

Whether you're tired of manual deployments or looking to improve your existing automation, this guide will help you build a robust CI/CD pipeline that you can easily extend to fit your needs.

What is CI/CD and Why Should You Care?

CI/CD stands for Continuous Integration and Continuous Delivery/Deployment.

In simple terms:

Continuous Integration (CI) means frequently merging code changes and running automated tests to catch issues early
Continuous Delivery (CD) means getting those changes to production-ready environments quickly and safely
Continuous Deployment (CD) is an extension of Continuous Delivery where every change that passes automated tests is deployed to production automatically

The main benefits I've seen:

Faster feedback : Find bugs within minutes instead of days
More stable releases : Small, incremental changes are easier to fix
Time savings : Let automation handle repetitive tasks while you focus on writing code
Consistent deployment : No more "it works on my machine" problems

My GitHub Actions Workflow for .NET 9

Here's the workflow I use to deploy a simple time service API to Azure App Service:

# Name of the workflow as it appears in GitHub Actions UI
name: Time Service CI

# Define when this workflow will run
on:
  workflow_dispatch: # Allow manual triggering from GitHub UI
  push:
    branches:
      - main # Run automatically when code is pushed to main branch

# Environment variables used throughout the workflow
env:
  AZURE_WEBAPP_NAME: time-service
  AZURE_WEBAPP_PACKAGE_PATH: './Time.Api/publish'
  DOTNET_VERSION: '9.x'
  SOLUTION_PATH: 'Time.Api.sln'
  API_PROJECT_PATH: 'Time.Api'
  PUBLISH_DIR: './publish'

# Define the separate jobs that make up this workflow
jobs:
  # First job: build and test the application
  build-and-test:
    name: Build and Test
    runs-on: ubuntu-latest # Use Ubuntu runner for this job

    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: ${{ env.DOTNET_VERSION }}

      - name: Restore
        run: dotnet restore ${{ env.SOLUTION_PATH }}

      - name: Build
      run: dotnet build ${{ env.SOLUTION_PATH }}
        --configuration Release
        --no-restore

    - name: Test
      run: dotnet test ${{ env.SOLUTION_PATH }}
        --configuration Release
        --no-restore
        --no-build
        --verbosity normal

    - name: Publish
      run: dotnet publish ${{ env.API_PROJECT_PATH }}
        --configuration Release
        --no-restore
        --no-build
        --property:PublishDir=${{ env.PUBLISH_DIR }}

    # Store the published output as an artifact for later jobs
    - name: Publish Artifacts
      uses: actions/upload-artifact@v4
      with:
        name: webapp # Name of the artifact
        path: ${{ env.AZURE_WEBAPP_PACKAGE_PATH }}

  # Second job: deploy the application to Azure
  deploy:
    name: Deploy to Azure
    runs-on: ubuntu-latest
    needs: [build-and-test] # This job depends on the build-and-test job

    steps:
      # Retrieve the artifacts from the build job
      - name: Download artifact from build job
        uses: actions/download-artifact@v4
        with:
          name: webapp
          path: ${{ env.AZURE_WEBAPP_PACKAGE_PATH }}

      # Deploy to Azure App Service using publish profile credentials
      - name: Deploy
        uses: azure/webapps-deploy@v2
        with:
          app-name: ${{ env.AZURE_WEBAPP_NAME }}
          # Authentication credentials stored as a secret
          publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
          package: '${{ env.AZURE_WEBAPP_PACKAGE_PATH }}'

This workflow does two main things: it builds and tests the code and then deploys it to Azure.

The first job checks out our repository, sets up .NET 9, and runs through a standard build process: restore packages, build the solution, run tests, and publish the application. The detailed comments in the YAML explain each step. Once everything passes, it packages the application as an artifact for the next job.

The second job takes that artifact and deploys it to Azure App Service using a publish profile. I store the publish profile as a GitHub secret for security. The needs: [build-and-test] line ensures deployment only happens if all tests pass, which protects our production environment from broken code.

Here's an example of what a workflow run looks like from the GitHub UI.

Extending Your CI/CD Pipeline

While the basic workflow gets your application deployed, most real-world projects need more sophisticated pipelines. As your project grows, so should your CI/CD process. Extensions to your pipeline could help catch issues earlier, ensure quality standards, and provide better visibility into your development process.

Here are some valuable additions to consider:

1. Running Database Migrations

Database schema changes can be tricky to coordinate with code deployments. There are several approaches to handling this:

Using EF Core Migration Bundles :

- name: Create migration bundle
  run: dotnet ef migrations bundle --project ${{ env.DATA_PROJECT }} --output ${{ env.MIGRATIONS_BUNDLE }}

- name: Apply migrations
  run: ${{ env.MIGRATIONS_BUNDLE }}

Migration bundles (introduced in EF Core 6.0) package your migrations into a standalone executable, making them easier to run in deployment pipelines.

Adding Manual Review for Migrations :

deploy-database:
  name: Deploy Database Changes
  environment: production
  runs-on: ubuntu-latest
  needs: [build-and-test]

This approach adds an environment with protection rules, requiring a DBA to review and approve migration scripts before they run. This is safer for production databases with valuable data.

Pros :

No manual migration steps
Schema and code changes deploy together
Database changes are versioned with code

Cons :

Failed migrations can be hard to roll back
Might need extra handling for production data
Requires secure database credentials in CI

To minimize risks, I test migrations in a staging environment first and always back up production databases before deployment.

2. Code Coverage Reports

I like knowing how much of my code is covered by tests. Here's an example of how to generate and publish code coverage reports to Codecov:

- name: Generate coverage report
  run: dotnet test ${{ env.SOLUTION_PATH }} /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura

- name: Publish coverage report
  uses: codecov/codecov-action@v5
  with:
    files: ./**/coverage.cobertura.xml
    fail_ci_if_error: true
    token: ${{ secrets.CODECOV_TOKEN }}

Adding minimum coverage requirements prevents drops in test coverage and encourages the team to maintain quality standards. You can also configure it to fail builds when coverage falls below a threshold.

3. Multi-Environment Deployment

For larger projects, deploying to multiple environments with approval gates provides better control:

deploy-staging:
  name: Deploy to Staging
  environment: staging
  runs-on: ubuntu-latest
  needs: [build-and-test]
  steps:
    # Deployment steps...

deploy-production:
  name: Deploy to Production
  environment: production
  runs-on: ubuntu-latest
  needs: [deploy-staging]
  steps:
    # Deployment steps...

Adding protection rules to your production environment creates checkpoints where team members can verify changes before they reach users.

Here's an example of some GitHub Environment protection rules:

Required reviewers : Specify team members who must approve deployments
Wait timers : Add a delay before deployments to give time for review
Deployment branches : Restrict which branches can deploy to production

These guardrails are especially important for critical environments where downtime can be costly.

Final Thoughts

A good CI/CD pipeline evolves with your project. Start simple, focus on automating the most painful manual tasks first, then gradually add more features as needed.

The initial setup takes time, but the long-term benefits are huge. My team now deploys multiple times per day instead of once every few weeks, with fewer bugs reaching production.

If you want to learn more about building robust APIs that complement your CI/CD process, check out my Pragmatic REST APIs course. It covers designing, implementing, and deploying production-ready APIs with best practices that work perfectly with the deployment pipeline we've discussed here.

What's your CI/CD setup like? I'd love to hear how you've customized your workflows for .NET applications.

That's all for today.

See you next week.

P.S. Whenever you're ready, there are 3 ways I can help you:

Pragmatic Clean Architecture: Join 3,700+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.
Modular Monolith Architecture: Join 1,600+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.
Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.

Better Request Tracing with User Context in ASP.NET Core

Milan Jovanović — Sat, 08 Mar 2025 00:00:00 +0000

When building web applications, knowing what's happening behind the scenes is crucial. In ASP.NET Core, we can make our lives easier by adding user context to our request tracing. This helps us track issues, understand user behavior, and improve our applications.

Let me show you how to enhance your request tracing by adding user context in ASP.NET Core applications.

Why Add User Context to Request Tracing?

When something goes wrong in your application, having the user's ID in your logs makes it much easier to figure out what happened. Instead of searching through thousands of log entries, you can filter by user ID and see only the relevant logs.

Adding user context also helps with:

Tracking user journeys through your application
Identifying patterns in user behavior
Troubleshooting issues for specific users
Monitoring performance for different user segments

Implementing User Context Enrichment

The core of our solution is a middleware component that extracts the user ID from the current user's claims and adds it to the current activity and logging scope.

A logging scope in ASP.NET Core lets you attach additional data to all log messages created within that scope.Structured logging frameworks like Serilogand the built-in logger support this feature. For example, if you add a user ID to a logging scope, every log message within that scope will include that user ID, even if the log message itself doesn't mention the user. This makes it easy to correlate logs for a specific user across different parts of your application.

The Activity class is part of the .NET diagnostics infrastructure. It represents a unit of work or operation and is designed for distributed tracing across service boundaries. When you add a tag to Activity.Current, that information becomes part of the trace and can be used to filter and analyze requests in your monitoring systems.

Here's the code:

using System.Diagnostics;
using System.Security.Claims;

namespace MyApp.Middleware;

public sealed class UserContextEnrichmentMiddleware(
    RequestDelegate next,
    ILogger<UserContextEnrichmentMiddleware> logger)
{
    public async Task InvokeAsync(HttpContext context)
    {
        string? userId = context.User?.FindFirstValue(ClaimTypes.NameIdentifier);
        if (userId is not null)
        {
            Activity.Current?.SetTag("user.id", userId);

            var data = new Dictionary<string, object>
            {
                ["UserId"] = userId
            };

            using (logger.BeginScope(data))
            {
                await next(context);
            }
        }
        else
        {
            await next(context);
        }
    }
}

Let's break down what this middleware does:

It extracts the user ID from the authenticated user's claims using context.User?.FindFirstValue(ClaimTypes.NameIdentifier)
If a user ID is found, it adds the ID as a tag to the current activity with Activity.Current?.SetTag("user.id", userId)
It creates a logging scope using ILogger.BeginScope with the user ID, which means all log entries within this scope will include the user ID
It calls the next middleware in the pipeline
If no user ID is found (for anonymous requests), it simply calls the next middleware

Logging Scopes and OpenTelemetry

If you're using OpenTelemetry to export logs, you have to configure the provider to include the log scopes on the generated log records.

Here's how:

builder.Logging.AddOpenTelemetry(options =>
{
    options.IncludeScopes = true;
    options.IncludeFormattedMessage = true;
});

Adding the Middleware to Your Application

To use this middleware in your ASP.NET Core application, add it to your pipeline in the Program.cs file:

app.UseAuthentication();
app.UseAuthorization();

// Add the user context enrichment middleware after authentication
app.UseMiddleware<UserContextEnrichmentMiddleware>();

app.MapControllers();

app.Run();

Make sure to place it after the authentication and authorization middleware so that the user identity is available.

Handling PII Concerns

When adding user IDs to your logs and traces, you need to be careful about Personally Identifiable Information (PII). Here are some important points to consider:

User IDs should be opaque identifiers (like GUIDs) that don't reveal personal information
Avoid logging email addresses, names, or other personal data
Make sure your logging configuration doesn't send PII to systems where it shouldn't go

If you need to comply with data protection regulations, consider implementing log retention policies and the ability to purge user data from logs when needed.

Expanding Context Enrichment

User IDs are just the beginning. We can add more context to make our logs and traces even more useful:

Feature Flags

Feature flags help us roll out new features gradually or enable them for specific users. Adding feature flag information to our context gives us valuable insights:

// Inside the middleware
if (featureFlagService.IsEnabled("NewFeature", userId))
{
    Activity.Current?.SetTag("features.newfeature", "enabled");
    // Add to logging scope as well
}

Tenant Information for Multi-tenant Applications

If your application serves multiple tenants, adding tenant IDs is extremely helpful:

string? tenantId = context.User?.FindFirstValue("TenantId");
if (tenantId is not null)
{
    Activity.Current?.SetTag("tenant.id", tenantId);
    // Add to logging scope
}

Takeaway

Adding user context to your request tracing in ASP.NET Core is a simple but powerful technique. By implementing the middleware we've explored, you'll see several important benefits:

Faster troubleshooting - when users report issues, you can quickly find relevant logs
Better understanding of usage patterns - see which features are being used and by whom
Improved performance monitoring - identify slow requests for specific user segments
More effective A/B testing - track metrics for users with different feature flags

Understanding logging scopes and the Activity class helps you get the most out of this technique. Logging scopes ensure your log entries contain consistent contextual information, while activities enable distributed tracing across service boundaries. Remember to be careful with PII and make sure your logging practices comply with relevant regulations.

Thanks for reading.

And stay awesome!

P.S. Whenever you're ready, there are 3 ways I can help you:

Pragmatic Clean Architecture: Join 3,700+ students in this comprehensive course that will teach you the system I use to ship production-ready applications using Clean Architecture. Learn how to apply the best practices of modern software architecture.
Modular Monolith Architecture: Join 1,600+ engineers in this in-depth course that will transform the way you build modern systems. You will learn the best practices for applying the Modular Monolith architecture in a real-world scenario.
Patreon Community: Join a community of 1,050+ engineers and software architects. You will also unlock access to the source code I use in my YouTube videos, early access to future videos, and exclusive discounts for my courses.