
<Sponsorships>

[**Dev Productivity is Down. Here's Why.**](https://fnf.dev/3GGpxfX)
68% of developers save 10+ hours weekly with AI, but half still lose just as much to broken processes.
Atlassian's 2025 Developer Experience Report reveals rising time waste, disconnects with leadership, and the gap between feeling productive and being productive.
Think your tools are smarter than your org chart? You're not alone.
[**Download the full report**](https://fnf.dev/3GGpxfX).

[**ReSharper is coming to VS Code**](https://jb.gg/rs-vsc-mj-newsletter).
JetBrains is bringing the power of ReSharper and AI assistant to Visual Studio Code!
Here's your chance to influence their future - [**join the public preview**](https://jb.gg/rs-vsc-mj-newsletter) to get early access,
test powerful new tools, and share your feedback directly with the development team.

</Sponsorships>

Let's talk about something we all deal with but often put off until the last minute - error handling in our ASP.NET Core apps.

When something breaks in production, the last thing you want is a cryptic 500 error with zero context.
Proper error handling isn't just about logging exceptions.
It's about making sure your app fails gracefully and gives useful info to the caller (and you).

In this article, I'll walk through the main options for global error handling in ASP.NET Core.

We'll look at how I used to do it, what ASP.NET Core 9 offers now, and where each approach makes sense.

## Middleware-Based Error Handling

The classic way to catch unhandled exceptions is with custom [**middleware**](3-ways-to-create-middleware-in-asp-net-core).
This is where most of us start, and honestly, it still works great for most scenarios.

```csharp
internal sealed class GlobalExceptionHandlerMiddleware(
    RequestDelegate next,
    ILogger<GlobalExceptionHandlerMiddleware> logger)
{
    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await next(context);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Unhandled exception occurred");

            // Make sure to set the status code before writing to the response body
            context.Response.StatusCode = ex switch
            {
                ApplicationException => StatusCodes.Status400BadRequest,
                _ => StatusCodes.Status500InternalServerError
            };

            await context.Response.WriteAsJsonAsync(
                new ProblemDetails
                {
                    Type = ex.GetType().Name,
                    Title = "An error occured",
                    Detail = ex.Message
                });
        }
    }
}
```

Don't forget to add the middleware to the request pipeline:

```csharp
app.UseMiddleware<GlobalExceptionHandlerMiddleware>();
```

This approach is solid and works everywhere in your pipeline.
The beauty is its simplicity: wrap everything in a try-catch, log the error, and return a consistent response.

But once you start adding specific rules for different exception types (e.g. `ValidationException`, `NotFoundException`), this becomes a mess.
You end up with long `if` / `else` chains or more abstractions to handle each exception type.

Plus, you're manually crafting JSON responses, which means you're probably not following
[RFC 9457 (Problem Details)](https://www.rfc-editor.org/rfc/rfc9457) standards.

## Enter IProblemDetailsService

Microsoft recognized this pain point and gave us `IProblemDetailsService` to standardize error responses.
Instead of manually serializing our own error objects, we can use the built-in Problem Details format.

```csharp {3,23-33}
internal sealed class GlobalExceptionHandlerMiddleware(
    RequestDelegate next,
    IProblemDetailsService problemDetailsService,
    ILogger<GlobalExceptionHandlerMiddleware> logger)
{
    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await next(context);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Unhandled exception occurred");

            // Make sure to set the status code before writing to the response body
            context.Response.StatusCode = ex switch
            {
                ApplicationException => StatusCodes.Status400BadRequest,
                _ => StatusCodes.Status500InternalServerError
            };

            await problemDetailsService.TryWriteAsync(new ProblemDetailsContext
            {
                HttpContext = httpContext,
                Exception = exception,
                ProblemDetails = new ProblemDetails
                {
                    Type = exception.GetType().Name,
                    Title = "An error occured",
                    Detail = exception.Message
                }
            });
        }
    }
}
```

This is much cleaner.
We're now using a standard format that API consumers expect, and we're not manually fiddling with JSON serialization.
But we're still stuck with that growing switch statement problem.
[**You can learn more about using Problem Details in .NET here**](problem-details-for-aspnetcore-apis).

## The Modern Way: IExceptionHandler

ASP.NET Core 8 introduced `IExceptionHandler`, and it's a game-changer.
Instead of one massive middleware handling everything, we can create focused handlers for specific exception types.

Here's how it works:

```csharp
internal sealed class GlobalExceptionHandler(
    IProblemDetailsService problemDetailsService,
    ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        logger.LogError(exception, "Unhandled exception occurred");

        httpContext.Response.StatusCode = exception switch
        {
            ApplicationException => StatusCodes.Status400BadRequest,
            _ => StatusCodes.Status500InternalServerError
        };

        return await problemDetailsService.TryWriteAsync(new ProblemDetailsContext
        {
            HttpContext = httpContext,
            Exception = exception,
            ProblemDetails = new ProblemDetails
            {
                Type = exception.GetType().Name,
                Title = "An error occured",
                Detail = exception.Message
            }
        });
    }
}
```

The key here is the return value.
If your handler can deal with the exception, return `true`.
If not, return `false` and let the next handler try.

Don't forget to register it with DI and the request pipeline:

```csharp
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddProblemDetails();

// And in your pipeline
app.UseExceptionHandler();
```

This approach is so much cleaner.
Each handler has one job, and the code is easy to test and maintain.

## Chaining Exception Handlers

You can chain multiple [**exception handlers**](global-error-handling-in-aspnetcore-8) together, and they'll run in the order you register them.
ASP.NET Core will use the first one that returns `true` from `TryHandleAsync`.

Example: One for validation errors, one global fallback.

```csharp
builder.Services.AddExceptionHandler<ValidationExceptionHandler>();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
```

Let's say you're using [FluentValidation](https://fluentvalidation.net/) (and you should be).
Here's a complete setup:

```csharp
internal sealed class ValidationExceptionHandler(
    IProblemDetailsService problemDetailsService,
    ILogger<ValidationExceptionHandler> logger) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        if (exception is not ValidationException validationException)
        {
            return false;
        }

        logger.LogError(exception, "Unhandled exception occurred");

        httpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        var context = new ProblemDetailsContext
        {
            HttpContext = httpContext,
            Exception = exception,
            ProblemDetails = new ProblemDetails
            {
                Detail = "One or more validation errors occurred",
                Status = StatusCodes.Status400BadRequest
            }
        };

        var errors = validationException.Errors
            .GroupBy(e => e.PropertyName)
            .ToDictionary(
                g => g.Key.ToLowerInvariant(),
                g => g.Select(e => e.ErrorMessage).ToArray()
            );
        context.ProblemDetails.Extensions.Add("errors", errors);

        return await problemDetailsService.TryWriteAsync(context);
    }
}
```

And in your app, just throw like this:

```csharp
// In your controller or service - IValidator<CreateUserRequest>
public async Task<IActionResult> CreateUser(CreateUserRequest request)
{
    await _validator.ValidateAndThrowAsync(request);

    // Your business logic here
}
```

The execution order is important.
The framework will try each handler in the order you registered them.
So put your most specific handlers first, and your catch-all handler last.

## Summary

We've come a long way from the days of manually crafting error responses in middleware.
The evolution looks like this:

- [**Middleware**](3-ways-to-create-middleware-in-asp-net-core): Simple, works everywhere, but gets complex fast
- [**IProblemDetailsService**](problem-details-for-aspnetcore-apis): Standardizes response format, still manageable
- [**IExceptionHandler**](global-error-handling-in-aspnetcore-8): Modern, testable, and scales beautifully

For new projects, I'd go straight to `IExceptionHandler`.
It's cleaner, more maintainable, and gives you the flexibility to handle different exception types exactly how you want.

The key takeaway?
Don't let error handling be an afterthought.
Set it up early, make it consistent, and your users (and your future self) will thank you when things inevitably go wrong.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**AI Agents: The Future of Software Development AND Developers**](https://fnf.dev/44x8Tri)\
AI Agents are redefining software, automating workflows and enabling real-time decisions via APIs.
Join Postman's Rodric Rabbah for a free on-demand webinar that will get you up to speed on Agentic AI and explore how
Postman Flows and AI Agent Builder can empower you to build, test, and deploy agents with APIs—no code required.
[**Get up to speed on Agentic AI**](https://fnf.dev/44x8Tri).

[**ReSharper's Fastest Build Yet**](https://lp.jetbrains.com/resharper-oop/?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=resharper_oop_eap&utm_content=how-to-try-resharper-in-out-of-process-mode)
Help us test ReSharper's fastest build yet: the 2025.2 EAP moves its engine out of Visual Studio and cuts median typing lag 37 %.
Spin it up in an experimental VS instance and tell us if it's 🐞 or 👍 →
[**Start here**](https://lp.jetbrains.com/resharper-oop/?utm_source=newsletter_milan_jovanovic&utm_medium=cpc&utm_campaign=resharper_oop_eap&utm_content=how-to-try-resharper-in-out-of-process-mode).

</Sponsorships>

[**.NET Aspire**](dotnet-aspire-a-game-changer-for-cloud-native-development) is one of the most exciting additions to the .NET ecosystem in years.

It brings a fresh, modern approach to building cloud-native apps, with a focus on developer productivity,
great defaults, and tight integration across your entire stack.

One of the most asked-for features is the ability to publish your app to Docker Compose.
This is now available in the latest preview, and I'm excited to share how it works.

In this post, I'll walk you through how I used Aspire's **Docker publisher** to spin up a demo app that includes an API, a Postgres database, and a Redis cache.
Everything runs using Docker Compose, and Aspire generates the whole thing from C# code.

I'll show you how to set it up, explain what it's doing behind the scenes,
and give you a glimpse into how easy it is to take that setup and run it on a VPS or cloud server.

## The Demo App

The app is intentionally simple, just enough to demonstrate how Aspire wires things together.

- API project: a minimal .NET Web API
- Postgres: used for data storage
- Redis: used for caching

In a traditional setup, you'd manually connect these services, manage configuration files, handle environment variables,
and write a `docker-compose.yml` from scratch.

With Aspire, you declare everything in C# inside the AppHost project.
Here's a quick look at the setup:

```csharp {4}
var builder = DistributedApplication.CreateBuilder(args);

// Enables Docker publisher
builder.AddDockerComposeEnvironment("aspire-docker-demo");

var postgres = builder.AddPostgres("database")
    .WithDataVolume();

var database = postgres.AddDatabase("demo-db");

var redis = builder.AddRedis("cache");

var webApi = builder.AddProject<Projects.Web_Api>("web-api")
    .WithReference(database).WaitFor(postgres)
    .WithReference(redis).WaitFor(redis);

builder.Build().Run();
```

This gives you a development environment where Aspire runs Postgres and Redis in containers, and connects your API to them.

The `AddDockerComposeEnvironment` method enables the Docker publisher.
It's available in the `Aspire.Hosting.Docker` NuGet package, which is currently in preview.

```powershell
Install-Package Aspire.Hosting.Docker -Version 9.3.1-preview.1.25305.6
```

## Installing the Aspire CLI

To publish your app to Docker Compose, install the **Aspire CLI**:

```bash
dotnet tool install --global aspire.cli --prerelease
```

Then you can run the `publish` command:

```bash
aspire publish -o docker-compose-artifacts
```

This command will scan your solution for the Aspire project and generate a Docker Compose file and an `.env` file
based on the services you've defined.

<div className="centered">
  <Image
    src="blogs/mnw_149/aspire_publish.png"
    width={799}
    height={247}
    alt="Aspire publish command"
  />
</div>

## The Docker Compose File

Let's examine what Aspire created for us:

```yml
services:
  database:
    image: 'docker.io/library/postgres:17.4'
    environment:
      POSTGRES_HOST_AUTH_METHOD: 'scram-sha-256'
      POSTGRES_INITDB_ARGS: '--auth-host=scram-sha-256 --auth-local=scram-sha-256'
      POSTGRES_USER: 'postgres'
      POSTGRES_PASSWORD: '${DATABASE_PASSWORD}'
    ports:
      - '8000:5432'
    volumes:
      - type: 'volume'
        target: '/var/lib/postgresql/data'
        source: 'aspire.apphost-1f0ed76b33-database-data'
        read_only: false
    networks:
      - 'aspire'
  redis:
    image: 'docker.io/library/redis:7.4'
    command:
      - '-c'
      - 'redis-server --requirepass $$REDIS_PASSWORD'
    entrypoint:
      - '/bin/sh'
    environment:
      REDIS_PASSWORD: '${REDIS_PASSWORD}'
    ports:
      - '8001:6379'
    networks:
      - 'aspire'
  web-api:
    image: '${WEB_API_IMAGE}'
    environment:
      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES: 'true'
      OTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES: 'true'
      OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY: 'in_memory'
      ASPNETCORE_FORWARDEDHEADERS_ENABLED: 'true'
      HTTP_PORTS: '8002'
      ConnectionStrings__demo-db: 'Host=database;Port=5432;Username=postgres;Password=${DATABASE_PASSWORD};Database=demo-db'
      ConnectionStrings__redis: 'redis:6379,password=${REDIS_PASSWORD}'
    ports:
      - '8003:8002'
      - '8005:8004'
    depends_on:
      database:
        condition: 'service_started'
      redis:
        condition: 'service_started'
    networks:
      - 'aspire'
networks:
  aspire:
    driver: 'bridge'
volumes:
  aspire.apphost-1f0ed76b33-database-data:
    driver: 'local'
```

This `docker-compose` file is generated from the C# code we wrote earlier.
It defines the services, their images, environment variables, ports, and dependencies.

The `.env` file contains some of the configuration we need:

```txt
# Parameter database-password
DATABASE_PASSWORD=<YOUR_STRONG_PASSWORD>

# Container image name for web-api
# Change this to the imaage name in the container registry
WEB_API_IMAGE=web-api:latest

# Parameter redis-password
REDIS_PASSWORD=<YOUR_STRONG_PASSWORD>
```

It contains the passwords for the database and Redis, as well as the image name for the API.
You'll need to replace the placeholders with actual values.
For the API image, you can build and tag the image yourself, or use a pre-built one from a registry.

## Publishing and Running on a VPS

Aspire doesn't deploy the app for you, but it gives you everything you need.

Once the Compose file is ready, deployment to a VPS is straightforward:

1. Copy the artifacts to your server using (`scp` or `git`).
2. SSH into the VPS.
3. Run `docker compose up -d` inside the artifact directory.

Make sure Docker and Docker Compose are installed on the server.

You can expose ports with a reverse proxy like Nginx or Caddy, and secure it with HTTPS using Let's Encrypt.

I'll cover this in more detail in a future post.

## Wrapping Up

.NET Aspire with Docker Compose provides a smooth developer experience and a simple way to deploy full-stack apps.

You define everything in C#, test it locally, and publish it with one command.
No need to write Compose files or manage infrastructure manually.
This opens up new possibilities for deploying and managing cloud-native apps.
You're not locked into a specific cloud provider, and you can easily move between environments.

Can I just say how much I love this?
I'm really excited about the future of cloud-native development with .NET and Aspire.

If you liked this article and want to learn how I structure larger apps, check out [**Modular Monolith Architecture**](/modular-monolith-architecture).
It walks you through building clean, scalable .NET applications with strong internal boundaries and maintainability in mind.

Thanks for reading and stay awesome!

---



<Sponsorships>

[**BREAKING: PagerDuty Actually Fixed Incident Management**](https://fnf.dev/3FSidO0)\
Remember when PagerDuty was just for alerting?
Plot twist: They've quietly bundled and enhanced complete incident management into ALL plans -
including custom workflows, Slack-first everything, AI-powered summaries, and incident roles.
Your incident management deserves better than browser tabs and hope.
[**Check it out here**](https://fnf.dev/3FSidO0).

Nick Chapsas' Dometrain is celebrating 2 years of teaching .NET developers, and they are offering their
[**"From Zero to Hero: REST APIs in .NET"**](https://dometrain.com/course/from-zero-to-hero-rest-apis-in-asp-net-core/?ref=milan-jovanovic&promo=newsletter-20250628)
course for free.
Until the end of June, use the link below, and the course is yours to keep for 1 month.
[**Get it for free**](https://dometrain.com/course/from-zero-to-hero-rest-apis-in-asp-net-core/?ref=milan-jovanovic&promo=newsletter-20250628).

</Sponsorships>

Integration tests with Testcontainers are powerful, but they can quickly become a maintenance nightmare if you don't follow the right patterns.

I've seen teams struggle with flaky tests, slow test suites, and configuration headaches that could have been avoided with better practices from the start.

Today, I'll show you the patterns that make [Testcontainers](https://testcontainers.com/) tests reliable, fast, and easy to maintain.

## How Testcontainers Changes Integration Testing

Traditional [**integration tests**](testcontainers-integration-testing-using-docker-in-dotnet) often rely on shared test databases or in-memory alternatives that don't match production behavior.
You either deal with test pollution between runs or sacrifice realism for speed.

Testcontainers solves this by spinning up real [Docker](https://www.docker.com/) containers for your dependencies.
Your tests run against actual PostgreSQL, Redis, or any other service you use in production.
When tests complete, containers are destroyed, giving you a clean slate every time.

The magic happens through Docker's API.
Testcontainers manages the entire lifecycle: pulling images, starting containers, waiting for readiness, and cleanup.
Your test code just needs to know how to connect.

## Prerequisites

First, make sure you have the necessary packages:

```powershell
Install-Package Microsoft.AspNetCore.Mvc.Testing
Install-Package Testcontainers.PostgreSql
Install-Package Testcontainers.Redis
```

If you want to learn more about the basic setup, check out my article on
[**integrating testing with Testcontainers**](testcontainers-integration-testing-using-docker-in-dotnet).

## Creating Test Containers

Here's how to set up your containers with proper configuration:

```csharp
PostgreSqlContainer _postgresContainer = new PostgreSqlBuilder()
    .WithImage("postgres:17")
    .WithDatabase("devhabit")
    .WithUsername("postgres")
    .WithPassword("postgres")
    .Build();

RedisContainer _redisContainer = new RedisBuilder()
    .WithImage("redis:latest")
    .Build();
```

To start and stop containers cleanly across your test suite, implement `IAsyncLifetime` in your `WebApplicationFactory`:

```csharp
public sealed class IntegrationTestWebAppFactory : WebApplicationFactory<Program>, IAsyncLifetime
{
    public async Task InitializeAsync()
    {
        await _postgresContainer.StartAsync();
        await _redisContainer.StartAsync();
        // Start other dependencies here
    }

    public async Task DisposeAsync()
    {
        await _postgresContainer.StopAsync();
        await _redisContainer.StopAsync();
    }
}
```

This ensures containers are ready before tests run and cleaned up afterward.
This means no leftover Docker state or race conditions.

**A tip**: pin your image versions (like `postgres:17`) to avoid surprises from upstream changes

I learned this the hard way when a minor version update caused my tests to fail unexpectedly.

## Pass Configuration to Your App

The biggest mistake I see is hardcoding connection strings.
Testcontainers assigns dynamic ports.
Don't hardcode anything.

Instead, inject values via `WebApplicationFactory.ConfigureWebHost`:

```csharp
protected override void ConfigureWebHost(IWebHostBuilder builder)
{
    builder.UseSetting("ConnectionStrings:Database", _postgresContainer.GetConnectionString());
    builder.UseSetting("ConnectionStrings:Redis", _redisContainer.GetConnectionString());
}
```

The key is to use the `UseSetting` method to pass connection strings dynamically.
It also avoids any race conditions or conflicts with other tests that might run in parallel.

This ensures your tests always connect to the right ports, regardless of what Docker assigns.

There's no need to remove services from the service collection or manually configure them (contrary to what you might find online).
Just set the connection strings, and your application will use them automatically.

## Share Expensive Setup with xUnit Collection Fixtures

What's a test fixture?
A **fixture** is a shared context for your tests, allowing you to set up expensive resources like databases or message brokers once and reuse them across multiple tests.

This is where most teams get tripped up.
The choice between class and collection fixtures affects both test performance and isolation.

**Class Fixture** - One container per test class:

Use class fixtures when tests modify global state or when debugging test interactions becomes difficult.

```csharp {1}
public class AddItemToCartTests : IClassFixture<DevHabitWebAppFactory>
{
    private readonly DevHabitWebAppFactory _factory;

    public AddItemToCartTests(DevHabitWebAppFactory factory)
    {
        _factory = factory;
    }

    [Fact]
    public async Task Should_ReturnFailure_WhenNotEnoughQuantity() { ... }
}
```

**Collection Fixture** - One container shared across multiple test classes:

Use collection fixtures when your tests don't modify shared state or when you can reliably clean up between tests.

```csharp
[CollectionDefinition(nameof(IntegrationTestCollection))]
public sealed class IntegrationTestCollection : ICollectionFixture<DevHabitWebAppFactory>
{
}
```

Then apply it to your test classes:

```csharp {1}
[Collection(nameof(IntegrationTestCollection))]
public class AddItemToCartTests : IntegrationTestFixture
{
    public AddItemToCartTests(DevHabitWebAppFactory factory) : base(factory) { }

    [Fact]
    public async Task Should_ReturnFailure_WhenNotEnoughQuantity()
    {
        Guid customerId = await Sender.CreateCustomerAsync(Guid.NewGuid());
        var command = new AddItemToCartCommand(customerId, ticketTypeId, Quantity + 1);

        Result result = await Sender.Send(command);

        result.Error.Should().Be(TicketTypeErrors.NotEnoughQuantity(Quantity));
    }
}
```

When to use which:

- Class fixtures when you need full isolation between test classes (slower but safer)
- Collection fixtures when test classes don't interfere with each other (faster but requires discipline)

With collection fixtures, you have to take care of cleaning up any state that might persist between tests.
This could include resetting databases, clearing caches, or removing test data.
If you don't do this, you risk tests affecting each other, leading to flaky results.

## Utility Methods for Auth and Cleanup

Your fixture can expose helpers to simplify test writing:

```csharp
public async Task<HttpClient> CreateAuthenticatedClientAsync() { ... }

protected async Task CleanupDatabaseAsync() { ... }
```

These methods can handle authentication setup and database cleanup, so you don't have to repeat boilerplate code in every test.
This lets your test code focus on assertions, not setup.

## Writing Maintainable Integration Tests

With the infrastructure properly configured, your actual tests should focus on business logic:

```csharp
[Fact]
public async Task Should_ReturnFailure_WhenNotEnoughQuantity()
{
    //Arrange
    Guid customerId = await Sender.CreateCustomerAsync(Guid.NewGuid());
    var eventId = Guid.NewGuid();
    var ticketTypeId = Guid.NewGuid();

    await Sender.CreateEventWithTicketTypeAsync(eventId, ticketTypeId, Quantity);

    var command = new AddItemToCartCommand(customerId, ticketTypeId, Quantity + 1);

    //Act
    Result result = await Sender.Send(command);

    //Assert
    result.Error.Should().Be(TicketTypeErrors.NotEnoughQuantity(Quantity));
}
```

Notice how the tests focus on business rules rather than infrastructure concerns.
The container complexity is hidden behind well-designed base classes and helper methods.
You're not mocking Postgres or Redis, you're testing real behavior.

## Conclusion

Testcontainers transforms integration testing by giving you the confidence that comes from testing against real dependencies.
No more wondering if your in-memory database behavior matches production, or dealing with shared test environments that break when someone else runs their tests.

Start simple: pick one integration test that currently uses mocks or in-memory databases, and convert it to use Testcontainers.
You'll immediately notice the difference in confidence when that test passes.
Then gradually expand to cover your critical business flows.

If you want to learn how to structure your applications for testability from day one,
my [**Pragmatic Clean Architecture**](/pragmatic-clean-architecture) course covers integration testing with Testcontainers alongside domain modeling,
API design, and the architectural decisions that make applications maintainable over time.

That's all for today.

See you next week.

---



<Sponsorships>

Gen AI is everywhere these days, but it can be hard to figure out where to start.
[**SambaNova Cloud**](https://fnf.dev/3ZArOzD) lets you build with the best open source models from Llama, DeepSeek, OpenAI and more, all optimized for speed.
They have integrations to popular frameworks and tools (like Hugging Face, CrewAI, and Cline), APIs for building, and a playground to test things out.
[**Get started with SambaNova Cloud today**](https://fnf.dev/3ZArOzD).

[**ABP Studio 1.0**](https://abp.io/community/articles/announcing-abp-studio-1-0-general-availability-82yw62bt#gsc.tab=0?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_jun21)
is Here: Develop .NET Apps Visually and Fast.
The stable version of ABP Studio 1.0 is now officially available!
It's a full-featured visual development environment for ABP.IO—generate modules, configure entities, and scaffold UIs in minutes.
Skip the boilerplate. Focus on what matters.
[**Explore ABP Studio 1.0**](https://abp.io/community/articles/announcing-abp-studio-1-0-general-availability-82yw62bt#gsc.tab=0?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_jun21)

</Sponsorships>

Your .NET application is running in production, but you're flying blind.

When something breaks, you're stuck digging through logs, guessing at performance bottlenecks,
and trying to piece together what actually happened across your distributed system.

That ends today.

[Grafana](https://grafana.com/) is a complete observability platform that unifies metrics, logs, and traces in one place.

With Grafana, you get:

- **Unified dashboards** that combine metrics, logs, and traces
- **Advanced alerting** that actually works when things go wrong
- **Deep trace analysis** to understand request flows across services
- **Log correlation** that connects your traces to the exact log entries that matter

[Grafana Cloud](https://grafana.com/products/cloud/) makes this even easier.
No infrastructure to manage, automatic scaling, and built-in integrations with [OpenTelemetry](https://opentelemetry.io/).
There's a generous free tier that allows you to get started without any upfront costs.

When you combine Grafana with OpenTelemetry, you get vendor-neutral observability that actually delivers insights instead of just pretty charts.

## Setting Up OpenTelemetry in .NET

First, install the core OpenTelemetry packages:

```powershell
Install-Package OpenTelemetry.Extensions.Hosting
Install-Package OpenTelemetry.Exporter.OpenTelemetryProtocol
Install-Package OpenTelemetry.Instrumentation.AspNetCore
Install-Package OpenTelemetry.Instrumentation.Http
```

You can also add instrumentation for other libraries as needed:

```powershell
Install-Package OpenTelemetry.Instrumentation.EntityFrameworkCore
Install-Package OpenTelemetry.Instrumentation.StackExchangeRedis
Install-Package Npgsql.OpenTelemetry
```

Configure OpenTelemetry in your `Program.cs`:

```csharp
var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService(serviceName))
    .WithTracing(tracing =>
    {
        tracing
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation()
            .AddEntityFrameworkCoreInstrumentation()
            .AddRedisInstrumentation()
            .AddNpgsql();

        tracing.AddOtlpExporter();
    });

builder.Logging.AddOpenTelemetry(logging =>
{
    logging.IncludeScopes = true;
    logging.IncludeFormattedMessage = true;

    logging.AddOtlpExporter();
});

var app = builder.Build();

// Your app configuration...

app.Run();
```

This configuration:

- Sets up [**tracing with OpenTelemetry**](introduction-to-distributed-tracing-with-opentelemetry-in-dotnet)
- Sets up automatic instrumentation for ASP.NET Core and HTTP requests
- Adds Entity Framework Core and Redis instrumentation
- Configures PostgreSQL instrumentation if you're using Npgsql
- Configures OTLP export for traces and logs (we can also add metrics later)

## Configuring OTLP Export to Grafana Cloud

Get your Grafana Cloud credentials:

1. Log into [Grafana Cloud](https://grafana.com/auth/sign-up/create-user)

2. Go to **My Account** → **Stack Details**

<Image
  src="blogs/mnw_147/grafana_setup.png"
  width={1919}
  height={1079}
  alt="Grafana cloud stack details"
/>

3. Find your **OTLP endpoint** (looks like `https://otlp-gateway-prod-eu-west-2.grafana.net/otlp`)

<Image
  src="blogs/mnw_147/grafana_setup_endpoint.png"
  width={1919}
  height={1079}
  alt="Grafana cloud endpoint"
/>

4. Generate an **API token** with permissions

<Image
  src="blogs/mnw_147/grafana_setup_token.png"
  width={1919}
  height={1079}
  alt="Grafana cloud token"
/>

You should also see the environment variables you can use to configure OpenTelemetry:

<Image
  src="blogs/mnw_147/grafana_setup_env_vars.png"
  width={1919}
  height={1079}
  alt="Grafana cloud environment variables"
/>

Configure the OTLP exporter in your `appsettings.json`:

```json
{
  "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otlp-gateway-prod-eu-west-2.grafana.net/otlp",
  "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
  "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Basic <your-base64-encoded-token>"
}
```

You can also set these as environment variables in your hosting environment.

## Viewing and Analyzing Data in Grafana

Start your application and generate some traffic.
Now head to your Grafana Cloud instance.

**Traces**

If everything is set up correctly, you should see traces from your application in the **Traces** section.

Here's an example of a trace view in Grafana Cloud.
It's a `POST users/register` request that contains multiple spans:

<Image
  src="blogs/mnw_147/grafana_trace_1.png"
  width={1919}
  height={1079}
  alt="Grafana cloud trace example"
/>

Here's another example of a trace that includes messages sent to a message broker (like RabbitMQ or Kafka).

<Image
  src="blogs/mnw_147/grafana_trace_2.png"
  width={1919}
  height={1079}
  alt="Grafana cloud trace example"
/>

**Logs**

You can also view logs in Grafana Cloud.

Here's an example of a log view that shows multiple log entries for our application.

<Image
  src="blogs/mnw_147/grafana_logs_1.png"
  width={1919}
  height={1079}
  alt="Grafana cloud logs example"
/>

You can drill down into individual log entries, filter by severity, and search for specific terms.

<Image
  src="blogs/mnw_147/grafana_logs_2.png"
  width={1919}
  height={1079}
  alt="Grafana cloud logs example"
/>

OpenTelemetry automatically correlates your logs with traces.
In the trace detail view, click **Logs** to see all log entries that occurred during that request.

Your logs will include trace and span IDs.

## Conclusion

You now have full observability for your .NET application.

When something goes wrong in production, you won't be guessing anymore.
You'll see exactly which requests were slow, what errors occurred, and how they propagated through your system.

Grafana gives you the dashboards and alerting to catch problems before users do.
OpenTelemetry gives you the detailed traces to understand exactly what happened.

This setup scales from a single service to hundreds of microservices without changing your instrumentation code.

**Ready to take your observability further?**

This article showed you the basics, but modern applications need advanced patterns like distributed tracing across event-driven architectures,
custom instrumentation strategies, and observability-driven development practices.

I cover all of this in-depth in my [**Modular Monolith Architecture**](/modular-monolith-architecture) course,
where you'll learn how to implement OpenTelemetry across complex, event-driven systems that actually scale in production.

That's all for today.

See you next Saturday.

---



<Sponsorships>

Nick Chapsas' Dometrain is celebrating 2 years of teaching .NET developers, and they are offering their
[**"From Zero to Hero: REST APIs in .NET"**](https://dometrain.com/course/from-zero-to-hero-rest-apis-in-asp-net-core/?ref=milan-jovanovic&promo=newsletter-20250614)
course for free.
Until the end of June, use the link below, and the course is yours to keep for 1 month.
[**Get it for free**](https://dometrain.com/course/from-zero-to-hero-rest-apis-in-asp-net-core/?ref=milan-jovanovic&promo=newsletter-20250614).

Get [**free senior engineer level code reviews**](https://fnf.dev/4l1jNMr) right in your IDE (VS Code, Cursor, Windsurf) with [**CodeRabbit**](https://fnf.dev/4l1jNMr).
Instantly catches bugs and code smells, suggests refactorings, and delivers context aware feedback for every commit, all without configuration.
Works with all major languages; trusted on 10M+ PRs across 1M repos and 70K+ OSS projects.
[**Install the extension and start vibe checking your code today**](https://fnf.dev/4l1jNMr).

</Sponsorships>

.NET 10 just got a whole lot more lightweight.

You can now run a C# file directly with:

```bash
dotnet run app.cs
```

That's it.
No `.csproj`.
No `Program.cs`.
No solution files.
Just a single C# file.

This new feature, introduced in [.NET 10 Preview 4](https://devblogs.microsoft.com/dotnet/announcing-dotnet-run-app/),
is a big step toward making C# more script-friendly, especially for quick utilities, dev tooling, and CLI-based workflows.

## Why This Matters

For years, C# has been perceived as heavyweight for small scripts.
Compare that to Python, Bash, or even JavaScript, where you can just write a file and run it.

That barrier is now gone.

You can now:

- Write one-off scripts in `.cs` files
- Use top-level statements
- Reference NuGet packages inline
- Share minimal reproducible examples without scaffolding a project

And it runs on **any OS** with the .NET SDK installed.

## Minimal Example

Here's a simple script that prints today's date:

```csharp
Console.WriteLine($"Today is {DateTime.Now:dddd, MMM dd yyyy}");
```

Run it:

```bash
dotnet run app.cs
```

Output:

```
Today is Saturday, Jun 14 2025
```

That's it.
No boilerplate, no boring `Main()` method.
Just top-level programs and C# code.

## Referencing NuGet Packages

Let's say you want to make an HTTP request using `Flurl.Http`.

You can do this inline:

```csharp
#:package Flurl.Http@4.0.2

using Flurl.Http;

var response = await "https://api.github.com"
    .WithHeader("Accept", "application/vnd.github.v3+json")
    .WithHeader("User-Agent", "dotnet-script")
    .GetAsync();

Console.WriteLine($"Status code: {response.StatusCode}");

Console.WriteLine(await response.GetJsonAsync<object>());
```

To run it:

```bash
dotnet run fetch.cs
```

Behind the scenes, the compiler downloads and restores NuGet dependencies automatically.

## Real-World Use Case: Seeding SQL Data

Here's a script I recently used to seed some test data into my Postgres database.

```csharp
#:package Dapper@2.1.66
#:package Npgsql@9.0.3

using Dapper;
using Npgsql;

const string connectionString = "Host=localhost;Port=5432;Username=postgres;Password=postgres";

using var connection = new NpgsqlConnection(connectionString);
await connection.OpenAsync();

using var transaction = connection.BeginTransaction();

Console.WriteLine("Creating tables...");

await connection.ExecuteAsync(@"
    CREATE TABLE IF NOT EXISTS users (
        id SERIAL PRIMARY KEY,
        name TEXT NOT NULL
    );
");

Console.WriteLine("Inserting users...");

for (int i = 1; i <= 10_000; i++)
{
    await connection.ExecuteAsync(
        "INSERT INTO users (name) VALUES (@Name);",
        new { Name = $"User {i}" });

    if (i % 1000 == 0)
    {
        Console.WriteLine($"Inserted {i} users...");
    }
}

transaction.Commit();

Console.WriteLine("Done!");
```

Why did I write this as a script?
I didn't want to clutter my app with throwaway seed logic.
I just needed a quick way to populate my database with test data.
This script does exactly that, and I can run it with:

```bash
dotnet run seed.cs
```

## File-Level Directives: The Magic Behind It

The real power comes from file-level directives.
These let you configure your app without leaving the .cs file:

**Package References**

```csharp
#:package Dapper@2.1.66
#:package Npgsql@9.0.3
```

**SDK Selection**

```csharp
#:sdk Microsoft.NET.Sdk.Web
```

This tells .NET to treat your file as a web application, enabling ASP.NET Core features:

```csharp
#:sdk Microsoft.NET.Sdk.Web
#:package Microsoft.AspNetCore.OpenApi@9.*

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/", () => "Hello from a file-based API!");
app.MapGet("/users/{id}", (int id) => new { Id = id, Name = $"User {id}" });

app.Run();
```

You now have a running web API.
No project file.
No `Startup.cs`.
Just C# that does what you want.

**MSBuild Properties**

You can also set MSBuild properties directly in the file:

```csharp
#:property LangVersion preview
#:property Nullable enable
```

## When Your Script Grows Up

The brilliant part? When your file-based app gets complex enough to need project structure, converting is seamless:

```bash
dotnet project convert api.cs
```

This creates:

- A new folder named after your file
- A proper `.csproj` file with all your directives converted to MSBuild properties
- Your code moved to `api.cs` (or `Program.cs` if you prefer)
- Everything ready for full project development

Given our API example above, the generated `.csproj` looks like:

```xml
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.*" />
  </ItemGroup>
</Project>
```

Your file-based app evolves naturally into a project-based app.
No need to rewrite or restructure everything.
This makes it easy to start small and grow as needed, without losing the simplicity of the initial script.

## Takeaway

The bottom line is this: C# just became significantly more approachable.
The barrier to entry dropped from "learn project files and MSBuild" to "write C# and run it."

For experienced developers, this is a productivity boost for scripting and prototyping.
For newcomers, this removes the biggest stumbling block to getting started with C#.

The best part?
Microsoft didn't create a separate scripting language or runtime.
They made regular C# easier to use.
Your file-based apps are real .NET applications that can grow into full projects when needed.

The ceremony is dead. Long live practical C#.

---



<Sponsorships>

[**EF Core is too slow**](https://entityframework-extensions.net/?utm_source=milanjovanovic&utm_medium=newsletter&utm_campaign=june-2025)? Discover how you can easily insert 14x faster (reducing saving time by 94%).
Boost your performance with our method integrated within EF Core: Bulk Insert, update, delete, and merge.
Join 5,000+ satisfied customers who have trusted our library since 2014.
[**Learn more**](https://entityframework-extensions.net/?utm_source=milanjovanovic&utm_medium=newsletter&utm_campaign=june-2025)

NET devs, your app's performance is trying to tell you something.
Are you listening?
[**Trace Explorer**](https://blog.sentry.io/find-and-fix-performance-bottlenecks-with-sentrys-trace-explorer/?utm_source=dotnetweekly&utm_medium=paid-community&utm_campaign=tracing-fy26q1-traceexplorer&utm_content=newsletter-dotnettracing-checkitout)
makes it easy to spot trends, find bottlenecks, and debug slow spans—without drowning in logs.
Search, filter, and aggregate to find what actually matters, like your slowest URLs, APIs & assets, jump straight to the culprit,
and get back to shipping cool stuff.
[**Check it out**](https://sentry.io/product/tracing/?utm_source=dotnetweekly&utm_medium=paid-community&utm_campaign=tracing-fy26q1-traceexplorer&utm_content=newsletter-dotnettracing-checkitout).

</Sponsorships>

I came across a Medium article with 700+ claps promoting this "SQL performance trick":

**"Filter Early, JOIN Later"**

<figure className="figure-center">
  <div className="bordered">
    <Image
      src="blogs/mnw_145/sql_performance_tip.png"
      width={910 * 0.75}
      height={906 * 0.75}
      alt="SQL performance tip that doesn't actually work."
    />
  </div>
  <figcaption>Source: SQL Tricks that Cut My Query Time by 80%</figcaption>
</figure>

The claim goes like this: instead of joining tables first and then filtering, you should filter in a subquery first, then join.

The supposed benefit?

> The database filtered the smaller table first, then did the JOIN — saving time and memory.

Here is the thing - this advice is **completely wrong** for modern databases.

Let me show you why with actual data.

## The Supposed "Optimization"

The article shows two queries. Here is the "bad" version:

```sql
SELECT *
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE o.total > 500;
```

And the "optimized" version:

```sql
SELECT *
FROM (
  SELECT * FROM orders WHERE total > 500
) o
JOIN users u ON u.id = o.user_id;
```

The claim is that the second query is faster because it "filters first, then joins."

Sounds logical, right?
**Wrong.**

## Testing with Real Data

I tested both queries on a PostgreSQL database with:

- 10,000 users
- 5,000,000 orders (500 per user)
- Filtering for orders > $500

Let me run `EXPLAIN ANALYZE` on both queries to see what actually happens.

## The Results

Here are the execution plans for both queries:

**"Bad" Query Execution Plan:**

```
Hash Join  (cost=280.00..96321.92 rows=2480444 width=27) (actual time=1.014..641.202 rows=2499245 loops=1)
  Hash Cond: (o.user_id = u.id)
  ->  Seq Scan on orders o  (cost=0.00..89528.00 rows=2480444 width=14) (actual time=0.006..368.857 rows=2499245 loops=1)
        Filter: (total > '500'::numeric)
        Rows Removed by Filter: 2500755
  ->  Hash  (cost=155.00..155.00 rows=10000 width=13) (actual time=0.998..0.999 rows=10000 loops=1)
        Buckets: 16384  Batches: 1  Memory Usage: 577kB
        ->  Seq Scan on users u  (cost=0.00..155.00 rows=10000 width=13) (actual time=0.002..0.341 rows=10000 loops=1)
Planning Time: 0.121 ms
Execution Time: 685.818 ms
```

**"Optimized" Query Execution Plan:**

```
Hash Join  (cost=280.00..96321.92 rows=2480444 width=27) (actual time=1.019..640.613 rows=2499245 loops=1)
  Hash Cond: (orders.user_id = u.id)
  ->  Seq Scan on orders  (cost=0.00..89528.00 rows=2480444 width=14) (actual time=0.005..368.260 rows=2499245 loops=1)
        Filter: (total > '500'::numeric)
        Rows Removed by Filter: 2500755
  ->  Hash  (cost=155.00..155.00 rows=10000 width=13) (actual time=1.004..1.005 rows=10000 loops=1)
        Buckets: 16384  Batches: 1  Memory Usage: 577kB
        ->  Seq Scan on users u  (cost=0.00..155.00 rows=10000 width=13) (actual time=0.003..0.348 rows=10000 loops=1)
Planning Time: 0.118 ms
Execution Time: 685.275 ms
```

**The execution plans are identical.**

Both queries took ~685ms.
The "optimization" did absolutely nothing.

Here's the simplified execution plan, where I removed some details:

```
Hash Join
  Hash Cond: (o.user_id = u.id)
  ->  Seq Scan on orders o
        Filter: (total > '500'::numeric)
        Rows Removed by Filter
  ->  Hash
        ->  Seq Scan on users u
```

The core operations are:

1. Sequential Scan on `orders` table with filter applied
2. Sequential Scan on `users` table
3. Hash operation to build hash table from `users`
4. Hash Join using the hash condition on `user_id`

## Query Optimizers Are Smarter Than You

Modern databases use **cost-based optimizers**.
Here is what happens when you run a query:

1. **Parser** turns your SQL into an abstract syntax tree
2. **Optimizer** rewrites your query into the most efficient form
3. **Executor** runs the optimized plan

The optimizer looks at your query and says:
"I don't care how you wrote this. I will figure out the best way to execute it."

Both of our queries get rewritten to the same optimal plan:

- Filter the orders table first (because that eliminates rows early)
- Build a hash table from users (the smaller table)
- Hash join the filtered orders with users

**The optimizer already does the "optimization" automatically.**

Your manual subquery does not make it faster - it just makes your SQL harder to read.

## How Cost-Based Optimization Works

The query optimizer has statistics about your tables:

- Row counts
- Data distribution
- Index availability
- Column selectivity

It uses these stats to estimate the cost of different execution strategies:

- Which table to scan first
- Which join algorithm to use (hash, nested loop, merge)
- When to apply filters
- Which indexes to use

Then it picks the cheapest plan.
Your well-intentioned manual "optimization" gets ignored because the optimizer knows better.

## Summary

The "Filter Early, JOIN Later" advice is a relic from ancient database systems that did not have sophisticated optimizers.

Modern databases like PostgreSQL, MySQL, and SQL Server already do predicate pushdown and join reordering automatically.
Your manual "optimizations" are pointless and make code harder to maintain.

Write clear, readable SQL.
Let the optimizer do its job.

**The real lesson?**
Stop believing every performance tip you read online.
Use `EXPLAIN ANALYZE` to understand what your database is actually doing.

---



<Sponsorships>

You're Invited: [**Watch Postman's Keynote Talk, APIs in the Age of Autonomous Agents**](https://youtube.com/live/k_ZfWFP0hfs)
Can't be at POST/CON this year?
Don't worry—we've got you! Join Postman CEO Abhinav Asthana & Head of Marketing Justine Davis for this livestream keynote
event on June 4 at 9:00 AM PT as they talk through how APIs have evolved from simple endpoints to intelligent instructions for autonomous agents.
Learn how leading teams are standardizing design, automating testing, and scaling distribution in an AI-driven world.
[**Get notified and tune in live on YouTube**](https://youtube.com/live/k_ZfWFP0hfs)

Nick Chapsas' Dometrain is celebrating 2 years of teaching .NET developers, and they are offering their
[**"From Zero to Hero: REST APIs in .NET"**](https://dometrain.com/course/from-zero-to-hero-rest-apis-in-asp-net-core/?ref=milan-jovanovic&promo=newsletter-20250531)
course for free.
Until the end of June, use the link below, and the course is yours to keep for 1 month.
[**Get it for free**](https://dometrain.com/course/from-zero-to-hero-rest-apis-in-asp-net-core/?ref=milan-jovanovic&promo=newsletter-20250531).

</Sponsorships>

When you're building .NET applications, choosing the right **reverse proxy** can make a huge difference.
Two popular options keep coming up: Microsoft's [**YARP**](implementing-an-api-gateway-for-microservices-with-yarp) (Yet Another Reverse Proxy)
and the tried-and-true [**Nginx**](https://nginx.org/).

Here's the thing - everyone talks about which one is "better," but rarely do you see actual numbers.
So I decided to put both through the same tests and see what happens.

I'll test both proxies using the exact same API, same hardware, and same load testing approach.
No bias, just data.

## The Test API

I kept the test API super simple on purpose.
This way, we're measuring proxy performance, not how fast the backend can process complex requests:

```csharp
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/hello", () =>
{
    return Results.Ok("Hello world!");
});

app.Run();
```

This basic endpoint means we're testing the proxy itself, not waiting for complex business logic to run.

## YARP Configuration

YARP is pretty nice to work with if you're already in the .NET world. The setup is straightforward:

```csharp
var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();
app.MapReverseProxy();
app.Run();
```

It's equally simple to configure [**load balancing**](horizontally-scaling-aspnetcore-apis-with-yarp-load-balancing)
or [**authentication**](implementing-api-gateway-authentication-with-yarp).

The routing setup is clean and uses a `**catch-all` pattern to forward everything:

```json
{
  "ReverseProxy": {
    "Routes": {
      "default": {
        "ClusterId": "hello",
        "Match": { "Path": "{**catch-all}" }
      }
    },
    "Clusters": {
      "hello": {
        "Destinations": {
          "destination1": {
            "Address": "http://hello.api:8080"
          }
        }
      }
    }
  }
}
```

## Nginx Setup

For Nginx, I went with Docker to keep things simple.
The configuration does the same job as YARP:

```yml
nginx.proxy:
  image: nginx:alpine
  ports:
    - '3001:80'
  volumes:
    - ./nginx-proxy.conf:/etc/nginx/nginx.conf:ro
  depends_on:
    - hello.api
```

The Nginx config does exactly what YARP does - just with different syntax:

```nginx
events {}

http {
    upstream backend {
        server hello.api:8080;
    }

    server {
        listen 80;
        location / {
            proxy_pass http://backend;
        }
    }
}
```

## Full Docker Compose Setup

Here's the complete `docker-compose.yml` that ties everything together:

```yml
services:
  hello.api:
    image: ${DOCKER_REGISTRY-}helloapi
    build:
      context: .
      dockerfile: Hello.Api/Dockerfile

  yarp.proxy:
    image: ${DOCKER_REGISTRY-}yarpproxy
    build:
      context: .
      dockerfile: Yarp.Proxy/Dockerfile
    ports:
      - 3000:8080
    depends_on:
      - hello.api

  nginx.proxy:
    image: nginx:alpine
    ports:
      - '3001:80'
    volumes:
      - ./nginx-proxy.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - hello.api
```

## Load Testing with k6

I used k6 to hit both proxies with the same load patterns.
I repeated the test with different numbers of virtual users (VUs) to see how each proxy handles increasing traffic.
This keeps things fair - same test, same conditions:

**YARP Test Script**:

```js
import http from 'k6/http';
import { check } from 'k6';

export let options = {
  scenarios: {
    yarp: {
      executor: 'per-vu-iterations',
      vus: 200, // 10, 50, 100, 200
      iterations: 1000,
      exec: 'testYarp',
      startTime: '0s'
    }
  }
};

export function testYarp() {
  let res = http.get('http://localhost:3000/hello');
  check(res, {
    'YARP: status 200': (r) => r.status === 200
  });
}
```

**Nginx Test Script**:

```js
import http from 'k6/http';
import { check } from 'k6';

export let options = {
  scenarios: {
    nginx: {
      executor: 'per-vu-iterations',
      vus: 200, // 10, 50, 100, 200
      iterations: 1000,
      exec: 'testNginx',
      startTime: '0s'
    }
  }
};

export function testNginx() {
  let res = http.get('http://localhost:3001/hello');
  check(res, {
    'NGINX: status 200': (r) => r.status === 200
  });
}
```

## Performance Results

Here's where things get interesting.
The numbers show a clear pattern:

```
| VUs  | YARP RPS | NGINX RPS | YARP p90 Latency (ms) | NGINX p90 Latency (ms) | YARP p95 Latency (ms) | NGINX p95 Latency (ms) |
|------|----------|-----------|-----------------------|------------------------|-----------------------|------------------------|
| 10   | 12692    | 9756      | 1.04                  | 1.10                   | 1.06                  | 1.52                   |
| 50   | 27080    | 10614     | 2.70                  | 5.23                   | 3.18                  | 5.68                   |
| 100  | 32432    | 10324     | 4.66                  | 10.61                  | 5.43                  | 10.96                  |
| 200  | 36662    | 10169     | 7.77                  | 21.23                  | 8.81                  | 21.92                  |
```

**Request per second (RPS)** is how many requests each proxy handled per second.

<Image
  src="blogs/mnw_144/rps_comparison.png"
  width={1750}
  height={760}
  alt="YARP vs Nginx RPS comparison"
/>

**p90 latency** is the time it took for 90% of requests to complete.

<Image
  src="blogs/mnw_144/p90_comparison.png"
  width={1750}
  height={760}
  alt="YARP vs Nginx p90 latency comparison"
/>

**p95 latency** is the time it took for 95% of requests to complete.

<Image
  src="blogs/mnw_144/p95_comparison.png"
  width={1750}
  height={760}
  alt="YARP vs Nginx p95 latency comparison"
/>

### Throughput Analysis

YARP really shines here.
It handles way more requests - almost 3.6x more at 200 users.
What's cool is how it scales up as you add more load.
Nginx stays pretty much flat around 10k requests per second, but YARP keeps climbing from 12k all the way to 36k.

### Latency Comparison

The latency story is even more impressive for YARP.
At 200 users, YARP keeps response times under 8ms while Nginx hits 21ms.
That's a big difference when you're trying to keep your app fast.

## Hold Up - That's Not Fair

Looking at these results, we're missing something important: **this comparison isn't fair to Nginx**.

The default Nginx configuration I used is fine for basic setups, but it's not optimized for high-throughput scenarios.
Nginx uses conservative defaults that work everywhere but don't push performance limits.

So let me fix the Nginx configuration and re-run the tests.

Here's the updated Nginx config with some tweaks to improve performance:

```nginx {1,4,19}
worker_processes auto;

events {
    worker_connections 65536;
    multi_accept on;
    use epoll;
}

http {
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 30;
    keepalive_requests 1000;
    types_hash_max_size 4096;

    upstream backend {
        server hello.api:8080;
        keepalive 512;
    }

    server {
        listen 80;

        location / {
            proxy_pass http://backend;
            proxy_http_version 1.1;
            proxy_set_header Connection "";
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}
```

## Performance Results - After Tuning

Here are the results after re-running the tests:

```
| VUs  | YARP RPS | NGINX RPS | YARP p90 Latency (ms) | NGINX p90 Latency (ms) | YARP p95 Latency (ms) | NGINX p95 Latency (ms) |
|------|----------|-----------|-----------------------|------------------------|-----------------------|------------------------|
| 10   | 12692    | 17572     | 1.04                  | 0.58                   | 1.06                  | 0.74                   |
| 50   | 27080    | 36687     | 2.70                  | 1.81                   | 3.18                  | 2.09                   |
| 100  | 32432    | 43289     | 4.66                  | 3.18                   | 5.43                  | 3.88                   |
| 200  | 36662    | 46850     | 7.77                  | 6.34                   | 8.81                  | 7.72                   |
```

<Image
  src="blogs/mnw_144/rps_comparison_tuned.png"
  width={1750}
  height={760}
  alt="YARP vs Nginx RPS comparison"
/>

<Image
  src="blogs/mnw_144/p90_comparison_tuned.png"
  width={1750}
  height={760}
  alt="YARP vs Nginx p90 latency comparison"
/>

<Image
  src="blogs/mnw_144/p95_comparison_tuned.png"
  width={1750}
  height={760}
  alt="YARP vs Nginx p95 latency comparison"
/>

### Throughput Analysis

Now this is more interesting.
Nginx actually edges out YARP in raw throughput - hitting 46k requests per second vs YARP's 36k at 200 users.
Both proxies scale well as load increases, but Nginx shows why it's been the go-to choice for high-traffic sites.

### Latency Comparison

The latency story is pretty close.
At lower loads, Nginx actually has better response times.
At 200 users, both proxies keep response times reasonable - YARP at 7.77ms and Nginx at 6.34ms for p90 latency.
The difference isn't huge either way.

## Key Takeaways

**Configuration matters more than you think**.
The initial results showed YARP crushing Nginx, but that was with Nginx's conservative defaults.
Once properly tuned, Nginx shows why it's been powering the internet for years.

**Nginx wins on raw performance**.
With proper configuration, Nginx handles more requests and keeps latency slightly lower.
That extra throughput matters when you're dealing with serious traffic.

**YARP offers better integration**.
Even though Nginx edges out performance, YARP feels natural in .NET projects.
Same configuration style, same patterns, same tooling.
Sometimes that developer experience is worth more than a few extra requests per second.

**Always tune your tools**.
This whole exercise shows why benchmarks with default configs can be misleading.
If you're choosing between these two, make sure you're comparing optimized configurations, not defaults.

The choice isn't as clear-cut as I initially thought.
Nginx wins on pure performance, but YARP wins on .NET integration.
Pick based on what matters more for your specific situation.

---



<Sponsorships>

Unlock the Power of [**ABP.IO's Core Modules**](https://abp.io/modules?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_may24)
and supercharge your .NET web app development:\
✅ SaaS - Build scalable, multi-tenant applications.\
✅ Identity & Permission Management - Handle authentication, roles, and claims.\
✅ Audit Logging - Track changes and user actions automatically.\
✅ Account - Get a full-featured, customizable user account UI.\
➡️ [**Explore ABP.IO Modules**](https://abp.io/modules?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_may24)
which are fully extensible and production-ready.

[**How to Migrate Your WPF Components to .NET MAUI**](https://www.telerik.com/blogs/how-to-migrate-wpf-components-net-maui?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=maui-general-awareness)\
Looking to modernize your WPF apps?
Discover how to seamlessly migrate your WPF components to .NET MAUI with Telerik's expert guide.
Learn best practices, avoid common pitfalls, and future-proof your desktop applications for cross-platform success.
[**Read the full guide**](https://www.telerik.com/blogs/how-to-migrate-wpf-components-net-maui?utm_medium=cpm&utm_source=milanjovanovich&utm_campaign=maui-general-awareness).

</Sponsorships>

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](https://en.wikipedia.org/wiki/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:

```csharp
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:

```csharp
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:

```csharp
// 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:

```csharp
// 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:

```csharp
// 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**](improving-aspnetcore-dependency-injection-with-scrutor):

```csharp
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.

```csharp {34,36}
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:

```csharp
services.AddTransient<IDomainEventsDispatcher, DomainEventsDispatcher>();
```

## Usage Example

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

```csharp
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**](how-to-use-domain-events-to-build-loosely-coupled-systems).

## 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**](implementing-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**](/ddd-refactoring) and
[**Clean Architecture**](/pragmatic-clean-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.

---



<Sponsorships>

[**AWS Summit Washington DC: the Future of Cloud Innovation**](https://fnf.dev/4kGXJqr)\
Join AWS innovators at AWS Summit, June 10-11 in Washington DC, for deep dives on everything cloud from architecture to infrastructure.
340+ sessions with hands-on workshops, labs, interactive builder sessions led by AWS experts, “chalk talk” whiteboard sessions, and skillset-building training.
Learn from cutting-edge cloud technologists solving real-world challenges across industries.
[**FREE registration — claim your spot today!**](https://fnf.dev/4kGXJqr)

[**Design .NET Apps Visually with ABP Studio**](https://abp.io/studio?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_may17)\
Say goodbye to boilerplate and repetitive setup.
ABP Studio is your visual development tool for building modern, modular .NET applications—faster than ever.
Generate full-layered solutions, manage modules, entities, and UI from an intuitive interface — all fully aligned with the ABP.IO
No more context switching or manual coding for scaffolding. Just build, customize, and ship.
➡️ [**Download & Try ABP Studio today**](https://abp.io/studio?utm_source=newsletter&utm_medium=affiliate&utm_campaign=milanjovanovic_may17)

</Sponsorships>

MediatR is going commercial.

[Jimmy Bogard recently announced](https://www.jimmybogard.com/automapper-and-mediatr-going-commercial/)
that 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**](stop-conflating-cqrs-and-mediatr).
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.

```csharp
// 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:

```csharp
// 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);
}
```

```csharp
// 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**](functional-error-handling-in-dotnet-with-the-result-pattern).

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.

```csharp
// 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.

```csharp
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**](cqrs-validation-with-mediatr-pipeline-and-fluentvalidation):

```csharp
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](https://github.com/khellang/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.

```csharp
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:

```csharp
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:

```csharp
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**](/templates/clean-architecture) includes everything covered in this article (fully wired up).

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

---



<Sponsorships>

[**Aiven for OpenSearch®**](https://fnf.dev/3SpnQpp) is the fully managed, open source alternative to Elasticsearch - built for
high-performance, distributed search and analytics.
Spin up production-ready clusters in under 10 minutes, deploy to the cloud of your choice,
and offload the rest to Aiven so you can focus on building, not managing infrastructure.
[**Sign up for free and get additional $100 credits here!**](https://fnf.dev/3EW72Dy)

Code reviews are time-consuming.
[**CodeRabbit**](https://fnf.dev/3F2eDR1) is your AI co-pilot—instantly generating review comments, one-click fixes, and custom AST-grep rules.
It can even plan refactors and merge via chat.
Trusted on 10M+ PRs across 1M repos and 70K+ OSS projects.
[**Try Code Rabbit today and cut .NET code review time and bugs in half**](https://fnf.dev/3F2eDR1).

</Sponsorships>

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:

1. **Inspect** a typical anemic implementation.
2. **Identify** hidden business rules that make it brittle.
3. **Refactor** toward a behavior-rich aggregate one refactor at a time.
4. **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**.

```csharp
// 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.

<div className='blockquote'>

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

</div>

## Guiding Principles Before We Touch Code

1. **Protect invariants close to the data.**
   Stock, discounts, and credit checks belong where the data lives — inside the `Order` aggregate.
2. **Expose intent, hide mechanics.**
   The application layer should read like a story: _"place order"_, not _"calculate totals, check credit, write to DB"_.
3. **Refactor in slices.**
   Each move is safe and compilable; no big-bang rewrites.
4. **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.

```csharp
// 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 Injecting Services into Domain Methods**

Passing services like `IPricingService` or `IInventoryService` into a domain method such as `Order.Create` might seem unconventional at first glance.
But it's a deliberate design choice: it keeps the orchestration inside the domain model, where the business logic naturally belongs,
instead of bloating the application service with procedural workflows.

This approach maintains the entity's autonomy while still aligning with dependency injection principles — dependencies are passed explicitly, not resolved from within.
It's a powerful technique, but one that should be used selectively — only when the operation clearly fits within the domain's responsibility
and benefits from direct access to external services.

### Guard the Aggregate's Internal State

```csharp
// 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

```csharp
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**](/ddd-refactoring).
It's packed with before-and-after examples like this one.

---


Previous issues of The .NET Weekly