
<Sponsorships>

[**The AI Agent for professional .NET developers**](https://fnf.dev/4lhJzeW)\
You ship to production; vibes won't cut it.
Augment Code's powerful AI coding agent meets professional .NET developers exactly where they are,
delivering deep context into even the gnarliest codebases and learning how you work.
[**Now supporting GPT-5 and Sonnet 4**](https://fnf.dev/4lhJzeW).

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

</Sponsorships>

Bad APIs create friction for developers, increase maintenance costs, and make change risky.
Good API design doesn't mean following every "best practice" blindly.
It means choosing the right trade-offs for your context and sticking to them.

Here are 5 common mistakes I see repeatedly, why they cause problems, and how to avoid them with pragmatic, battle-tested solutions.

## 1. Inconsistent Naming and Structure

Naming is the first thing consumers see.
Inconsistency here leads to constant documentation lookups, broken expectations, and more bugs.

Look, we've all been there.
You successfully call `/users` and `/products`, so naturally you try `/orders`.
But nope, this API uses `/order-list` for some reason.
Now you're back to the docs, breaking your flow, wondering why anyone would do this.
Multiply this friction by dozens of endpoints, and you've built an API that makes developers want to flip tables.

I get it, deep URL hierarchies like `/users/{id}/habits/{habitId}/entries/{entryId}/comments/{commentId}` feel satisfying.
They mirror your beautiful domain model!
But here's the thing: you've just **hardcoded your entire data structure** into your URLs.
When business requirements change (and they will), you can't reorganize without breaking clients.

Plus, what happens when someone only has a comment ID?
They need to somehow figure out the user, habit, and entry IDs just to fetch one comment.
That's ridiculous.

Keep it simple with **plural nouns**: `/users`, `/habits`, `/entries`.
No more guessing if it's `user` or `users`.

**Only nest when something truly belongs to something else.**
User settings belong to and die with the user, so `/users/{id}/settings` makes sense.
Comments can exist independently, so `/users/{id}/posts/{postId}/comments` can be simplified.

Instead, flatten with filters:

```http
# Instead of deep nesting
GET /users/{userId}/habits/{habitId}/entries

# Use filters for flexibility
GET /entries?userId={userId}&habitId={habitId}
GET /entries?habitId={habitId}  # Now you can get entries without knowing the user
```

And please, for the love of all that is holy, wrap your arrays:

```json
{
  "data": [
    {
      "id": "e_8YH",
      "habitId": "code-review",
      "at": "2025-08-08T09:17:34Z",
      "value": 5,
      "unit": "reviews",
      "tags": ["team"]
    },
    {
      "id": "e_8Z2",
      "habitId": "deep-work",
      "at": "2025-08-07T07:00:00Z",
      "value": 2,
      "unit": "pomodoros",
      "note": "EF filters optimized"
    }
  ],
  "total": 42,
  "hasMore": true,
  "nextCursor": "cursor_01J9KaBcd"
}
```

I know it feels like pointless boilerplate now, but trust me, when you need to add pagination info six months from now,
you'll thank yourself for not having to break every client that expects a raw array.

Yeah, the [REST](https://en.wikipedia.org/wiki/REST) purists will complain that filters aren't "RESTful enough."
Let them.
Your API will be flexible, maintainable, and actually pleasant to use.
I'll take that over conceptual purity any day.

## 2. Poor Versioning Strategy

Everyone defaults to [**versioning**](api-versioning-in-aspnetcore) (`/v1/users`) thinking they're being smart about future changes.
Spoiler: they're not. They're creating a maintenance nightmare.

Here's what actually happens when you have v1, v2, and v3 running:

- Every bug needs to be fixed three times
- Every security patch needs three deployments
- Your docs become a choose-your-own-adventure novel
- Support has no idea which version that angry customer is using
- You spend weekends maintaining code you wrote two years ago

But the worst part?
**Versioning makes you lazy**.
Instead of thinking "how can I evolve this without breaking clients?" you just think "eh, I'll bump the version."
Now your clients have to rewrite their entire integration because you wanted to rename a field.

Watch this disaster unfold:

```
v1: GET /users returns {id, name, email}
v2: GET /users returns {id, fullName, emailAddress}  // "looks cleaner!"
v3: GET /users returns {id, firstName, lastName, email}  // "we need split names!"
```

Congrats, you're now maintaining three different response formats for the same damn data.
That v1 client?
They'll never get new features unless they rewrite everything.
Found a critical bug? Hope you enjoy patching it three times!

Here's the **radical idea**: **don't version at all**.
I'm serious.

Add fields, don't replace them:

```json
// What you ship first
{ "id": 1, "name": "John Doe" }

// What you ship later (keeping the old field)
{
  "id": 1,
  "name": "John Doe",  // Still there! Mark it deprecated in docs
  "firstName": "John",
  "lastName": "Doe"
}
```

Need optional features?
Use query parameters:

```http
GET /users/{id}?include=habits,entries
GET /users/{id}?format=detailed
```

If you absolutely must make a breaking change (and really think about this), create a new resource:

```http
# Old faithful, unchanged
GET /users/{id}

# New hotness
GET /userProfiles/{id}
```

When breaking changes are truly unavoidable, at least be a decent human about it.
Give people 6-12 months notice.
Run both versions in parallel.
Write a migration guide that doesn't suck.
And for crying out loud, monitor who's still using the old stuff so you can reach out before pulling the plug.

Yes, this means you need to actually think about your API design upfront.
You can't just YOLO field names and fix them later.
But that constraint will make you design better APIs, and future-you will buy present-you a beer.

If you want to learn more about this, I recommend reading [API Change Management](https://medium.com/good-api/api-change-management-2fe5bba32e9b).

## 3. Ignoring Pagination, Filtering, and Searching

That `GET /entries` endpoint works great with your 10 test records.
Then you launch, get actual users, and suddenly you're returning 100,000 entries in a single response.
Your API times out, your mobile users on crappy connections hate you, and your cloud bill makes you cry.

"We'll add pagination later," you said.
Well, now it's later, and adding pagination means breaking every client that expects an array.
Nice job.

Without filtering, your clients are downloading thousands of records to find the five they actually need.
It's like making someone download all of Wikipedia to read one article.
Your servers are melting, serializing data nobody wants.
Your users are burning through their data plans.
Everyone loses.

**Filtering** is for when you know exactly what you want:

```http
GET /entries?habitId=123&date=2025-08-01&status=completed
```

**Searching** is for when you kinda know what you want:

```http
GET /entries/search?q=morning+run+park
```

Don't try to be clever and combine them.
Filtering uses your database indexes efficiently.
Searching needs full-text magic.
Mix them and you'll end up with something that does neither well.

For pagination, you've got two choices, and they both kinda suck in different ways.

**Offset/limit** is what everyone starts with:

```http
GET /entries?offset=100&limit=50
             # or you can call them skip and take
             # or you can call them page and pageSize
             # use whatever you like best
```

It's dead simple and lets users jump to page 5, but here's the fun part: add or delete an item while someone's paginating, and they'll either skip entries or see duplicates.
Plus, asking for offset=10000 makes your database cry as it counts through all those rows.

[**Cursor-based pagination**](understanding-cursor-pagination-and-why-its-so-fast-deep-dive) is the "proper" solution:

```http
GET /entries?limit=50&cursor=eyJpZCI6MTIzfQ==
```

Rock solid, no skipped items, consistent performance.
But you can't jump to arbitrary pages and cursors can become invalid if underlying data changes significantly.

Yeah, implementing all this is a pain.
You need cursor encoding, parameter validation, query optimization.
But trying to add it after launch?
Wouldn't recommend.
Just build it right the first time.

## 4. Unclear or Inconsistent Error Handling

`{"error": "An error occurred"}` — if you return this, I hate you.

Seriously, when your API spits out these useless errors, here's what happens: I try random stuff hoping something works.
I add defensive code everywhere because I don't trust you.
I flood your support channel asking what's wrong.
Then I complain about your API on social media (any publicity is good publicity, eh?).

A good error tells me three things: **what broke**, **why it broke**, and **how to fix it**.
Is that so hard?

Stop inventing your own janky error format.
Use [**Problem Details**](problem-details-for-aspnetcore-apis) (RFC 9457) like a civilized developer:

```json
{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "The request body contains invalid fields",
  "instance": "/habits/123",
  "errors": [
    {
      "field": "name",
      "reason": "Must be between 1 and 100 characters",
      "value": ""
    },
    {
      "field": "frequency",
      "reason": "Must be one of: daily, weekly, monthly",
      "value": "sometimes"
    }
  ]
}
```

See how that actually helps me fix the problem? Revolutionary, I know.

And please use the right status codes. It's not that hard:

- `400 Bad Request`: You sent garbage
- `401 Unauthorized`: Who are you?
- `403 Forbidden`: I know who you are, but no
- `404 Not Found`: That thing doesn't exist
- `409 Conflict`: That conflicts with something
- `422 Unprocessable Entity`: I understand what you want, but it's wrong\
  (_I don't use this personally, and prefer returning 400 for validation failures_)
- `429 Too Many Requests`: Slow down, cowboy
- `500 Internal Server Error`: We screwed up
- `503 Service Unavailable`: We're drowning, try again later

Now, don't go leaking your entire stack trace in production like an amateur.
Give friendly errors to users, detailed errors in dev/staging, and log the gory details server-side where you can actually use them.

## 5. Ignoring Security Until It's Too Late

"We'll add auth in phase 2" — famous last words before your API becomes a data buffet for hackers.
Ask the [Tea app](https://www.teaforwomen.com/cyberincident) how that worked out for them.

Here's what happens when you try to bolt on security later: Every client breaks when you add authentication.
That data you've been leaking? It's probably been scraped already.
Your compliance audit? Failed.
That one security incident? Your users will bring it up for years.

**Authentication** (who are you?) and **Authorization** (what can you do?) are different things.
I've seen so many APIs that check if you're logged in but never check if you should actually access that data.
Don't be that person.

[**Rate limiting**](advanced-rate-limiting-use-cases-in-dotnet) isn't just about stopping abuse, it's about fairness.
Start simple: 1000 requests per hour per API key.
When they hit the limit, return `429` with headers showing when they can try again.
Then get fancy: different limits for different endpoints, higher limits for paying customers,
lower limits for that one client who keeps doing weird stuff.

**HTTPS everywhere**.
Yes, even for your internal "no one will ever find this" API.
It's 2025, not 2005.
[Let's Encrypt](https://letsencrypt.org/) is free.
You have no excuse.

Look, security makes things slower and more complex.
Auth checks on every request, encryption overhead, state management for rate limiting, it all adds up.
But you know what's worse?
Explaining to your users why their data is being sold on the dark web.
Build security in from the start, or prepare for a world of pain.

## Final Thoughts

Good API design isn't about perfection, it's about making intentional, informed decisions.
Every choice is a tradeoff.
Consistency might limit flexibility.
Security will impact performance.
Stability means slower innovation.

Here's what actually matters: **know your tradeoffs and own them**.
Document why you made these choices (future you will thank you).
Stay consistent even when it's tempting not to.
Design for evolution, not some imaginary perfect future.
And listen to your users, but don't turn your API into a frankenstein monster trying to please everyone.

**Your API is a promise to other developers**.
Every time you break that promise (with a breaking change, an inconsistent pattern, or a useless error message) you lose their trust.
And trust me, developers hold grudges.

Build the API you'd want to use.
Your developers will thank you, your support team will thank you, and honestly, you'll thank yourself six months from now when you have to maintain this thing.

Want to dive deeper? Check out my [**Pragmatic REST APIs**](/pragmatic-rest-apis) course where I cover all of this (and more).

---



<Sponsorships>

[**Unlock AI Success with MongoDB Atlas on Azure - Final Webinar**](https://bit.ly/4odLTX5)\
Successful AI applications require a secure, scalable data foundation. Join MongoDB and Microsoft on
August 6 for From Vectorsto Value, the final webinar in this series, and learn how leading enterprises are
leveraging MongoDB Atlas and Azure AI Foundry to build powerful AI-driven applications with native
vector search and real-time reasoning.
[**Register now**](https://bit.ly/4odLTX5).

[**Share your thoughts about API development**](https://fnf.dev/4lSb9Rm)🧠\
Postman wants to learn how developers are really building and scaling APIs - what's working, what's broken,
and how AI is changing the game (for better or worse).
This year's survey covers:
How AI is reshaping API development;
What teams are actually doing for security and monitoring;
How real-world teams are collaborating and testing in 2025.
It only takes ~10-15 minutes.
You'll also be entered to win an iPad Pro M4 (with the good accessories).

👉[**Take the survey**](https://fnf.dev/4lSb9Rm).
Your input helps keep this industry honest - and evolving.

</Sponsorships>

[**Modular monoliths**](what-is-a-modular-monolith) promise the productivity of a monolith and the clear boundaries of microservices.
They work because each module is self-contained: its domain model, behavior and data live behind a boundary.
But one of the hardest places to maintain those boundaries is in the database.

Nothing stops a developer from running a rogue `JOIN` across tables or bypassing a public API.

In previous articles, I described [**four levels of data isolation**](modular-monolith-data-isolation) (table, schema, database and alternative persistence)
and argued that [**modules should expose explicit APIs**](internal-vs-public-apis-in-modular-monoliths) to access their data.

This article goes deeper on the database side.
You'll learn how to carve out logical and physical boundaries using PostgreSQL schemas and roles and EF Core,
why those choices matter, and how to handle cross-cutting queries without breaking encapsulation.

## Why enforce database boundaries?

In a modular monolith each module **owns its data**.
If Module A reaches into Module B's tables, you lose this constraint and your modules become tightly coupled.
Instead, B exposes a public API and hides its persistence logic from consumers.

Beyond clean code, enforcing boundaries at the database level protects you against mistakes
and makes it easier to extract a module into its own service later.

Database schemas act like folders: they let you organise objects and share a database among many users,
but a user can access any schema only if they have privileges.
This means we can deliberately lock each module to its own schema.

**The strategy**

- Create a schema per module and a dedicated database role.
- Grant that role privileges only on its schema and set its default search path.
- Use EF with one `DbContext` per module, setting a default schema and connection string per module.
- For cross-cutting queries, publish a read-only database view that acts like a public API.
- _Optional_: Use row-level security policies to restrict access within a table.

These practices give us **enforceable boundaries** while keeping the **operational overhead low**.

## Schemas, roles and search paths

PostgreSQL lets you create multiple schemas within a single database.
A module can define its own schema and a role that owns it.
The role only has usage and table-level privileges on that schema.
For example, for an orders module:

```sql
-- create a user for the module and its schema
CREATE ROLE orders_role LOGIN PASSWORD 'orders_secret';
CREATE SCHEMA orders AUTHORIZATION orders_role;
GRANT USAGE ON SCHEMA orders TO orders_role;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA orders TO orders_role;
ALTER ROLE orders_role SET search_path = orders;
```

The `ALTER ROLE` command sets the role's default search path so unqualified names resolve to the module's schema.
If you don't want to rely on the search path, always qualify table names (`orders.table_name`).

Row-level security (RLS) allows you to filter rows based on a policy expression.
You enable RLS on a table and define a policy referencing `current_user` or columns:

RLS is powerful for multi-tenant scenarios or sensitive data, but it adds complexity.
Start with schemas and roles and add RLS only when necessary.

## Configuring EF schemas and multiple DbContexts

I assume readers are comfortable with EF Core, so we'll skip the basics and focus on what matters for modular monoliths:

- Use [**one DbContext per module**](using-multiple-ef-core-dbcontext-in-single-application).
  Each context contains only the entities of its module, and you call `modelBuilder.HasDefaultSchema("orders")` in `OnModelCreating`
  to map entities to the correct schema.
  Setting a default schema also affects sequences and migrations.
- Provide a connection string per module using the module's role.
  Even if modules share the same database, separate credentials ensure that a misconfigured context cannot access another schema.
- Configure the migrations history table in each context using `MigrationsHistoryTable("__EFMigrationsHistory", "orders")`
  so that EF's migration metadata stays within the module's schema.

These settings ensure EF Core queries and migrations respect the boundaries established by the database.

## Step-by-step: Enforcing module boundaries

Suppose we have two modules (**Orders** and **Shipping**) and we want to enforce boundaries between them.
Here's what we need to do:

1. **Create schemas and roles**.
   Use SQL to create orders and shipping schemas and their corresponding roles (`orders_role`, `shipping_role`).
   Grant each role privileges only on its schema.

   ```sql
   -- Orders schema and role
   CREATE ROLE orders_role LOGIN PASSWORD 'orders_secret';
   CREATE SCHEMA orders AUTHORIZATION orders_role;
   GRANT USAGE ON SCHEMA orders TO orders_role;
   GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA orders TO orders_role;
   ALTER ROLE orders_role SET search_path = orders;

    -- Shipping schema and role
    CREATE ROLE shipping_role LOGIN PASSWORD 'shipping_secret';
    CREATE SCHEMA shipping AUTHORIZATION shipping_role;
    GRANT USAGE ON SCHEMA shipping TO shipping_role;
    GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA shipping TO shipping_role;
    ALTER ROLE shipping_role SET search_path = shipping;
   ```

2. **Add connection strings**. In configuration, define separate connection strings per module:

   ```json
   {
     "ConnectionStrings": {
       "Orders": "Host=localhost;Database=appdb;Username=orders_role;Password=orders_secret",
       "Shipping": "Host=localhost;Database=appdb;Username=shipping_role;Password=shipping_secret"
     }
   }
   ```

3. **Define DbContexts**. Each module defines its own context and sets the default schema. For the Orders module:

   ```csharp
   public class OrdersDbContext : DbContext
   {
       public DbSet<Order> Orders { get; set; } = default!;
       public DbSet<OrderLine> OrderLines { get; set; } = default!;

       public OrdersDbContext(DbContextOptions<OrdersDbContext> options) : base(options) { }

       protected override void OnModelCreating(ModelBuilder modelBuilder)
       {
           // set default schema for all entities in this context
           modelBuilder.HasDefaultSchema("orders");
           // optional: configure tables explicitly
           modelBuilder.Entity<Order>().ToTable("orders");
           modelBuilder.Entity<OrderLine>().ToTable("order_lines");
           base.OnModelCreating(modelBuilder);
       }
   }
   ```

   Register each context with its connection string and specify the migrations history table:

   ```csharp
   builder.Services.AddDbContext<OrdersDbContext>(options =>
       options.UseNpgsql(builder.Configuration.GetConnectionString("Orders"),
           o => o.MigrationsHistoryTable("__EFMigrationsHistory", "orders")));

   builder.Services.AddDbContext<ShippingDbContext>(options =>
       options.UseNpgsql(builder.Configuration.GetConnectionString("Shipping"),
           o => o.MigrationsHistoryTable("__EFMigrationsHistory", "shipping")));
   ```

4. **Maintain migrations separately**.
   Because each module has its own context and schema, you maintain migrations separately.
   When generating a migration, specify the context:

   ```bash
   dotnet ef migrations add InitialOrders --context OrdersDbContext --output-dir Data/Migrations/Orders
   ```

   Repeat this for the Shipping context.
   EF Core will generate migration classes that create tables within the specified schema (because of `HasDefaultSchema`).
   Remember to apply the migrations in the correct order when deploying. You can automate this by having a migration runner iterate through the contexts.

With schemas, roles and multiple contexts in place, the data boundary becomes enforceable at the database level:

- The **Orders** module's `DbContext` knows only about the orders schema and uses credentials that have no privileges on the **Shipping** schema.
- The **Shipping** module cannot query `orders.orders` directly because its role lacks the necessary privileges.
- Cross-module communication must go through the module's public API (or an asynchronous event).
  This explicit coupling makes dependencies obvious and maintainable.

## Cross-cutting queries

Even in a modular system you occasionally need a screen that spans multiple modules,
such as an **Order History** page that shows order and shipping data.
Resist the temptation to `JOIN` across schemas.
Two approaches can help:

- **Dedicated read model**.
  One module owns a view model and subscribes to events from others.
  This pattern works well when modules might be extracted later.

- **Database views with privileges**.
  Since our modules share a database, we can create a read-only view in the public schema that joins the relevant tables.
  We grant `SELECT` on the view to a special role or module.
  This view acts like a controlled public API.
  Consumers query the view but cannot access the underlying tables directly.
  The trade-off is similar to calling a synchronous API: if you later split the database, the view will have to be replaced with a service call.

For example:

```sql
CREATE VIEW public.order_summary AS
SELECT o.id, o.total, s.status
FROM orders.orders o
JOIN shipping.shipments s ON s.order_id = o.id;

-- grant read access to a reporting role
GRANT SELECT ON public.order_summary TO reporting_role;
```

This approach lets you build dashboards or admin screens without breaking boundaries.

## Conclusion

By giving each module its own schema, role and DbContext, and by controlling cross-module access via views or APIs,
you **ensure that boundaries in your modular monolith are enforceable** rather than aspirational.
This discipline makes it easier to evolve your system and paves the way for a future microservice extraction.

If you found this article valuable, check out my previous posts on modular monoliths:

- [What Is a Modular Monolith?](what-is-a-modular-monolith)
- [Modular Monolith Data Isolation](modular-monolith-data-isolation)
- [Internal vs Public APIs in Modular Monoliths](internal-vs-public-apis-in-modular-monoliths)

If you want a structured, hands-on approach to building modular systems, from defining boundaries to extracting services,
check out my [**Modular Monolith Architecture**](/modular-monolith-architecture) course.
Join more than 2,100+ students who have mastered modular monoliths with it.
The course walks through these patterns in depth and shows how to apply them in a real codebase.

Thanks for reading.

And stay awesome!

---



<Sponsorships>

[**The AI Agent for professional .NET developers**](https://fnf.dev/44AcRR2).
You ship to production; vibes won't cut it.
Augment Code's powerful AI coding agent meets professional .NET developers exactly where they are,
delivering deep context into even the gnarliest codebases and learning how you work.
[**Ditch the vibes and try Augment Code today**](https://fnf.dev/44AcRR2).

[**Phoenix.new: The fastest way to build Elixir apps in-browser**](https://fnf.dev/3Uwwwve)
Built by the folks at [Fly.io](https://fly.io), Phoenix.new spins up real Phoenix apps right in the browser—no setup, no yak-shaving.
The agent has root access, runs real tests, interacts with the UI in a headless browser, and pushes to GitHub.
Get live previews and a dev loop that just works.
[**Get started for free**](https://fnf.dev/3Uwwwve).

</Sponsorships>

Entity Framework Core's global query filters have long been a convenient way to apply common conditions to all queries on an entity.
They're especially handy in scenarios like [**soft deletion**](implementing-soft-delete-with-ef-core)
and [**multi-tenancy**](multi-tenant-applications-with-ef-core),
where you want the same `WHERE` clause added automatically to every query.

Previous versions of EF Core, however, suffered from **one big limitation**: each entity type could only have one filter defined.
If you needed to combine multiple conditions (for example, soft-delete and tenant isolation)
you either had to write explicit `&&` expressions or manually disable and reapply filters in specific queries.

With EF 10, that changes.
The new **named query filters** feature lets you attach multiple filters to a single entity and reference them by name.
You can then disable individual filters as needed, rather than turning off all filters at once.

Let's explore this new capability, why it matters, and some practical ways to use it.

## What Are Query Filters?

If you've used EF Core for a while, you may already be familiar with
[global query filters](https://learn.microsoft.com/en-us/ef/core/querying/filters).
A query filter is a condition that EF automatically applies to all queries for a particular entity type.
Under the hood, EF adds a `WHERE` clause whenever that entity is queried. Typical uses include:

- **Soft deletion**: filtering out rows where IsDeleted is true so that deleted records don't show up in queries by default
- **Multi-tenancy**: filtering by a TenantId so that each tenant only sees its own data

For example, a soft-delete filter might be configured like this:

```csharp
modelBuilder.Entity<Order>()
    .HasQueryFilter(order => !order.IsDeleted);
```

With the filter in place, every query on `Orders` automatically excludes soft-deleted records.
To include deleted data (say, for an admin report), you can call `IgnoreQueryFilters()` on the query.
The downside is that all filters on that entity are disabled,
which opens the door to accidentally leaking data you don't intend to show.

## Using Multiple Query Filters

Until now, EF permitted only one query filter per entity.
If you called `HasQueryFilter` twice on the same entity, the second call overwrote the first.
To combine filters you had to write a single expression with `&&`:

```csharp
modelBuilder.Entity<Order>()
    .HasQueryFilter(order => !order.IsDeleted && order.TenantId == tenantId);
```

This works but makes it impossible to selectively disable one condition.
`IgnoreQueryFilters()` disables both, forcing you to manually re-apply whichever filter you still need.
EF 10 introduces a better alternative: **named query filters**.

To attach multiple filters to an entity, call `HasQueryFilter` with a name for each filter:

```csharp
modelBuilder.Entity<Order>()
    .HasQueryFilter("SoftDeletionFilter", order => !order.IsDeleted)
    .HasQueryFilter("TenantFilter", order => order.TenantId == tenantId);
```

Under the hood, EF creates separate filters identified by the names you provide.
You can now turn off just the soft-delete filter while keeping the tenant filter in place:

```csharp
// Returns all orders (including soft‑deleted) for the current tenant
var allOrders = await context.Orders.IgnoreQueryFilters(["SoftDeletionFilter"]).ToListAsync();
```

If you omit the parameter array, `IgnoreQueryFilters()` disables all filters for the entity.

## Tip: Using Constants for Filter Names

Named filters use string keys.
Hard-coding those names throughout your codebase makes it easy to introduce typos and brittle magic strings.
To avoid this, define constants or enums for your filter names and reuse them wherever needed.
For example:

```csharp
public static class OrderFilters
{
    public const string SoftDelete = nameof(SoftDelete);
    public const string Tenant = nameof(Tenant);
}

modelBuilder.Entity<Order>()
    .HasQueryFilter(OrderFilters.SoftDelete, order => !order.IsDeleted)
    .HasQueryFilter(OrderFilters.Tenant, order => order.TenantId == tenantId);

// Later in your query
var allOrders = await context.Orders.IgnoreQueryFilters([OrderFilters.SoftDelete]).ToListAsync();
```

Having the filter names defined in a single place reduces duplication and improves maintainability.
Another best practice is to wrap the ignore call in an extension method or repository
so that consumers don't directly interact with filter names at all. For example:

```csharp
public static IQueryable<Order> IncludeSoftDeleted(this IQueryable<Order> query)
    => query.IgnoreQueryFilters([OrderFilters.SoftDelete]);
```

This makes your intent explicit and centralizes the filter logic in one place.

## Wrapping Up

The introduction of **named query filters** in EF 10 removes one of the longstanding limitations
of EF's [**global query filters**](how-to-use-global-query-filters-in-ef-core) feature.
You can now:

- Attach multiple filters to a single entity and manage them individually
- Selectively disable specific filters in a LINQ query using `IgnoreQueryFilters(["FilterName"])`
- Simplify common patterns like [**soft deletion**](implementing-soft-delete-with-ef-core) plus
  [**multi-tenancy**](multi-tenant-applications-with-ef-core) without resorting to complicated conditional logic

Named query filters can become a powerful tool to keep your queries clean and your domain logic encapsulated.

Whether you're building SaaS applications that isolate tenant data or
ensuring that deleted records stay hidden until you explicitly need them,
EF 10's named query filters offer the flexibility you've been waiting for.

Give them a try in the preview and start thinking about how they can simplify your codebase.

That's all for today.

See you next week.

---


<Sponsorships>

[**Now Available: GitHub Job Details in the Depot App**](https://fnf.dev/3TNd6lx)
Stop guessing why your GitHub Actions are failing. Depot's new GitHub Job Details feature delivers the
observability you need to quickly diagnose and fix issues, all within a unified interface.
- Get uncollapsed logs and real-time resource metrics (CPU, memory, OOM events).
- Easily correlate logs with performance data to pinpoint bottlenecks.

[**Get the visibility you need to debug builds faster**](https://fnf.dev/3TNd6lx).

A great auth product gets out of your way.
[**PropelAuth**](https://www.propelauth.com/?utm_source=newsletter&utm_campaign=mj) makes it easy to
[**add authentication to your .NET application**](https://docs.propelauth.com/guides-and-examples/guides/dot-net-oauth-guide/?utm_source=newsletter&utm_campaign=mj) -
no digging through obscure documentation or frantically searching StackOverflow for answers.
Whether you're supporting small businesses or huge enterprises, PropelAuth has everything you need:
organization management, RBAC, MFA, Enterprise SSO and more.

</Sponsorships>

Sooner or later, every .NET developer needs to generate PDF reports.
And generating polished PDF reports in .NET doesn't have to be painful.
Let me explain how.

My go-to method?

**HTML to PDF conversion**.
It's:

- Simple to implement
- Very flexible
- Ideal for stylized reports

But many popular libraries require a commercial license.
This post walks you through a completely free approach using:

- **Handlebars.NET** for templating
- **PuppeteerSharp** for headless rendering

This gives you full control over layout, styling, and content.
It's perfect for invoices, dashboards, and exports.

We'll start from scratch and build up to a complex, dynamic invoice report with full styling, images, and even headers and footers.

## Why HTML + Headless Browser?

**Pros:**

- Rich styling with CSS
- Easy to preview/debug in browser
- Supports charts/images via JS/CSS
- Full control over layout (media queries, page breaks, etc.)

**Cons:**

- Requires bundling a browser (e.g. Chromium)
- Slower than native PDF libraries
- Slightly more setup complexity

## Setting Up the Project

We'll start by installing the NuGet packages we need for Handlebars and PuppeteerSharp:

```powershell
Install-Package Handlebars.Net
Install-Package PuppeteerSharp
```

Next, we'll create our first template.
It's a simple HTML document with some Handlebars placeholders.
You'll notice them with the `{{variable}}` syntax.
These placeholders will be replaced with actual data when rendering the template.

```html


<html lang="en">
  <head>
    <style>
      body {
        font-family: Arial;
      }
    </style>
  </head>
  <body>
    <h1>Invoice #{{Number}}</h1>

    <p>Date: {{formatDate IssuedDate}}</p>

    <h2>From:</h2>
    <p>{{SellerAddress.CompanyName}}</p>
    <p>{{SellerAddress.Email}}</p>

    <h2>To:</h2>
    <p>{{CustomerAddress.CompanyName}}</p>
    <p>{{CustomerAddress.Email}}</p>

    <h2>Items:</h2>
    <table>
      <tr>
        <th>Name</th>
        <th>Price</th>
      </tr>
      {{#each LineItems}}
      <tr>
        <td>{{Name}}</td>
        <td>{{formatCurrency Price}}</td>
      </tr>
      {{/each}}
    </table>

    <p><strong>Total: {{formatCurrency Total}}</strong></p>
  </body>
</html>
```

The function calls, like `{{formatDate IssuedDate}}`, are custom helpers we can define in Handlebars.
You register them like this:

```csharp
Handlebars.RegisterHelper("formatDate", (context, arguments) =>
{
    if (arguments[0] is DateOnly date)
    {
        return date.ToString("dd/MM/yyyy");
    }
    return arguments[0]?.ToString() ?? "";
});
```

This allows us to format dates, currencies, or any other data type as needed.
You register these helpers before compiling the template, once per application start is enough.

## Rendering the Template and PDF

How do we render this template and convert it to PDF?
We'll use [Handlebars.NET](https://github.com/Handlebars-Net/Handlebars.Net) to compile the template with data, then PuppeteerSharp to render it to PDF.

First, we read the template file and compile it with `Handlebars`:

```csharp {10,12}
var template = File.ReadAllText("Templates/InvoiceTemplate.html");
var data = new {
    customer = "Milan Jovanović",
    items = new[] {
        new { description = "Software License", price = 99 },
        new { description = "Support Plan", price = 49 }
    }
};

var compiledTemplate = Handlebars.Compile(template);

string html = compiledTemplate(data);
```

This gives us the final HTML with all placeholders replaced by actual data.

**Note**: You don't necessarily need to use Handlebars.
You can use any templating engine that suits your needs,
like [**Razor**](flexible-pdf-reporting-in-net-using-razor-views) or [Scriban](https://github.com/scriban/scriban).

Next, we need to convert this HTML to PDF using PuppeteerSharp.
We'll launch a headless browser, set the content to our HTML, and then generate the PDF.
Here's how we do it:

```csharp
// Ensure PuppeteerSharp has the browser binaries
var browserFetcher = new BrowserFetcher();
await browserFetcher.DownloadAsync(BrowserFetcher.DefaultChromiumRevision);

// Launch the browser and create a new page
using var browser = await Puppeteer.LaunchAsync(new LaunchOptions { Headless = true });
using var page = await browser.NewPageAsync();

// Set the content of the page to our compiled HTML
await page.SetContentAsync(html);

// Optional: wait for fonts to load if using custom fonts
await page.EvaluateExpressionHandleAsync("document.fonts.ready");

byte[] pdf = await page.PdfDataAsync(new PdfOptions {
    Format = PaperFormat.A4,
    PrintBackground = true,
    MarginOptions = new MarginOptions
    {
        Top = "50px",
        Right = "20px",
        Bottom = "50px",
        Left = "20px"
    }
});
```

This gives us a byte array containing the PDF data.
You can then save it to a file or return it from an API endpoint.

Here's a simple example of returning it from a Minimal API endpoint:

```csharp
return Results.File(pdf, "application/pdf", "invoice.pdf");
```

Here's what the document looks like when rendered:

<figure className="figure-center">
  <div className="bordered">
    <Image
      src="blogs/mnw_151/simple_template.png"
      width={1656}
      height={2342}
      alt="Simple PDF Template example rendered as PDF"
    />
  </div>
  <figcaption>
    This is a simple PDF template example with dynamic templated content.
  </figcaption>
</figure>

## Enhancements: Images, Header/Footer, Styling

What are some improvements we can make to this basic setup?

For example, you can add images to your template using the `<img>` tag.
A simple approach is to use a base64-encoded image directly in the HTML.
Note that we're passing the image data using the `LogoBase64` variable.

```html {2}
<img
  src="data:image/png;base64,{{LogoBase64}}"
  alt="Logo"
  style="height:50px; max-width:200px; object-fit:contain;"
/>
```

We can also render dynamic headers and footers using PuppeteerSharp's built-in support.
You can define these in the `PdfOptions` object when generating the PDF.
Here's an example:

```csharp {3,10,17}
var pdfOptions = new PdfOptions
{
    HeaderTemplate =
        @"""
        <div style='font-size: 14px; text-align: center; padding: 10px;'>
            <span style='margin-right: 20px;'><span class='title'></span></span>
            <span><span class='date'></span></span>
        </div>
        """,
    FooterTemplate =
        @"""
        <div style='font-size: 14px; text-align: center; padding: 10px;'>
            <span style='margin-right: 20px;'>Generated on <span class='date'></span></span>
            <span>Page <span class='pageNumber'></span> of <span class='totalPages'></span></span>
        </div>
        """,
    DisplayHeaderFooter = true
};
```

PuppeteerSharp uses CSS classes like `title`, `date`, `pageNumber`, and `totalPages` to inject dynamic values.
This could be different for some other libraries, so check the documentation.

Lastly, I want to mention that you can use CSS for advanced styling.
This can be inline in the HTML or in a separate CSS file.
You can also reference external stylesheets if needed, using the `<link>` tag.

Here's a complete example of a more complex template with images, headers, and footers:

```html
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Invoice #{{Number}}</title>
    <style>
      /* Omitted for brevity */
    </style>
  </head>
  <body>
    <div class="invoice-container">
      
      <div
        style="display: flex; justify-content: space-between; align-items: flex-start;"
      >
        <div>
          <h1 class="invoice-title">Invoice #{{Number}}</h1>
          <div class="invoice-dates">
            <p><strong>Issued:</strong> {{formatDate IssuedDate}}</p>
            <p><strong>Due:</strong> {{formatDate DueDate}}</p>
          </div>
        </div>
        <div>
          {{#if LogoBase64}}
          <img
            src="data:image/png;base64,{{LogoBase64}}"
            alt="Logo"
            style="height:50px; max-width:200px; object-fit:contain;"
          />
          {{/if}}
        </div>
      </div>
      <hr
        style="margin: 20px 0; border: none; border-top: 1px solid #e9ecef;"
      />

      
      <div class="addresses">
        
        <div class="address-box">
          <h3 class="address-title">From:</h3>
          <div class="address-content">
            <p class="company-name">{{SellerAddress.CompanyName}}</p>
            <p>{{SellerAddress.Street}}</p>
            <p>{{SellerAddress.City}}, {{SellerAddress.State}}</p>
            <p class="email">{{SellerAddress.Email}}</p>
          </div>
        </div>

        
        <div class="address-box">
          <h3 class="address-title">Bill To:</h3>
          <div class="address-content">
            <p class="company-name">{{CustomerAddress.CompanyName}}</p>
            <p>{{CustomerAddress.Street}}</p>
            <p>{{CustomerAddress.City}}, {{CustomerAddress.State}}</p>
            <p class="email">{{CustomerAddress.Email}}</p>
          </div>
        </div>
      </div>

      
      <div class="items-section">
        <h2 class="items-title">Items</h2>
        <table class="items-table">
          <thead>
            <tr>
              <th>#</th>
              <th>Description</th>
              <th>Price</th>
              <th>Qty</th>
              <th>Total</th>
            </tr>
          </thead>
          <tbody>
            {{#each LineItems}}
            <tr>
              <td>{{@index}}</td>
              <td>{{Name}}</td>
              <td>{{formatCurrency Price}}</td>
              <td>{{formatNumber Quantity}}</td>
              <td>{{formatCurrency (multiply Price Quantity)}}</td>
            </tr>
            {{/each}}
          </tbody>
        </table>
      </div>

      
      <div class="totals">
        <div class="totals-container">
          <div class="totals-row subtotal">
            <span>Subtotal:</span>
            <span>{{formatCurrency Subtotal}}</span>
          </div>
          <div class="totals-row">
            <span>Tax:</span>
            <span>{{formatCurrency 0}}</span>
          </div>
          <div class="totals-row total">
            <span>Total:</span>
            <span>{{formatCurrency Total}}</span>
          </div>
        </div>
      </div>
    </div>
  </body>
</html>
```

And the rendered PDF looks like this:

<figure className="figure-center">
  <div className="bordered">
    <Image
      src="blogs/mnw_151/complex_template.png"
      width={1656}
      height={2342}
      alt="Complex PDF Template example rendered as PDF with images, headers, and footers"
    />
  </div>
  <figcaption>
    This is a complex PDF template example with CSS stylization, tables, images,
    headers, and footers.
  </figcaption>
</figure>

## Downloading Binaries at Application Start

Here's a small tip: PuppeteerSharp requires the Chromium browser binaries to be downloaded at runtime.
You can do this by calling `BrowserFetcher.DownloadAsync()` before launching the browser.
This ensures the required browser version is available when you run your application.

A simple way to do this is to add it to your application startup code or a background service:

```csharp
public class BrowserSetupService : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var browserFetcher = new BrowserFetcher();
        await browserFetcher.DownloadAsync();
    }
}
```

Then register this service in your `Program.cs`:

```csharp
builder.Services.AddHostedService<BrowserSetupService>();
```

## Performance Considerations

Let's talk about performance.
How fast is this approach and can you use it at scale?

The first thing to consider is the use a headless browser like Chromium.
This can be slower than native PDF libraries, especially for large documents or high concurrency.
It also adds **overhead at runtime** since the browser binaries need to be **downloaded** and **launched**.

You should definitely consider moving this out of your main application.
You can use a background service or a separate microservice to handle PDF generation.
Event a cloud function can be a good fit if you need to scale.

But as with anything performance-related, it depends on your specific use case.
So measure and profile your application to see if this approach meets your needs.

Here are some benchmarks I ran on a sample invoice template.
It's nothing scientific, but it gives you an idea of the performance.
I didn't test this with concurrent requests, but rather just the time it takes to generate a single PDF.

**Cold Start**: ~12s spent downloading + launching Chromium

**Warm Run**: ~580ms

- Template + HTML generation: ~13ms
- Browser reuse + rendering: ~550ms

## Summary

HTML + PuppeteerSharp is one of the most pragmatic approaches for PDF reporting in .NET.

It lets you:

- Design pixel-perfect layouts using familiar web technologies
- Inject dynamic data cleanly with Handlebars.NET
- Output high-quality PDFs with full styling, tables, and images

And all of this without relying on commercial libraries.

I've also written about [**PDF generation**](how-to-easily-create-pdf-documents-in-aspnetcore) in the past,
with libraries like [QuestPdf](https://www.questpdf.com/) or [IronPdf](https://ironpdf.com/).
You can take a look at those if you want to compare approaches.

The cold start can be expensive, but once warmed up, rendering is fast and reliable.
You get total layout control, CSS styling, and even dynamic headers and footers with page numbers and timestamps.

If you're building internal dashboards, invoice generators, or export endpoints, this approach delivers excellent value.

If you need pixel-perfect PDF reports in .NET and want full design control,
combining Handlebars.NET with PuppeteerSharp is a powerful approach.

You'll trade some performance and setup cost for flexibility, but for most internal tools, dashboards, or customer-facing reports, it's worth it.

---


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

---


Previous issues of The .NET Weekly