Sponsor this newsletter to reach 10,000+ readers →

A request coming into an ASP .NET Core app doesn’t go straight to your controller. It passes through a stack of components first, things like auth, CORS, rate limiting, and exception handling. That stack is the middleware pipeline.

Each middleware sits in line, does its job, then either hands off to the next one or stops the request right there. That’s really it. Nest a few of these together, and you’ve got a pipeline.

A typical API pipeline might look like this:

Request
  ↓
Exception Handling
  ↓
HTTPS Redirection
  ↓
Routing
  ↓
CORS
  ↓
Authentication
  ↓
Authorization
  ↓
Endpoint
  ↓
Response

The response travels back through in reverse order:

Request
  ↓
Middleware A
  ↓
Middleware B
  ↓
Middleware C
  ↓
Endpoint
  ↑
Middleware C
  ↑
Middleware B
  ↑
Middleware A
  ↑
Response

That reverse trip is why middleware works so well for request timing, logging, and headers- anything that needs to wrap the whole request.

Types of Middleware: Built-in and Custom

Every middleware in your pipeline falls into one of two buckets: the ones ASP.NET Core ships for you, and the ones you write yourself.

Built-in middleware

ASP.NET Core ships middleware for most of the cross-cutting concerns you’ll actually need: exception handling, HTTPS redirection, static files, routing, CORS, authentication, authorization, rate limiting, response compression. I’ve covered several of these individually: built-in middleware, CORS, rate limiting, response compression, and global exception handling. Reach for these first; don’t hand-roll something the framework already gives you.

Custom middleware

Once you need logic specific to your own app- a header check, a tenant lookup, something tied to your domain- you write it yourself. There are three ways to do that.

1. Request delegate (inline)

The simplest option. Written directly in Program.cs with app.Use.

app.Use(async (context, next) =>
{
    // logic before the next middleware

    await next(context);

    // logic after the next middleware
});

Skip the next call if you don’t want the pipeline to continue.

2. By convention

A dedicated class. ASP.NET Core recognizes it through its constructor and an Invoke or InvokeAsync method; no interface required.

public class RequestTimingMiddleware
{
    private readonly RequestDelegate _next;

    public RequestTimingMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // logic before the next middleware

        await _next(context);

        // logic after the next middleware
    }
}

Registered in Program.cs:

app.UseMiddleware<RequestTimingMiddleware>();

3. Using a factory (IMiddleware)

Same idea, but the class implements IMiddleware and is activated through DI instead of by convention.

public class RequestTimingMiddleware : IMiddleware
{
    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        // logic before the next middleware

        await next(context);

        // logic after the next middleware
    }
}

Register the class in DI, then wire it into the pipeline the same way as before:

builder.Services.AddTransient<RequestTimingMiddleware>();
app.UseMiddleware<RequestTimingMiddleware>

Worth the extra step when your middleware needs scoped dependencies; factory-based activation plays nicer with the container than convention-based middleware does. For most day-to-day cases, though, convention-based is enough.

The Most Important Part: Calling the Next Middleware

Consider this small middleware:

app.Use(async (context, next) =>
{
    Console.WriteLine("Before");

    await next(context);

    Console.WriteLine("After");
});

The important line is await next(context);. It passes control to the next component. When the rest of the pipeline finishes, execution comes back to the line right after it.

With two middleware components, the order looks like this:

Middleware 1 - Before
Middleware 2 - Before

Endpoint Executes

Middleware 2 - After
Middleware 1 - After

Think of middleware as nested layers, not a one-way list. That mental model makes the whole pipeline click.

Use vs Run vs Map

You’ll see these three constantly while configuring an app. They solve different problems.

Use

Use adds middleware that can continue to the next component.

app.Use(async (context, next) =>
{
    // Before downstream middleware

    await next(context);

    // After downstream middleware
});

Typical examples: request logging, correlation IDs, request timing, authentication, authorization, CORS, rate limiting, security headers. Anything where you want to do something around the request and then let it continue.

Run

Run adds terminal middleware. There’s no next delegate because processing ends here.

app.Run(async context =>
{
    await context.Response.WriteAsync("Request handled.");
});

Useful for a simple terminal response, maintenance mode, a fallback handler, or the end of a custom pipeline branch. Anything registered after it won’t run for requests that reach it, so use it deliberately.

Map

Map creates a separate pipeline based on the request path.

/api/*
    → API pipeline
    → API endpoints

/admin/*
    → Admin-specific middleware
    → Admin endpoints

Handy when one part of your app needs different processing: admin routes, API vs non-API, legacy sections, tenant-specific branches. One gotcha: Map strips the matched segment off Request.Path and moves it into Request.PathBase, so code inside the branch reading Request.Path sees it without that prefix.

Conditional Middleware: UseWhen vs MapWhen vs Map

Map only branches on path, and once a request goes down that branch, it never comes back to the main pipeline. Sometimes that’s too blunt. You want a middleware to apply only under some condition, without splitting your whole app into separate pipelines.

That’s what UseWhen and MapWhen are for, and they’re not interchangeable with each other either.

UseWhen: branches on any condition, and rejoins the main pipeline afterward as long as nothing inside the branch short-circuits.

app.UseWhen(
    context => context.Request.Path.StartsWithSegments("/api/user"),
    branch => branch.UseMiddleware<YourMiddlewareName>()
);

app.UseAuthorization();
app.MapControllers();

Requests to /api/user/* pick up YourMiddlewareName on the way through, then continue on to authorization and the controllers exactly like every other request. Nothing else about the pipeline changes for them.

MapWhen branches on any condition too, but behaves like Map, the branch does not rejoin.

app.MapWhen(
    context => context.Request.Headers.ContainsKey("X-Beta-User"),
    betaApp =>
    {
        betaApp.UseMiddleware<BetaFeatureMiddleware>();

        betaApp.Run(async context =>
        {
            await context.Response.WriteAsync("Beta experience");
        });
    });

Two questions settle which one you need. Does the branch need to rejoin the main pipeline, or is it a dead end. And are you branching on the path, or on something else entirely: a header, a query string, the user’s claims. Map and MapWhen are dead ends and only Map is path-only. UseWhen rejoins and can check anything.

What Should Middleware Handle?

Middleware is built for cross-cutting concerns tied to the HTTP request itself. Say you want to time every request. Adding that logic to every controller duplicates infrastructure code across the app. Middleware gives you one place to do it once.

Good candidates: global exception handling, request/response logging, correlation IDs, authentication, authorization, CORS, rate limiting, request timing, security headers, response compression.

Ask yourself whether the concern applies to the HTTP request as a whole. If it does, middleware’s usually the right starting point. ASP.NET Core already ships middleware for most of these (see the built-in middleware section above), so don’t rebuild what’s already there.

Middleware Order Matters

Middleware runs in the order you register it.

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

Authentication figures out who the user is. Authorization decides whether that user can access what they’re asking for. Flip those two, and you get broken behavior that looks like a completely unrelated bug.

A simplified pipeline:

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/error");
    app.UseHsts();
}

app.UseHttpsRedirection();

app.UseRouting();

app.UseCors();

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

app.UseRateLimiter();

app.MapControllers();

Don’t copy this into every project blindly. The right order depends on what middleware you’re actually using. What matters is the relationships: exception handling needs to sit early enough to catch what’s downstream, authentication comes before authorization, CORS has to run at the right point for the endpoints it covers, and anything that short-circuits blocks everything registered after it.

Order isn’t a formality here. Get auth and authorization backwards, and you’ll spend an hour debugging something that was never really a bug.

What Is Short-Circuiting?

A middleware doesn’t have to call the next component. Say your app requires a specific header:

app.Use(async (context, next) =>
{
    if (!context.Request.Headers.ContainsKey("X-API-Key"))
    {
        context.Response.StatusCode =
            StatusCodes.Status401Unauthorized;

        await context.Response.WriteAsync(
            "API key is missing.");

        return;
    }

    await next(context);
});

Missing header, response goes out immediately, nothing later in the pipeline runs. That’s short-circuiting. Useful for rate-limit rejection, maintenance mode, invalid requests, cached responses, security checks.

Watch out when writing custom middleware, though. Forgetting to call next when you meant to continue makes everything after it look broken for no obvious reason.

Middleware vs Filters: Which One Should You Use?

Both can wrap logic around something else, so they get confused a lot. The difference is where that logic runs.

Middleware only sees the HttpContext; it has no idea which controller or action got picked. Filters run after that decision’s already been made, so they’re the right call once you need the action’s arguments or its result.

Correlation IDs, request logging, global exception handling: middleware. Inspecting an action’s arguments or modifying its result: filter. A client IP restriction could go either way; I showed both approaches in my piece on client IP safelisting in ASP.NET Core.

Summary

• Order isn’t cosmetic; get auth and authorization backwards, and the bug won’t look like an order problem

• Short-circuit when finishing the pipeline would be wasted work

• Middleware for anything that only needs HttpContext; filters once you need the action itself

Whenever you’re ready, there are 2 ways I can help you:

1. I work with founders and growing businesses to design, build, and improve reliable web apps. Let’s talk →

2. Promote yourself to 10,000+ subscribers by sponsoring this newsletter →

3. Boost your .NET skills by subscribing to my YouTube Channel →

Sponsor this newsletter to reach 10,000+ readers →

Most developers create a new Web API and immediately start writing controllers, entities, and endpoints. I got an email from Hostinger last month. 97% of my monthly bandwidth used; 5 days left in the billing cycle. Upgrade or get throttled.

For my PakExam SaaS, I’m running a Hostinger KVM2:

• 2 vCPU cores

• 8 GB RAM

• 100 GB NVMe disk space

• 8 TB bandwidth

PakExam is built for students preparing for exams, and every time they download a past paper or a resource, that’s bandwidth. Last month I nearly ran out of the 8 TB, and the “solution” Hostinger pushes on you is simple: upgrade to KVM4.

I’d already been thinking about moving off Hostinger after 6 months there. Nothing wrong with them, but for a SaaS that hasn’t even turned subscriptions on yet, I don’t want to lock myself into a bigger, costlier plan just to fix one thing. KVM2 cost me $101.88 the first year and renews at $200 for the second. I didn’t check that going in. Lesson learned: always check the renewal price, not just the first-year offer, because by the time it kicks in you’re already dependent on the setup and switching feels like a bigger job than it should.

So before paying for a bigger VPS, I wanted to know what was actually eating the bandwidth.

What was actually eating my bandwidth?

I was running MinIO, the open-source S3-compatible storage server, deployed directly on my VPS. Every past paper PDF, every image, every audio (my dictionary feature provides English-to-Urdu translation) file the app served was going through that same box and the same bandwidth allowance as everything else.

Storage traffic was the biggest chunk of it. Students downloading papers all day, every day, all counted against the same 8 TB as my API and my site.

Once I saw that, the fix wasn’t “buy a bigger server.” It was “stop making my server serve files.”

Why Cloudflare R2

I’d heard about R2 before but never had a real reason to move. Cloudflare’s free tier for R2 is generous:

• 10 GB-month of standard storage

• 1 million Class A operations (writes, lists)

• 10 million Class B operations (reads)

• Completely free egress, no matter how much data goes out

That last point is the whole reason this made sense for me. Egress is exactly what was costing me bandwidth on Hostinger, and R2 doesn’t charge for it at all.

The other advantage: MinIO and R2 are both S3-compatible. My whole setup was already speaking that protocol, so this wasn’t a rewrite; it was a swap.

How I moved the data

Here’s how I moved everything over:

1. Installed rclone on the server. Since both MinIO and R2 speak S3, this one tool could talk to both.

2. Grabbed my R2 credentials from the Cloudflare dashboard: an Access Key ID and Secret Access Key scoped to Object Read & Write.

3. Created matching buckets on R2 first, same names as my MinIO buckets, so nothing in my app code would need to change beyond the endpoint.

4. Set up two rclone remotes, one pointing at MinIO (source) and one at R2 (destination), using the same S3 provider type for both.

5. Ran a dry run on each bucket before touching anything real, just to see file counts and sizes and catch surprises early.

6. Copied bucket by bucket with rclone, checking progress live as it transferred.

7. Verified everything with rclone check on each bucket to confirm the file counts and checksums matched between MinIO and R2.

Once every bucket checked out clean, I swapped my app’s storage config over to R2 and kept MinIO around for a few days as a safety net before shutting it down for good.

What changed in the code

The config side got a new section for R2 alongside the existing MinIO one, with a switch to pick which provider is active:

"MinIOStorage": {
  "Endpoint": "yourendpoint.yourdomain.com",
  "UseSSL": true,
  "DefaultBucket": "defaultBucketName"
},
"CloudflareR2Storage": {
  "AccountId": "accountId",
  "Region": "auto/regionName",
  "DefaultBucket": "defaultBucketName"
},
"Storage": {
  "BaseUrl": "baseURL",
  "ActiveProvider": "CloudflareR2"
}

Under the hood, I built a new storage service for R2 and wired it into the same storage abstraction the rest of the app already uses. Since every part of the codebase that reads or writes a file goes through that interface, not a concrete MinIO class, none of those call sites needed to change. Only the DI registration and the new service itself did.

That new service and the DI setup around it deserves its own walkthrough, so I’ll cover the actual implementation in a separate article.

This isn’t the first infrastructure decision I’ve made for PakExam as a solo dev. I wrote a bit ago about why I went with a monorepo for the whole project; similar reasoning there: fewer moving parts, less to manage alone.

Summary

• MinIO on my own VPS meant every file download counted against my server’s bandwidth allowance.

• R2’s free egress moved that cost to $0, without giving up S3 compatibility.

• rclone made the actual data migration a copy-and-verify job.

• A new storage service implementing the existing abstraction meant switching providers was a config change plus one new service, not a rewrite of the app.

Whenever you’re ready, there are 2 ways I can help you:

1. I work with founders and growing businesses to design, build, and improve reliable web apps. Let's talk →

2. Promote yourself to 10,000+ subscribers by sponsoring this newsletter →

3. Boost your .NET skills by subscribing to my YouTube Channel →

Sponsor this newsletter

Most developers create a new Web API and immediately start writing controllers, entities, and endpoints.

That works until the project grows.

Then formatting becomes inconsistent, NuGet versions start drifting, and your AI coding assistant keeps making decisions that do not match your architecture.

Before writing the first endpoint, I recommend setting up these three things:

1. .editorconfig

2. Central NuGet Package Management

3. CLAUDE.md

They take a few minutes to configure and save hours of cleanup later.

1. Add an .editorconfig File

The .editorconfig file defines how code should look across the entire solution.

It can control:

• Indentation and spacing

• File-scoped namespaces

• Brace placement

• Use of var

• Naming conventions

• Unused imports

• Code-analysis severity

• Special rules for migrations and tests

For example:

root = true

[*.cs]

indent_size = 4
indent_style = space

csharp_style_namespace_declarations = file_scoped
dotnet_style_readonly_field = true
dotnet_diagnostic.IDE0005.severity = warning

Without an.editorconfig, every developer’s IDE can format code differently.

One person uses var. Another writes explicit types. One removes braces. Another adds them back.

Soon, your pull requests contain more formatting changes than actual business logic.

A shared .editorconfig gives the whole team one coding standard. Your existing configuration can also enforce interface naming, PascalCase members, analyzer rules, migration exclusions, and test-specific exceptions.

The goal is simple:

Stop debating formatting during code reviews.

Let the configuration handle it.

2. Enable Central NuGet Package Management

In a solution with multiple projects, package versions can quickly become inconsistent.

Your API project might use one version of Entity Framework Core while your Persistence project uses another.

That is how strange restore errors and dependency conflicts begin.

Create a Directory.Packages.props file at the solution root:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>

    <CentralPackageTransitivePinningEnabled>
      true
    </CentralPackageTransitivePinningEnabled>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion
      Include="Microsoft.EntityFrameworkCore"
      Version="9.0.4" />

    <PackageVersion
      Include="Npgsql.EntityFrameworkCore.PostgreSQL"
      Version="9.0.4" />

    <PackageVersion
      Include="Serilog.AspNetCore"
      Version="9.0.0" />

    <PackageVersion
      Include="OpenTelemetry.Extensions.Hosting"
      Version="1.15.3" />
  </ItemGroup>
</Project>

Your individual project files can then reference packages without specifying versions:

<ItemGroup>
  <PackageReference Include="Microsoft.EntityFrameworkCore" />
  <PackageReference Include="Serilog.AspNetCore" />
</ItemGroup>

Now every project gets its package versions from one place.

This gives you:

• One place to update packages

• Consistent versions across projects

• Easier security upgrades

• Fewer dependency conflicts

• Cleaner .csproj files

CentralPackageTransitivePinningEnabled also lets NuGet promote and pin a transitive dependency when a centrally defined version needs to be enforced.

You can combine this with a Directory.Build.props file for solution-wide settings:

<Project>
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>

    <Nullable>enable</Nullable>

    <ImplicitUsings>enable</ImplicitUsings>

    <AnalysisLevel>latest</AnalysisLevel>

    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>

    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
  </PropertyGroup>
</Project>

A good rule is:

Package versions belong in Directory.Packages.props. Shared build rules belong in Directory.Build.props.

Also, do not copy a hundred packages into a new project just because you might need them someday.

Add packages when the project actually needs them. NuGet packages are dependencies, not Pokémon.

3. Create a CLAUDE.md File

If you use Claude Code or another AI coding assistant, create a CLAUDE.md file at the repository root.

This file acts as the project’s instruction manual.

It should explain:

• What the application does

• Which technologies it uses

• How the solution is structured

• Where new features should go

• Which commands should be used

• How migrations should be created

• How tests should be organized

• Which architectural rules must never be broken

• Which actions require explicit approval

For example:

# Project Guidelines

This project is a .NET 9 Web API using Clean Architecture,
EF Core, PostgreSQL, Wolverine, and OpenTelemetry.

## Architecture

- Domain contains entities and domain events.
- Application contains business logic and abstractions.
- Persistence contains EF Core and service implementations.
- Infrastructure contains external integrations.
- API contains controllers and dependency injection.

## Important Rules

- Never use DbContext directly in the Application layer.
- Never create EF Core migrations manually.
- Every new feature must include tests.
- Never run git push unless explicitly requested.
- Use fluent LINQ syntax instead of query syntax.

Without project instructions, the AI has to guess.

It may place database code inside the Application layer, create migrations manually, skip tests, introduce a different folder structure, or push code when you only asked it to make a local change.

A detailed CLAUDE.md can document commands, architecture, feature workflows, security rules, testing expectations, deployment constraints, and even instructions such as never running git push without permission.

The AI does not know your unwritten rules.

Write them down once, and you will not need to repeat them in every prompt.

My Recommended Setup Order

When starting a new Web API, I now follow this order:

1. Create the solution and projects.

2. Add .editorconfig.

3. Add Directory.Build.props.

4. Add Directory.Packages.props.

5. Add CLAUDE.md.

6. Configure analyzers and warnings.

7. Run dotnet build.

8. Only then start building features.

These files are not exciting.

They will not appear in your product demo, and your client will never ask about them.

But they create the foundation for consistent code, predictable builds, controlled dependencies, and safer AI-assisted development.

A clean project does not begin with the first controller.

It begins with the rules that every controller must follow.

Whenever you’re ready, there are 2 ways I can help you:

1. Boost your .NET skills by subscribing to my YouTube Channel

2. Promote yourself to 10,000+ subscribers by sponsoring this newsletter

Someone starts signing up on your app. They enter their email, hit “Register,” and then... never open the OTP email.

They’re gone. But their row isn’t.

Six months later your users table has 40,000 rows and only 22,000 are real. Your signup conversion metric is lying to you. And worse, that abandoned email is sitting in a unique column, so the actual person can never register with it again.

Here’s how to stop that from happening.

The Naive Way

Most registration flows look like this:

app.MapPost("/register", async (RegisterRequest request, AppDbContext db) =>
{
    var user = new User
    {
        Id = Guid.NewGuid(),
        Email = request.Email,
        PasswordHash = Hasher.Hash(request.Password),
        CreatedAtUtc = DateTime.UtcNow
    };

    db.Users.Add(user);

    await db.SaveChangesAsync();

    await otpService.SendOtpAsync(user.Email);

    return Results.Ok("Check your email for the OTP.");
});

This works fine on day one. The problem shows up over time:

• The row is indistinguishable from a real, verified user. Nothing marks it as incomplete.

• Email is unique, so if this person abandons the flow, nobody, including them, can ever register with that email again.

• Your table grows forever with rows that never convert.

• Every dashboard counting “total users” or “signups today” is quietly wrong.

There’s no cleanup mechanism here at all. That’s the gap we need to close.

Why This Happens

A registration and an OTP verification are really two separate events, but this code treats them as one. The row gets created as if the user already exists, before they’ve proven they own that email.

The fix is to stop treating “registered” and “verified” as the same thing. A user isn’t a user until they’ve confirmed the OTP. Until then, they’re a pending row with an expiry date.

Once you model it that way, cleanup becomes a scheduled job instead of a manual database chore.

There are two solid ways to structure this:

Option 1: one table, a status column. The user row is inserted as Pending, flipped to Active on OTP verification, and hard-deleted by a background job if it never gets there. One table, no migration logic between states.

Option 2: two tables. Unverified signups live in pending_users. On successful OTP verification, the row moves into users. Your main table never has a status flag or a ghost row in it, every query against users is guaranteed clean.

For a fast-moving SaaS, option 1 is the pragmatic default. It’s what I run in production. Option 2 earns its keep once users gets queried constantly across many services and you don’t want every one of them filtering by status. I’ll implement option 1 in full below, since that’s what most teams need first.

Step 1: Add a Status to the User

Supposing we already have the User entity:

public class User
{
    public Guid Id { get; set; }
    public string Email { get; set; } = default!;
    public string PasswordHash { get; set; } = default!;
    public DateTime CreatedAtUtc { get; set; }
    public string? OtpCode { get; set; }
    public DateTime? OtpExpiresAtUtc { get; set; }
}

Introduce a user status enum:

public enum UserStatus
{
    Pending,
    Active
}

Update the user entity now:

public class User
{
    public Guid Id { get; set; }
    public string Email { get; set; } = default!;
    public string PasswordHash { get; set; } = default!;
    public UserStatus Status { get; set; } = UserStatus.Pending;
    public DateTime CreatedAtUtc { get; set; }
    public string? OtpCode { get; set; }
    public DateTime? OtpExpiresAtUtc { get; set; }
}

Every user starts life as Pending. Nothing is “active” until it’s proven.

If you’re validating RegisterRequest with data annotations, Data Annotations in C# covers the attributes worth reaching for on a request DTO like this or if you are fan of FluentValidation then check FluentValidation in .NET

Step 2: Insert as Pending, Generate the OTP

Two things need to change from the naive version above: the insert has to carry OTP data, and the email has to carry the OTP itself. Start with generating the value:

var otp = otpService.GenerateOtp();

That value now needs to land on the user row, along with an explicit Pending status and an expiry:

Status = UserStatus.Pending,
CreatedAtUtc = DateTime.UtcNow,
OtpCode = otp,
OtpExpiresAtUtc = DateTime.UtcNow.AddMinutes(10)

Full endpoint with both pieces wired in:

app.MapPost("/register", async (RegisterRequest request, AppDbContext db, IOtpService otpService) =>
{
    var otp = otpService.GenerateOtp();

    var user = new User
    {
        Id = Guid.NewGuid(),
        Email = request.Email,
        PasswordHash = Hasher.Hash(request.Password),
        Status = UserStatus.Pending,
        CreatedAtUtc = DateTime.UtcNow,
        OtpCode = otp,
        OtpExpiresAtUtc = DateTime.UtcNow.AddMinutes(10)
    };

    db.Users.Add(user);
    await db.SaveChangesAsync();

    await otpService.SendOtpAsync(user.Email, otp);

    return Results.Ok("Check your email for the OTP.");
});

Same insert as before, but now the row is honest about what it is. Nothing downstream should treat this user as real until Status flips.

Step 3: Flip to Active on Verification

First, find the pending user by email and make sure one exists:

var user = await db.Users
    .FirstOrDefaultAsync(u => u.Email == request.Email && u.Status == UserStatus.Pending);

if (user is null)
    return Results.NotFound("No pending registration found for this email.");

Then check the OTP itself before touching anything:

if (user.OtpCode != request.OtpCode || user.OtpExpiresAtUtc < DateTime.UtcNow)
    return Results.BadRequest("Invalid or expired OTP.");

Once both checks pass, flip the status and clear the OTP fields so they can’t be reused:

user.Status = UserStatus.Active;
user.OtpCode = null;
user.OtpExpiresAtUtc = null;

await db.SaveChangesAsync();

return Results.Ok("Account verified.");

Full endpoint:

app.MapPost("/verify-otp", async (VerifyOtpRequest request, AppDbContext db) =>
{
    var user = await db.Users
        .FirstOrDefaultAsync(u => u.Email == request.Email && u.Status == UserStatus.Pending);

    if (user is null)
        return Results.NotFound("No pending registration found for this email.");

    if (user.OtpCode != request.OtpCode || user.OtpExpiresAtUtc < DateTime.UtcNow)
        return Results.BadRequest("Invalid or expired OTP.");

    user.Status = UserStatus.Active;
    user.OtpCode = null;
    user.OtpExpiresAtUtc = null;

    await db.SaveChangesAsync();

    return Results.Ok("Account verified.");
});

This is the only place a user ever becomes Active. If you’re routing this through a mediator instead of a minimal API endpoint, the handler slots in the same way I described in Wolverine as Mediator in .NET, same logic, just invoked through IMessageBus instead of MapPost.

Step 4: Index the Pending Rows

Your cleanup job is going to scan for Pending rows on every run. Without an index, that’s a full table scan as your users table grows.

A partial index, one that only covers Pending rows, keeps that scan cheap without bloating the index for your (much larger) set of active users:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<User>()
        .HasIndex(u => u.CreatedAtUtc)
        .HasFilter("\"Status\" = 0") // 0 = Pending
        .HasDatabaseName("IX_Users_Pending_CreatedAt");
}

Status = 0 matches UserStatus.Pending, since EF Core stores enums as integers by default. Active users, the vast majority of your table over time, never touch this index.

Step 5: Sweep the Ghosts with Quartz

I already covered the basics of wiring Quartz.NET into a .NET app back in Episode 3: Schedule Jobs with Quartz.NET. This is that same scheduler pointed at a much narrower job.

public class GhostUserCleanupJob : IJob
{
    private readonly AppDbContext _db;
    private readonly ILogger<GhostUserCleanupJob> _logger;

    public GhostUserCleanupJob(AppDbContext db, ILogger<GhostUserCleanupJob> logger)
    {
        _db = db;
        _logger = logger;
    }

    public async Task Execute(IJobExecutionContext context)
    {
        var cutoff = DateTime.UtcNow.AddMinutes(-30);

        var ghosts = await _db.Users
            .Where(u => u.Status == UserStatus.Pending && u.CreatedAtUtc < cutoff)
            .ToListAsync();

        if (ghosts.Count == 0)
            return;

        _db.Users.RemoveRange(ghosts);
        await _db.SaveChangesAsync();

        _logger.LogInformation("Deleted {Count} ghost users older than {Cutoff}", ghosts.Count, cutoff);
    }
}

Register it and give it a schedule:

builder.Services.AddQuartz(q =>
{
    var jobKey = new JobKey("GhostUserCleanupJob");

    q.AddJob<GhostUserCleanupJob>(opts => opts.WithIdentity(jobKey));

    q.AddTrigger(opts => opts
        .ForJob(jobKey)
        .WithIdentity("GhostUserCleanupJob-trigger")
        .WithSimpleSchedule(s => s
            .WithIntervalInMinutes(15)
            .RepeatForever()));
});

builder.Services.AddQuartzHostedService(q => q.WaitForJobsToComplete = true);

Every 15 minutes, this job deletes anyone who registered more than 30 minutes ago and never verified. Adjust the window to whatever fits your product: 30 minutes if OTP abandonment should be punished quickly, 30 days if you want a longer window before wiping people out. Google takes the long-window approach, deleting inactive accounts after two years of no activity. The principle scales, only the clock changes.

When Two Tables Is the Better Call

If users gets hit by dozens of queries across multiple services, a status flag becomes a tax every one of those queries has to pay, either by filtering on Status = Active explicitly, or by risking a ghost row leaking into a report.

Option 2 avoids that entirely:

// On successful OTP verification:
var pending = await db.PendingUsers.FirstAsync(p => p.Email == request.Email);

var user = new User
{
    Id = Guid.NewGuid(),
    Email = pending.Email,
    PasswordHash = pending.PasswordHash,
    CreatedAtUtc = DateTime.UtcNow
};

db.Users.Add(user);
db.PendingUsers.Remove(pending);

await db.SaveChangesAsync();

users never has a Pending row in it, ever. The trade-off is that verification now touches two tables in one transaction instead of flipping a column. For most teams starting out, that extra complexity isn’t worth paying for yet. Reach for it when your users table is under enough query pressure that “just filter by status” stops being a satisfying answer.

Bonus: What I’d Improve With More Time

Stepping back from the tutorial for a second, here’s what I’d tighten up before this went anywhere near a real production system:

• Decouple OTP sending from user creation with a domain event. Fire something like a UserRegisteredEvent inside the same transaction that inserts the pending user, and let a separate handler call the OTP provider. A slow or failing email or SMS provider should never be able to block or roll back the write that creates the row.

• Give that event real delivery guarantees. Wrapping it in the outbox pattern (I walked through this in The Outbox Pattern in .NET) means a network blip on the OTP provider doesn’t lose the message, it just gets picked up and retried on the next processor run.

• Rate limit /register and /verify-otp. Nothing in this walkthrough stops someone from hitting either endpoint repeatedly with the same email, generating a fresh OTP every few seconds or brute-forcing the code. Both routes need a rate limiter keyed on email or IP before this ships.

• Make the cleanup job safe to run on more than one instance. If this ever scales out, two schedulers can grab the same batch of ghost rows at once. A claim-then-delete pattern using SELECT ... FOR UPDATE SKIP LOCKED, the same trick from the outbox processor, avoids double-processing.

Summary

• Don’t insert a user as if they’re real before they’ve verified their OTP, model it as Pending first.

• A partial index on the pending rows keeps your cleanup job’s scan cheap as the table grows.

• A Quartz job on a schedule hard-deletes anyone who never verified within your chosen window.

• Two tables is the right call once your users table is under heavy query load from multiple services, not before.

One status column. One background job. Zero ghosts.

Whenever you’re ready, there are 2 ways I can help you:

1. Boost your .NET skills by subscribing to my YouTube Channel

2. Promote yourself to 10,000+ subscribers by sponsoring this newsletter

Sponsor this newsletter

EF Core interceptors let you hook into database operations automatically, eliminating repetitive infrastructure logic across every handler. Instead of writing the same soft delete, audit trail, or outbox logic in dozens of places, you write it once and EF Core runs it on every operation.

Every time you save data, something else needs to happen.

A deleted record should not actually delete.

A created record should log who made it.

A domain event should land in the outbox table.

So you write that logic. In one handler. Then another. Then ten more.

Until one day you forget. And the bug is silent.

This is the problem interceptors solve.

If you have read my previous issue on Built-in Middleware in ASP.NET Core, you already understand the idea of hooking into a pipeline. Interceptors are the same concept, but for your DbContext.

What is an Interceptor?

EF Core interceptors let you hook into database operations before or after they happen.

Instead of repeating cross-cutting logic in every handler, you register it once and EF Core runs it automatically on every operation.

Think of it as middleware for your database context. Every time SaveChangesAsync runs, your interceptor gets called first. You inspect what’s about to be saved, modify it if needed, then let the operation continue.

This turns scattered infrastructure code into a single, centralized implementation.

Example 1: Soft Delete

The Pain

Here is what soft delete looks like without interceptors:

public async Task Handle(DeleteBlogCommand command, CancellationToken ct)
{
    var blog = await context.Blogs.FindAsync(command.Id);

    blog.IsDeleted = true;
    blog.DeletedAt = DateTime.UtcNow;

    await context.SaveChangesAsync(ct);
}

Fine for one handler. But now you have users, comments, posts, categories. All need the same logic.

public async Task Handle(DeleteUserCommand command, CancellationToken ct)
{
    var user = await context.Users.FindAsync(command.Id);

    user.IsDeleted = true;
    user.DeletedAt = DateTime.UtcNow;

    await context.SaveChangesAsync(ct);
}

public async Task Handle(DeleteCommentCommand command, CancellationToken ct)
{
    var comment = await context.Comments.FindAsync(command.Id);

    comment.IsDeleted = true;
    comment.DeletedAt = DateTime.UtcNow;

    await context.SaveChangesAsync(ct);
}

You will forget one. Or a junior developer will call context.Remove() and bypass it entirely.

Now let us fix this properly.

The Fix

Interceptors solve this by hooking into SaveChangesAsync before any data touches the database. When EF Core detects a deleted entity, the interceptor changes the operation from delete to update and sets the soft delete flags automatically.

Create a class that extends SaveChangesInterceptor:

public class SoftDeleteInterceptor : SaveChangesInterceptor
{
    public override ValueTask> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult result,
        CancellationToken ct = default)
    {
        if (eventData.Context is null)
            return base.SavingChangesAsync(eventData, result, ct);

        foreach (var entry in eventData.Context.ChangeTracker.Entries())
        {
            if (entry is { State: EntityState.Deleted, Entity: ISoftDeletable entity })
            {
                entry.State = EntityState.Modified;
                entity.IsDeleted = true;
                entity.DeletedAt = DateTime.UtcNow;
            }
        }

        return base.SavingChangesAsync(eventData, result, ct);
    }
}

Add a marker interface:

public interface ISoftDeletable
{
    bool IsDeleted { get; set; }
    DateTime? DeletedAt { get; set; }
}

Implement it on your entity:

public class Blog : ISoftDeletable
{
    public Guid Id { get; set; }
    public string Title { get; set; }
    public bool IsDeleted { get; set; }
    public DateTime? DeletedAt { get; set; }
}

Now when anyone calls context.Remove(blog), EF Core intercepts it and flips IsDeleted instead of deleting the row.

Your handler goes back to being simple:

public async Task Handle(DeleteBlogCommand command, CancellationToken ct)
{
    var blog = await context.Blogs.FindAsync(command.Id);
    context.Blogs.Remove(blog);
    await context.SaveChangesAsync(ct);
}

The interceptor handles the rest. Every entity that implements ISoftDeletable gets soft deleted automatically. No repeated logic. No forgotten flags.

Register it in your DbContext setup:

options.UseNpgsql(connectionString)
       .AddInterceptors(new SoftDeleteInterceptor());

Example 2: Audit Entries

The Pain

Here is what tracking who-did-what looks like without interceptors:

public async Task Handle(CreateBlogCommand command, CancellationToken ct)
{
    var blog = new Blog
    {
        Id = Guid.NewGuid(),
        Title = command.Title,
        CreatedAt = DateTime.UtcNow,
        CreatedBy = _currentUser.UserId
    };

    context.Blogs.Add(blog);
    await context.SaveChangesAsync(ct);
}

public async Task Handle(UpdateBlogCommand command, CancellationToken ct)
{
    var blog = await context.Blogs.FindAsync(command.Id);

    if (blog is null)
        throw new NotFoundException(nameof(Blog), command.Id);

    blog.Title = command.Title;
    blog.UpdatedAt = DateTime.UtcNow;
    blog.UpdatedBy = _currentUser.UserId;

    await context.SaveChangesAsync(ct);
}

Every create handler needs CreatedAt and CreatedBy. Every update handler needs UpdatedAt and UpdatedBy.

Across users, posts, comments, categories, that is a lot of places to remember four lines of code.

Miss one, and your audit trail has a silent gap. You will not notice until someone asks “who changed this?” and you have no answer.

The Fix

Interceptors solve this by inspecting the change tracker before save and automatically stamping audit fields based on the entity state. Added entities get creation timestamps. Modified entities get update timestamps.

Same pattern as soft delete. Different interface.

public interface IAuditable
{
    DateTime CreatedAt { get; set; }
    DateTime? UpdatedAt { get; set; }
    string CreatedBy { get; set; }
    string? UpdatedBy { get; set; }
}

Create the interceptor:

public class AuditInterceptor : SaveChangesInterceptor
{
    private readonly ICurrentUserService _currentUser;

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

    public override ValueTask> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult result,
        CancellationToken ct = default)
    {
        if (eventData.Context is null)
            return base.SavingChangesAsync(eventData, result, ct);

        var now = DateTime.UtcNow;
        var user = _currentUser.UserId;

        foreach (var entry in eventData.Context.ChangeTracker.Entries())
        {
            if (entry.State == EntityState.Added)
            {
                entry.Entity.CreatedAt = now;
                entry.Entity.CreatedBy = user;
            }

            if (entry.State == EntityState.Modified)
            {
                entry.Entity.UpdatedAt = now;
                entry.Entity.UpdatedBy = user;
            }
        }

        return base.SavingChangesAsync(eventData, result, ct);
    }
}

Implement on your entity:

public class Blog : IAuditable
{
    public Guid Id { get; set; }
    public string Title { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime? UpdatedAt { get; set; }
    public string CreatedBy { get; set; }
    public string? UpdatedBy { get; set; }
}

Your handlers go back to just being handlers:

public async Task Handle(CreateBlogCommand command, CancellationToken ct)
{
    var blog = new Blog
    {
        Id = Guid.NewGuid(),
        Title = command.Title
    };

    context.Blogs.Add(blog);
    await context.SaveChangesAsync(ct);
}

public async Task Handle(UpdateBlogCommand command, CancellationToken ct)
{
    var blog = await context.Blogs.FindAsync(command.Id);

    if (blog is null)
        throw new NotFoundException(nameof(Blog), command.Id);

    blog.Title = command.Title;

    await context.SaveChangesAsync(ct);
}

Every insert and update now tracks who did it and when. Zero extra code in your handlers.

This pairs well with the Clean Code Tips I covered earlier. Keeping handlers focused on business logic and pushing infrastructure concerns like auditing into interceptors is exactly what clean code looks like in practice.

Example 3: Outbox Message Insert

The Pain

If you don’t know what the Outbox Pattern is, I have a full article on implementing outbox pattern in .NET — this example assumes the basic idea: when you change state, you write an event to an “outbox” table in the same transaction, so a background process can dispatch it reliably later.

Without an interceptor, every handler that raises a domain event has to build and insert the outbox row itself:

public async Task Handle(DeleteUserCommand command, CancellationToken ct)
{
    var user = await context.Users.FindAsync(command.Id);
    user.Delete();

    var domainEvent = new UserDeletedEvent(user.Id);

    var outboxMessage = new OutboxMessage
    {
        Id = Guid.NewGuid(),
        Type = domainEvent.GetType().AssemblyQualifiedName!,
        Payload = JsonSerializer.Serialize(domainEvent, domainEvent.GetType()),
        CreatedAt = DateTime.UtcNow
    };

    context.Set().Add(outboxMessage);
    await context.SaveChangesAsync(ct);
}

This is the most dangerous one to forget.

Miss the soft-delete flag and a row that should be gone is still visible annoying, but obvious.

Miss the outbox insert and nothing happens. No exception. No log. A downstream service just never finds out the user was deleted, and you won’t know until someone notices the data drifted apart.

The Fix

Interceptors solve this by scanning the change tracker for entities that raised domain events, converting those events into outbox messages, and inserting them automatically in the same transaction.

This is the most powerful use case for interceptors.

First, your base entity raises events:

public abstract class Entity
{
    private readonly List _domainEvents = new();

    public IReadOnlyList DomainEvents => _domainEvents;

    protected void Raise(IDomainEvent domainEvent) =>
        _domainEvents.Add(domainEvent);

    public void ClearDomainEvents() =>
        _domainEvents.Clear();
}

Now the interceptor picks them up before save:

public class OutboxInterceptor : SaveChangesInterceptor
{
    public override ValueTask> SavingChangesAsync(
        DbContextEventData eventData,
        InterceptionResult result,
        CancellationToken ct = default)
    {
        if (eventData.Context is null)
            return base.SavingChangesAsync(eventData, result, ct);

        var outboxMessages = eventData.Context.ChangeTracker
            .Entries()
            .SelectMany(e => e.Entity.DomainEvents)
            .Select(domainEvent => new OutboxMessage
            {
                Id = Guid.NewGuid(),
                Type = domainEvent.GetType().AssemblyQualifiedName!,
                Payload = JsonSerializer.Serialize(domainEvent, domainEvent.GetType()),
                CreatedAt = DateTime.UtcNow
            })
            .ToList();

        eventData.Context.Set().AddRange(outboxMessages);

        foreach (var entry in eventData.Context.ChangeTracker.Entries())
            entry.Entity.ClearDomainEvents();

        return base.SavingChangesAsync(eventData, result, ct);
    }
}

Now your handler looks like this:

public async Task Handle(DeleteUserCommand command, CancellationToken ct)
{
    var user = await context.Users.FindAsync(command.Id);
    user.Delete();
    await context.SaveChangesAsync(ct);
}

user.Delete() raises a UserDeletedEvent. The interceptor catches it and inserts the outbox row using AssemblyQualifiedName, the same convention I used in the outbox article, so Type.GetType() resolves correctly when the background processor picks it up.

Your handler knows nothing about any of this.

Once the outbox message is saved, something needs to process it. I use Wolverine as a Mediator for exactly this. Wolverine picks up outbox messages and dispatches them reliably without you wiring anything manually.

Registering Multiple Interceptors

You can stack them all:

options.UseNpgsql(connectionString)
       .AddInterceptors(
           new SoftDeleteInterceptor(),
           new AuditInterceptor(currentUserService),
           new OutboxInterceptor()
       );

EF Core runs them in the order you register them. If one interceptor modifies entity state that another interceptor needs to see, order matters.

When to Use Interceptors

Use interceptors when the same infrastructure logic needs to run across many entities without touching individual handlers.

Good use cases:

• Soft delete across all entities

• Audit trails (CreatedBy, UpdatedBy, timestamps)

• Outbox message inserts for domain events

• Row-level security (setting TenantId automatically)

• Optimistic concurrency (auto-incrementing version numbers)

• Global query filters (excluding soft-deleted records from queries)

These are all infrastructure concerns. They have nothing to do with your business rules. They need to happen consistently everywhere, and forgetting them creates silent bugs.

Do NOT use interceptors for:

• Business validation (e.g., “a blog post must have a title”)

• Domain rules (e.g., “a user can only delete their own comments”)

• Feature-specific logic (e.g., “send a welcome email when a user registers”)

• Conditional behavior based on the command being executed

If the logic is specific to one feature or depends on business context, it belongs in the handler. Interceptors are for cross-cutting infrastructure that applies universally.

A simple test: If you would need to explain why this logic runs to a product manager, it does not belong in an interceptor. If it is just “how the system works under the hood,” it probably does.

Why This Matters

Interceptors change the way you think about handlers and infrastructure separation.

Your handlers become pure expressions of business intent. They do not care about audit trails, soft deletes, or outbox tables. They just change state and save. The infrastructure takes care of itself.

This is not just cleaner code. It is safer code. You cannot forget to log an audit entry if the system does it automatically. You cannot skip the outbox insert if the interceptor handles it for every save.

When infrastructure concerns live in one place, they are easier to test, easier to change, and impossible to forget.

Demo Code

I put together a complete running example with all three interceptors wired up.

Clone it, run it, and see how clean your handlers look when the infrastructure takes care of itself.

👉 GitHub Issue #78

There are 2 ways I can help you:

Enhance your .NET skills by subscribing to my YouTube Channel

Promote yourself to 10,000+ subscribers by sponsoring this newsletter

Sponsor this newsletter

Your handler saved the data. But the email never sent. The notification never fired. And you have no idea why.

You have seen this bug before.

Everything looks fine. The record is in the database. But something that was supposed to happen after the save just did not.

Maybe the API crashed mid-request. Maybe an exception swallowed the side effect. Maybe it just ran out of memory.

This is not a code bug. It is an architectural gap. And the Outbox Pattern is how you close it.

What is the Outbox Pattern?

The idea is simple.

Instead of firing side effects directly after a save, you write them to a database table in the same transaction as your main data.

A background job then picks them up and processes them reliably.

Without Outbox:

Save User → Send Welcome Email ← email can fail silently

With Outbox:

(Save User + Insert Outbox Message) → Background Job → Send Welcome Email

The key word is same transaction. If the save fails, the outbox message never gets inserted. If the save succeeds, the message is guaranteed to be processed eventually.

The Problem Without It

Here is what most developers write first:

public async Task Handle(RegisterUserCommand command, CancellationToken ct)
{
    var user = User.Create(command.Email);
    context.Users.Add(user);
    await context.SaveChangesAsync(ct);
    await emailService.SendWelcomeEmailAsync(user.Email, ct);
}

This looks fine. But there are two problems.

If SaveChangesAsync throws, the email does not send. Fine, that is expected.

But if SendWelcomeEmailAsync throws after the save, your user is created and never gets the welcome email. And you will never know unless you check manually. Now imagine that email was an OTP for account verification the user is stuck and can never finish signing up.

Multiply this across ten features. Password resets, order confirmations, notification triggers. Every single one is a silent failure waiting to happen.

Setting Up the Outbox Table

Start with the entity:

public class OutboxMessage
{
    public Guid Id { get; set; }
    public string Type { get; set; }
    public string Payload { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime? ProcessedAt { get; set; }
    public string? Error { get; set; }
    public int RetryCount { get; set; }
}

Apply it via migration:

CREATE TABLE OutboxMessages (
    Id UUID PRIMARY KEY,
    Type VARCHAR(255) NOT NULL,
    Payload TEXT NOT NULL,
    CreatedAt TIMESTAMP NOT NULL,
    ProcessedAt TIMESTAMP NULL,
    Error TEXT NULL,
    RetryCount INT NOT NULL DEFAULT 0
);

-- Your background job will run "WHERE ProcessedAt IS NULL ORDER BY CreatedAt" constantly.
-- A partial index keeps that query fast even after the table has millions of processed rows.
CREATE INDEX IX_OutboxMessages_Unprocessed
ON OutboxMessages (CreatedAt)
WHERE ProcessedAt IS NULL;

That partial index only covers unprocessed rows, so it stays small and cheap to scan no matter how large the table gets.

A partial index is an index built over a subset of a table; the subset is defined by a conditional expression (called the predicate of the partial index). The index contains entries only for those table rows that satisfy the predicate. Partial indexes are a specialized feature, but there are several situations in which they are useful.

Writing to the Outbox

Without using the outbox our code would look like this normally :

public async Task Handle(RegisterUserCommand command, CancellationToken ct)
{
    var user = User.Create(command.Email);
    context.Users.Add(user);
    await context.SaveChangesAsync(ct);
    
   // Separate operation — no guarantee this runs
    await emailService.SendWelcomeEmailAsync(user.Email, ct);
}

Instead, write the event to the outbox table in the same transaction as your business data:

public async Task Handle(RegisterUserCommand command, CancellationToken ct)
{
    var user = User.Create(command.Email);
    var welcomeEmail = new WelcomeEmailRequested(user.Email);
    var outboxMessage = new OutboxMessage
    {
        Id = Guid.NewGuid(),
        Type = typeof(WelcomeEmailRequested).AssemblyQualifiedName!,
        Payload = JsonSerializer.Serialize(welcomeEmail),
        CreatedAt = DateTime.UtcNow
    }; 
    context.Users.Add(user);
    context.OutboxMessages.Add(outboxMessage); 
    await context.SaveChangesAsync(ct);
}

No email call. No notification call. Just save and done.

Both the user and the outbox message are written atomically. If the transaction rolls back, both roll back. Nothing is lost.

A small but important detail: store AssemblyQualifiedName, not just the type’s short name (nameof(WelcomeEmailRequested) gives you "WelcomeEmailRequested" with no namespace or assembly info). Your background job needs to turn that string back into a real Type to deserialize the payload and Type.GetType(...) can only do that reliably if the string carries the full assembly info. Skip this and your job will throw InvalidOperationException: Unknown event type the first time it runs.

Processing the Outbox

A background job polls the table and processes unhandled messages:

[DisallowConcurrentExecution]
internal sealed class ProcessOutboxMessagesJob(AppDbContext dbContext, IMessageBus messageBus) : IJob
{
    public async Task Execute(IJobExecutionContext context)
    {
        var cancellationToken = context.CancellationToken;

        await using var transaction = await dbContext.Database.BeginTransactionAsync(cancellationToken);

        var messages = await dbContext.OutboxMessages
            .FromSqlRaw(
                """
                SELECT "Id", "Type", "Payload", "CreatedAt", "ProcessedAt", "Error", "RetryCount"
                FROM "OutboxMessages"
                WHERE "ProcessedAt" IS NULL
                ORDER BY "CreatedAt"
                LIMIT 20
                FOR UPDATE SKIP LOCKED
                """)
            .ToListAsync(cancellationToken);

        foreach (var message in messages)
        {
            try
            {
                var eventType = Type.GetType(message.Type)
                    ?? throw new InvalidOperationException($"Unknown event type '{message.Type}'.");

                var @event = JsonSerializer.Deserialize(message.Payload, eventType)
                    ?? throw new InvalidOperationException($"Could not deserialize payload for '{message.Type}'.");

                await messageBus.InvokeAsync(@event, cancellationToken);

                message.ProcessedAt = DateTime.UtcNow;
                message.Error = null;
            }
            catch (Exception ex)
            {
                message.Error = ex.Message;
                message.RetryCount++;
            }
        }

        await dbContext.SaveChangesAsync(cancellationToken);
        await transaction.CommitAsync(cancellationToken);
    }
}

The job runs every 10 seconds. It fetches up to 20 unprocessed messages, publishes them, and marks them processed. Oldest first, always.

If you’re already using Wolverine as your mediator (see my Wolverine as Mediator in .NET piece), IMessageBus.InvokeAsync here is the exact same call you’d use to dispatch a command in your handlers the outbox job is just another caller.

At-Least-Once Delivery: Your Consumers Must Be Idempotent

Some points worth considering, the outbox pattern does not guarantee a message is processed exactly once. It guarantees at least once.

Think about what happens if the job publishes the message successfully, then crashes before it can set ProcessedAt and commit. The next run picks up that same message and publishes it again.

That means SendWelcomeEmailAsync or whatever handler consumes the message needs to be safe to run twice. A few practical ways to get there:

• Check whether the action already happened before doing it again (e.g., “has this user already received a welcome email?”).

• Use a natural or generated idempotency key so duplicate sends are detected and skipped downstream.

• For anything transactional (charging a card, decrementing stock), make the operation itself idempotent rather than relying on the outbox to dedupe for you.

Preventing Duplicate Processing

If two instances of your app run at the same time, both might pick up the same message.

Use FOR UPDATE SKIP LOCKED to prevent that:

SELECT * FROM "OutboxMessages"
WHERE "ProcessedAt" IS NULL
ORDER BY "CreatedAt"
LIMIT 20
FOR UPDATE SKIP LOCKED

Now only one instance processes each message. The other skips it and moves on.

Note this solves concurrent duplicate processing across instances it does not replace the idempotency work above, which covers crash-and-retry duplicates on a single instance.

Keeping the Outbox Table Healthy

Nobody thinks about this until the table has ten million rows and the background job starts timing out.

Two habits keep it under control:

1. Cap retries. I have added a column named RetryCount in our entity use it for retries count. After a handful of failed attempts (e.g. 3 attempts), stop retrying automatically and flag the message for manual review instead of hammering a dependency that’s clearly down.

2. Archive or delete processed rows. Once a message is processed and you’re past the window where you’d ever need to debug it, delete it (or move it to a cold-storage table):

DELETE FROM "OutboxMessages"
WHERE "ProcessedAt" IS NOT NULL
AND "ProcessedAt" < NOW() - INTERVAL '7 days';

Run this as its own scheduled job, separate from the processor. A table that only ever grows will eventually make even the partial index expensive to maintain.

👉 Find complete running demo code at GitHub Issue #77

Summary

Here is everything covered in this issue:

• The problem: saving data and calling side effects separately creates a silent failure gap.

• The fix: write your messages to a database table in the same transaction as your business data, then process them asynchronously.

• OutboxMessage entity stores the event type (as an assembly-qualified name), serialized payload, and processed timestamp.

• Write the outbox message directly in your handler alongside your business data in one SaveChangesAsync call.

• A background job polls every 10 seconds, deserializes each message, publishes it, and marks it processed.

• FOR UPDATE SKIP LOCKED prevents duplicate processing across multiple app instances.

• Outbox delivery is at-least-once your consumers must be idempotent.

• A partial index and a cleanup job keep the table fast as it grows.

One table. One background job. Zero lost events.

There are 3 ways I can help you:

1. Enhance your .NET skills by subscribing to my YouTube Channel

2. Promote yourself to 10,000+ subscribers by sponsoring this newsletter

3. Have a software idea? Let’s turn it into a real product, Work With Me

“Search is easy... until users stop searching with the exact words you stored.”

Imagine you have thousands of blog posts.

A user searches:

“How do I secure my APIs?”

But your blog title is:

“JWT Authentication in ASP.NET Core”

A normal database search returns nothing.

Even though that article is exactly what the user wants.

This is the problem with keyword search and it is why AI-powered search exists.

In this article, we will build an AI-powered search using:

• ASP.NET Core

• PostgreSQL

• pgvector

• Gemini Embeddings API

Let’s break it down step by step.

The Problem With Normal Search

Here is what normal search looks like in EF Core:

var blogs = await context.Blogs
    .Where(x =>
        x.Title.Contains(search) ||
        x.Description.Contains(search))
    .ToListAsync();

This works fine when users search with the exact words stored in your database.

But when they search by meaning, “secure my APIs” instead of “JWT”, it fails silently.

You get zero results. Not because the data does not exist, but because the search does not understand meaning.

That is what vector search solves.

What is Vector Search?

Vector Search is a way of searching by meaning instead of exact words.

Instead of asking:

“Does this sentence contain JWT?”

It asks:

“Does this sentence mean something similar to what the user asked?”

What are Embeddings?

Embeddings are numbers that represent the meaning of text.

A sentence like:

“JWT Authentication in ASP.NET Core”

becomes something like:

[0.123, -0.873, ...]

Text with similar meanings produces similar vectors. That is how meaning-based search works.

Step 1 — Generate Embeddings with Gemini

Almost every AI provider offers an embedding model. Gemini, OpenAI, local LLMs.

With the Gemini free API, you send your text using the models e.g. gemini-embedding-001 :

POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent";

And you will receive a response similar to this :

{
  "embedding": [0.123, -0.873, ...]
}

Store this vector in your database alongside the blog post.

Step 2 — Update Your Blog Entity

Add an Embedding property to your Blog entity:

using Pgvector;

public class Blog
{
    public Guid Id { get; set; }
    public string Title { get; set; }
    public string Description { get; set; }
    public Vector? Embedding { get; set; }   // New
}

Step 3 — Configure PostgreSQL

Enable the pgvector extension:

CREATE EXTENSION vector;

Add the vector column:

ALTER TABLE Blogs
ADD COLUMN Embedding vector(768);

Install the EF Core package:

dotnet add package Pgvector.EntityFrameworkCore

Configure it in your DbContext:

options.UseNpgsql(connectionString, o => o.UseVector());

PostgreSQL now understands vectors.

Step 4 — Save Embeddings on Blog Creation

Whenever a new blog is created, generate and save its embedding:

Blog → Gemini Embedding API → Embedding Vector → Save Blog + Vector

blog.Embedding = await embeddingService.GenerateAsync(blog.Description);

context.Blogs.Add(blog);

await context.SaveChangesAsync();

Step 5 — Search by Meaning

When a user searches “Secure my APIs”:

Generate an embedding for the search query:

var queryEmbedding = await embeddingService.GenerateAsync(search);

Then ask PostgreSQL to return the nearest vectors:

var blogs = await context.Blogs
    .OrderBy(x => x.Embedding.CosineDistance(queryEmbedding))
    .Take(5)
    .ToListAsync();

Cosine distance measures how similar two vectors are in meaning.

The closest ones come back first, even if no keywords match.

Demo Code

I put together a complete running Web API with 100 seeded articles.

Clone the repo, add your Gemini API key and PostgreSQL connection string and you are ready to go.

👉 GitHub Issue #76

What is Next?

Vector search gets you the right documents.

But what if you want a direct answer instead of a list of results?

That is where RAG comes in. You take these search results and pass them to an LLM to generate a precise, grounded answer. We will cover that in the future articles.

There are 2 ways I can help you:

1. Enhance your .NET skills by subscribing to my YouTube Channel

2. Promote yourself to 10,000+ subscribers by sponsoring this newsletter

If you’ve been building software for a while, you’ve probably heard the term Monorepo.

But what exactly is it?

Let’s break it down.

What is a Monorepo?

A Monorepo (Monolithic Repository) is a single Git repository that contains multiple projects.

As per the official definition :

A monorepo (monolithic repository) is a software development strategy where code for multiple separate, independent projects or services is stored in a single repository

Instead of creating separate repositories for your frontend, backend, mobile apps, shared libraries, and infrastructure, everything lives in one repository.

For example:

pakexam/
│
├── frontend/
├── admin-panel/
├── backend/
│   ├── API
│   ├── Application
│   ├── Domain
│   ├── Infrastructure
│   └── Tests
│
├── mobile/
│   ├── android/
│   └── ios/
│
├── shared/
└── docs/

Everything is versioned together.

One commit can update multiple projects at the same time.

Monorepo vs Multiple Repositories

In the opposite of monorepos we have option of multiple repos, let’s see how it looks in picture :

One repository, single source of truth.

pakexam
├── frontend
├── backend
├── admin
├── mobile
└── shared

On the other hand for multiple repos :

pakexam-frontend
pakexam-backend
pakexam-admin
pakexam-mobile
pakexam-shared

Each project has its own Git repository.

Both approaches are valid.

The right choice depends on your team and product.

When should you use a Monorepo?

A monorepo works really well when:

• You’re building multiple applications that evolve together.

• Frontend and backend are maintained by the same team or in my case you are the only developer.

• You have shared code or libraries.

• Changes often span multiple projects.

• You want everything versioned together.

For example, imagine you rename an API endpoint.

With a monorepo, you can update:

• Backend

• Frontend

• Mobile

• Shared SDK

• Tests

...all in a single commit.

No synchronization headaches.

When should you avoid it?

A monorepo isn’t always the right answer.

It can become difficult when:

• Hundreds of developers work on unrelated products.

• Different teams have completely independent release cycles.

• Repository size becomes enormous.

• CI/CD pipelines aren’t optimized.

Without proper tooling, build times can also become slower.

Benefits of a Monorepo

Some of the biggest advantages are:

• Easier refactoring : You can safely make changes across multiple projects.

• Shared code : Utilities, DTOs, models, UI components, or libraries can live in one place.

• Simpler dependency management : Everything uses compatible versions.

• No wondering whether Repository A is using an older package than Repository B.

• Easier onboarding : A new developer clones one repository and has access to the entire product.

• Atomic commits : One pull request can include frontend, backend, tests, and documentation together.

Challenges

Of course, nothing is free.

A monorepo also comes with trade-offs:

• Larger Git repository

• More complex CI/CD

• Need for build caching

• Good folder structure becomes critical

• Permissions are harder if different teams shouldn’t see certain projects

Modern tools like Nx, Turborepo, Bazel, Rush, and Pants help solve many of these challenges.

Which companies use Monorepos?

Some well-known companies that use monorepos include:

• Google

• Meta (Facebook)

• Microsoft (many internal engineering teams)

• Uber

• Airbnb

• X (formerly Twitter)

• Dropbox

Their repositories are obviously much larger than ours, but the idea is the same: keep related code together so teams can move faster.

Where did I use it?

I use a monorepo for my SaaS project PakExam.

The repository currently contains:

• Website (Frontend)

• Admin Panel

• .NET Backend

• Clean Architecture layers

• Unit & Integration Tests

• Android App (not live yet)

• iOS App (not live yet)

Everything is developed from a single repository.

When I change the backend contract, I can immediately update the frontend, admin panel, and mobile applications without jumping between multiple repositories.

For a solo developer, this has made development much smoother.

And with the evolution of AI I can easily set instructions in the instructions file e.g. claude.md that whenever a change in backend API happens reflect it automatically wherever that API was being used

Should everyone use a Monorepo?

No. It’s a tool, not a rule.

If you’re building several applications that share the same domain and are maintained by the same team, a monorepo is often an excellent choice.

If your products are completely independent and owned by different teams, multiple repositories may be the better option.

Choose the approach that reduces complexity for your team not the one that’s currently trending.

Have you ever used a monorepo, or do you prefer multiple repositories?

I’d love to hear your experience.

There are 2 ways I can help you:

1. Enhance your .NET skills by subscribing to my YouTube Channel

2. Promote yourself to 10,000+ subscribers by sponsoring this newsletter

With the recent news that MediatR will become commercial in its upcoming versions, developers might be considering alternatives. I respect Jimmy Bogard's decision and wish him the best; however, if you are an individual, not a company, and are wondering how to navigate this change, today’s article will be helpful for you.

We will explore how to use this awesome NuGet package, free to use as of the date I am writing this article.

Wolverine is a Next Generation .NET Mediator and Message Bus available as a free nuget package on nuget package manager store.

Let’s start with a fresh .NET 8 Web API :

Name your project:

I am using .NET 8 and choosing the controllers option :

Install the wolverine package :

Register the dependency of this package :

Let’s keep this super simple:

We want to send a “greeting” message and get back a friendly hello. In Wolverine, you don’t implement any special interfaces; everything happens by naming conventions.

First, define a plain request object that carries the user’s name. Then, create a public handler class whose name ends in Handler (or Consumer) and give it a single method that ends in Handle (or Consume). Inside that method, you write your greeting logic.

To send a message from our controller, we use the IMessageBus interface provided by the package. We inject IMessageBus into the controller’s constructor and then invoke it like this:

When you call bus.InvokeAsync With your request, Wolverine scans its known assemblies for any public class named SomethingHandler (or SomethingConsumer) and looks for a matching Handle(...) (or Consume(...)) method that takes your request type. It then invokes that method and returns the result no interfaces, no manual registrations, no extra boilerplate.

If your request returns a response, then we must specify it next to InvokeAsync<ResponseType>. Let’s try our request :

Ok but this is not enough we might need to add the fluent validation as well, so we can use this nugget come from same library :

You don’t need to install FluentValidation separately this packages does it under the hood :

Time to add some validation :

Here we add and modify our dependencies by adding FluentValidator as an option :

And here our validator comes into action :

That looks ugly, but we can do that some day later to make it look better.

Wolverine is packed with powerful features, durable outbox, scheduled delivery, sagas, and more but if you only need its in-process mediator capabilities, you can trim the extras in your Program.cs. By registering just the core mediator services, you avoid pulling in unnecessary modules and keep your application lean and efficient.

There are 2 ways I can help you:

1. Enhance your .NET skills by subscribing to my YouTube Channel

2. Promote yourself to 10,000+ subscribers by sponsoring this newsletter

Blazor is a modern web framework developed by Microsoft that allows developers to build interactive web applications using C# instead of JavaScript.

It leverages the power of .NET and provides a component-based architecture, making it easier to create rich user interfaces.

In this series about Blazor, we will dive into different aspects, and today we will discuss an introduction.

Key Features of Blazor

To fully grasp the blazor application, it's essential to understand its key features :

1. C# and .NET: Blazor enables developers to write client-side code in C#, allowing for a unified development experience across the client and server. You can share code and libraries between the server and the client.

2. Component-Based Architecture: Blazor applications are built using reusable components. Each component encapsulates its rendering logic, state, and behavior, promoting modularity and reusability.

3. Two Hosting Models:

   • Blazor Server: In this model, the application runs on the server, and UI updates are sent to the client over a SignalR connection. This allows for fast load times and reduced client resource usage.

   • Blazor WebAssembly: This model runs the application directly in the browser using WebAssembly. It allows for offline capabilities and a more responsive user experience, as the application runs client-side.

4. Rich Interactivity: Blazor supports data binding, event handling, and dependency injection, enabling developers to create dynamic and interactive web applications.

5. Integration with JavaScript: While Blazor allows you to write applications in C#, it also provides the ability to call JavaScript functions and use existing JavaScript libraries when needed.

   • Routing: Blazor includes built-in routing capabilities, allowing developers to define routes for different components and manage navigation within the application easily.

   • Form Handling and Validation: Blazor provides robust support for forms, including data binding and validation, making it easier to create forms that are user-friendly and maintainable.

Components of Blazor

We can break down the blazor into the following components for better understanding:

1. Components: The building blocks of Blazor applications. A component is a self-contained unit of UI that can include HTML markup, C# code, and CSS styles.

2. Razor Syntax: Blazor uses Razor syntax, which combines HTML and C# code. This allows for seamless integration of server-side logic with client-side rendering.

3. Dependency Injection: Blazor supports dependency injection, allowing you to manage service lifetimes and inject services into components easily.

Use Cases for Blazor

Here are the use cases for Blazor:

1. Single Page Applications (SPAs): Blazor is well-suited for building SPAs that require rich interactivity and dynamic content updates.

2. Enterprise Applications: With its component-based architecture and C# support, Blazor is ideal for developing complex enterprise applications that require maintainability and scalability.

3. Progressive Web Apps (PWAs): Blazor WebAssembly can be used to create PWAs that work offline and provide a native-like experience on the web.

Summary

Blazor represents a significant shift in web development by allowing developers to use C# and .NET for building interactive web applications.

Its component-based architecture, rich interactivity, and support for both server-side and client-side hosting models make it a powerful choice for modern web development.

Whether you are building SPAs, enterprise applications, or PWAs, Blazor provides the tools and flexibility needed to create high-quality web applications.

Tap the ❤️ if you enjoyed this article—it motivates me to keep sharing more!

Have suggestions or thoughts to contribute?
Share them in the comments 💬. Your feedback is always valued and appreciated!

Share it with others who might benefit ♻️

There are 2 ways I can help you:

1. Enhance your .NET skills by subscribing to my YouTube Channel

2. Promote yourself to 9,700+ subscribers by sponsoring this newsletter

1/ Static

The static keyword is used to declare members that belong to the type itself rather than to any specific instance. This means you can access static members without creating an instance of the class. Static members are shared across all instances of the class :

public class Program
{
    public static void Main(string[] args)
    {
        double squareOfFour = MathUtilities.Square(4);
    }
}

public class MathUtilities
{
    public static double Square(double number)
    {
        return number * number;
    }
}

2/ Constant

The const keyword is used to declare a constant field or local. Constants are immutable values that are known at compile time and do not change for the life of the program. They must be initialized at the time of declaration.

public class Circle
{
    public const double Pi = 3.14159;

    public double CalculateCircumference(double radius)
    {
        return 2 * Pi * radius;
    }
}

3/ Readonly

The readonly keyword is used to declare a field that can only be assigned during its declaration or in the constructor of the same class. This is useful for fields that should not change after the object is constructed.

public class Configuration
{
    public readonly string _configName;

    public Configuration(string name)
    {
        _configName = name;
    }
}

4/ Async and Await

The async and await keywords are used to write asynchronous code. async is used to declare a method as asynchronous, and await is used to pause the execution of the method until the awaited task completes. This allows for non-blocking operations, improving the responsiveness of applications.

public async Task<string> FetchDataAsync()
{
    await Task.Delay(1000);

    return "Data fetched";
}

5/ Yield

The yield keyword is used in iterator methods to provide a value to the enumerator object and to signal the position in the code to resume execution when the next element is requested. It simplifies the implementation of iterators.

public IEnumerable<int> GetNumbers()
{
    for (int i = 0; i < 5; i++)
    {
        yield return i;
    }
}

6/ Ref

The ref keyword is used to pass arguments by reference, allowing the method to modify the original variable:

public class Program
{
    public static void Main(string[] args)
    {
        int number = 5;

        DoubleValue(ref number);

        Console.WriteLine($"{number}");
    }

    public static void DoubleValue(ref int number)
    {
        number *= 2;
    }
}
---
10

7/ Out

Similar to ref, the out keyword is used to pass arguments by reference, but it requires the method to assign a value to the parameter.

public class Program
{
    public static void Main(string[] args))
    {
        if (TryParseNumber("123", out int result))
        {
            Console.WriteLine($"Parsed number: {result}");
        }
        else
        {
            Console.WriteLine("Failed to parse number.");
        }
    }

    public static bool TryParseNumber(string input, out int result)
    {
        return int.TryParse(input, out result);
    }
}
---
Parsed number: 123

8/ Params

The params keyword allows you to pass a variable number of arguments to a method:

public class Program
{
    public static void Main((string[] args)
    {
        int sum = Sum(1, 2, 3, 4, 5);

        Console.WriteLine($"Sum: {sum}");
    }

    public static int Sum(params int[] numbers)
    {
        int sum = 0;

        foreach (int number in numbers)
        {
            sum += number;
        }
        return sum;
    }
}
---
Sum: 15

9/ Is and As

The is keyword checks if an object is of a specific type.

The as keyword is used to perform safe type conversions, returning null if the conversion fails:

public void CheckType(object obj)
{
    if (obj is string)
    {
        Console.WriteLine("It's a string!");
    }

    string str = obj as string;

    if (str != null)
    {
        Console.WriteLine("Conversion successful!");
    }
}

10/ Lock

The lock keyword is used to ensure that a block of code runs exclusively in a multi-threaded environment.

private readonly object _lock = new object();

public void ThreadSafeMethod()
{
    lock (_lock)
    {
        // Critical section
    }
}

11/ Base

base refers to the base class constructor or members:

public class BaseClass
{
    public virtual void Display()
    {
        Console.WriteLine("Base class display");
    }
}

public class DerivedClass : BaseClass
{
    public override void Display()
    {
        base.Display();
        Console.WriteLine("Derived class display");
    }
}

12/ This

this Refers to the current instance of the class.

public class Person
{
    private string name;

    public Person(string name)
    {
        this.name = name;
    }
}

13/ New

new keyword hides a member inherited from a base class or creates an object :

public class BaseClass
{
    public void Display()
    {
        Console.WriteLine("Base class display");
    }
}

public class DerivedClass : BaseClass
{
    public new void Display()
    {
        Console.WriteLine("Derived class display");
    }
}

14/ Abstract

abstract defines a class or method that must be implemented by derived classes.

public abstract class Shape
{
    public abstract double Area();
}

public class Circle : Shape
{
    private double radius;

    public Circle(double radius)
    {
        this.radius = radius;
    }

    public override double Area()
    {
        return Math.PI * radius * radius;
    }
}

15/ Sealed

sealed keyword prevents a class from being inherited.

public sealed class FinalClass
{
    public void Display()
    {
        Console.WriteLine("This class cannot be inherited");
    }
}

16/ Override

override keyword overrides a virtual method in a base class :

public class BaseClass
{
    public virtual void Display()
    {
        Console.WriteLine("Base class display");
    }
}

public class DerivedClass : BaseClass
{
    public override void Display()
    {
        Console.WriteLine("Derived class display");
    }
}

17/ Partial

partial keyword splits a class, struct, or method definition across multiple files.

// File1.cs
public partial class PartialClass
{
    public void Method1()
    {
        Console.WriteLine("Method1");
    }
}

// File2.cs
public partial class PartialClass
{
    public void Method2()
    {
        Console.WriteLine("Method2");
    }
}

Tap the ❤️ if you enjoyed this article—it motivates me to keep sharing more!

Have suggestions or thoughts to contribute?
Share them in the comments 💬. Your feedback is always valued and appreciated!

Share it with others who might benefit ♻️

There are 2 ways I can help you:

1. Enhance your .NET skills by subscribing to my YouTube Channel

2. Promote yourself to 9,700+ subscribers by sponsoring this newsletter

AI is everywhere!

Let’s walk through three simple steps to add it to your Web App or Web API :

Get your API Key

Retrieve your API key from the OpenAI website. Make sure you have already created the account.

Install the Required NuGet Package

Add the OpenAI NuGet package to your .NET API project :

dotnet add package OpenAI

Configure Your Code

Set up your code to initialize and use the OpenAI API, this is the sample code

 public async Task<string> Chat(string query)
 {
     ChatClient client = new(model: "gpt-4o", apiKey: API_KEY);

     ChatCompletion completion = await client.CompleteChatAsync(query);

     string response = completion.Content[0].Text;

     return response;
 }

This code's purpose is to demonstrate how we can connect the Open AI, we will see in the next sections how we can improve this code.

Available Methods and Properties

ChatClient comes from the OpenAI.Chat and the ChatClient constructor can take:

1. Model and ApiKey

2. Model and ApiKeyCredential

3. Model, ApiKeyCredential and OpenAIClientOptions

It has the following methods:

Task<ClientResult<ChatCompletion>>CompleteChatAsync(
   IEnumerable<ChatMessage> messages, 
   ChatCompletionOptions options = null, 
   CancellationToken cancellationToken = default);

ClientResult<ChatCompletion> CompleteChat(
   IEnumerable<ChatMessage> messages, 
   ChatCompletionOptions options = null, 
   CancellationToken cancellationToken = default);

Task<ClientResult<ChatCompletion>> CompleteChatAsync(
params ChatMessage[] messages);

ClientResult<ChatCompletion> CompleteChat(params ChatMessage[] messages);

Each method has its Async version as well we can use the one according to our need.

There is an additional asynchronous method called CompleteChatStreaming. Unlike CompleteChatAsync, this method streams the completion back token by token as it is generated.

ChatCompletion contains Id, Model, SystemFingerprint, Role, Content , ToolCalls and Usage details.

Listing every detail isn’t feasible, but our response is found within the Content object. This object includes Text, Refusal, and additional properties related to images if the response contains one.

Best Practices

Let’s improve this code :

public async Task<string> Chat(string query)
 {
     ChatClient client = new(model: "gpt-4o", apiKey: API_KEY);

     ChatCompletion completion = await client.CompleteChatAsync(query);

     string response = completion.Content[0].Text;

     return response;
 }

1. Create an Enum to define the available models rather than passing the model as a string.

2. Retrieve the API_Key from app settings or a secure vault.

3. Implement a dedicated service for OpenAI features to ensure reusability.

4. Provide separate methods for asynchronous and synchronous calls.

5. Perform NULL checks to validate the query.

6. Use try-catch blocks to handle exceptions.

7. Refer to OpenAI's documentation to display detailed error messages for each error code :

Common Errors in Package Configuration

While setting up the library you can get this error :

The model gpt-4o does not exist or you do not have access to it.

To resolve this you must have a five USS balance in your Open API account.

Tap the ❤️ if you enjoyed this article—it motivates me to keep sharing more!

Have suggestions or thoughts to contribute?
Share them in the comments 💬. Your feedback is always valued and appreciated!

Share it with others who might benefit ♻️

There are 2 ways I can help you:

1. Enhance your .NET skills by subscribing to my YouTube Channel

2. Promote yourself to 9,700+ subscribers by sponsoring this newsletter

Are you a content creator or a small business looking to enhance your social media presence? With BrandGhost, you can effortlessly share your content across multiple platforms without the hassle of manual scheduling. Reclaim your time for what matters most and let BrandGhost effortlessly deliver your content to your audience!

START YOUR 30-DAY TRIAL

Sponsor this newsletter

Data validation ensures that only correct and expected data reaches our databases, as user input can be unpredictable. We can use various validation methods, including Fluent Validation and Data Annotations to achieve this.

In this article, we’ll explore how to implement data annotations effectively in a web application.

Applying Validation Using Data Annotations

Data annotations allow us to apply validation by adding attributes to model properties. The System.ComponentModel.DataAnnotations namespace provides these attributes by default in .NET, with no additional setup needed.

Common Validation Attributes

Common validation attributes include:

• [Required]

• [StringLength]

• [Range]

• [RegularExpression]

• [EmailAddress]

• [Compare]

• [MinLength]

• [MaxLength]

• [AllowedValues]

We'll explore each of these with code examples.

Using Validation Attributes in C#

[Required]

Ensures that a property is not null or empty :

using System.ComponentModel.DataAnnotations;

namespace DataAnnotations.Models;

public sealed class User
{
    [Required]
    public string Name { get; set; }
    
    ... Other properties ...
}

This field is now required, and if a value is not provided, an error message will be displayed like this.

To customize the default error message, we can add the ErrorMessage attribute, like this :

public sealed class User
{
    [Required(ErrorMessage = "Name is required.")]
    public string Name { get; set; }
    
    ... Other properties ...
}

[StringLength]

Specifies the minimum and maximum length of a string property :

public sealed class User
{
  [StringLength(maximumLength:100,
   MinimumLength=6,
   ErrorMessage="Password must be between 6 and 100 characters")]
  public string Password { get; set; }
    
    ... Other properties ...
}

[Range]

Defines a numeric range for a property :

public sealed class User
{
     [Range(18, 65, ErrorMessage = "Age must be between 18 and 65")]
     public int Age { get; set; }
   
    ... Other properties ...
}

[RegularExpression]

Validates a property against a regular expression pattern :

public sealed class User
{
     [RegularExpression(@"^[a-zA-Z0-9+_.-]+@[a-zA-Z0-9.-]+$",
     ErrorMessage = "Invalid email format.")]
     public string Email { get; set; }
   
    ... Other properties ...
}

[EmailAddress]

Validate a property whether it is a valid email or not:

public sealed class User
{
     [EmailAddress(ErrorMessage ="Email address is not valid")]
     public string Email { get; set; }
   
    ... Other properties ...
}

[Compare]

It compares the value of one property with another and makes sure both are the same:

public sealed class User
{
     [Required]
     [Compare("Password", 
     ErrorMessage = "Password and ConfirmPassword should be same")]
     public string ConfirmPassword { get; set; }

    [Required]
    public string Password { get; set; }
}

[MinLength] and [MaxLength]

Another way to specify the minimum and maximum length of a string or array type property :

public sealed class User
{
    [Required]
    [MinLength(4)]
    [MaxLength(20)]
    public string Name { get; set; }
    
    ... Other properties ...
}

[AllowedValues]

Gets the list of values allowed by this attribute :

public sealed class User
{
    [AllowedValues(UserTypes.Admin)]
    public UserTypes UserType { get; set; }
    
    ... Other properties ...
}

public enum UserTypes
{
    Admin,
    Customer
}

How validation is triggering

If you're wondering how this validation is triggered, you'll need to add asp-validation-for it to your HTML(View in my case for MVC)

 <div class="form-group">
     <label asp-for="Name" class="control-label"></label>
     <input asp-for="Name" class="form-control" />
     <span asp-validation-for="Name" class="text-danger"></span>
 </div>

Additional Purposes of Data Annotations

Data annotations can also serve additional purposes beyond validation, such as:

[Display]

Specifies how data, including name, description, and order, is displayed in the UI.

[DisplayFormat]

Specifies the format for displaying data, such as date and currency formats.

[DataType]

Provides additional type information, such as DataType.Date, DataType.Time, DataType.Currency, etc.

[Key]

Specifies that a property is the primary key of an entity.

[ForeignKey]

Specifies a foreign key relationship between entities.

Tap the ❤️ if you enjoyed this article—it motivates me to keep sharing more!

Have suggestions or thoughts to contribute?
Share them in the comments 💬. Your feedback is always valued and appreciated!

Share it with others who might benefit ♻️

There are 2 ways I can help you:

1. Enhance your .NET skills by subscribing to my YouTube Channel

2. Promote yourself to 9,000+ subscribers by sponsoring this newsletter

Middlewares are used to add additional logic before and after HTTP requests.

We can create custom middleware, and there is a wide range of built-in middleware available that we can utilize:

Simply adding a middleware code (as show in the article) does not guarantee that its intended purpose will be fully achieved. Additional services, configurations, and logic may be required to meet specific application needs.

This article aims to explain the purpose of commonly seen middleware in the Program.cs file, along with a few additional middleware components.

1. Static Files Middleware

Purpose: Serves static files such as HTML, CSS, JavaScript, and images directly from the file system.

app.UseStaticFiles();

Details: This middleware is typically placed early in the pipeline to efficiently serve static content without further processing.

2. Routing Middleware

Purpose: Matches incoming HTTP requests to endpoints defined in the application.

app.UseRouting();

Details: Routing middleware is essential for directing requests to the appropriate controllers or endpoints. It should be placed before any middleware that depends on routing information, such as authorization.

3. Authentication Middleware

Purpose: Handles user authentication, verifying user credentials, and establishing user identity.

app.UseAuthentication();

Details: This middleware should be placed before authorization middleware to ensure that users are authenticated before access checks are performed.

4. Authorization Middleware

Purpose: Enforces access control policies, ensuring that authenticated users have the necessary permissions to access resources.

app.UseAuthorization();

Details: Authorization middleware should be placed after authentication middleware to ensure that only authenticated users are authorized.

5. CORS Middleware

Purpose: Configures Cross-Origin Resource Sharing (CORS) policies to allow or restrict resources requested from another domain.

app.UseCors("AllowAllPolicy");

Details: CORS middleware is crucial for enabling secure cross-origin requests, especially in API applications.

6. Session Middleware

Purpose: Manages user sessions, allowing data to be stored and retrieved across multiple requests.

app.UseSession();

Details: Session middleware requires session services to be configured in services.

7. Response Compression Middleware

Purpose: Compresses HTTP responses to reduce bandwidth usage and improve load times.

app.UseResponseCompression();

Details: This middleware is beneficial for optimizing performance, especially for large responses.

8. Exception Handling Middleware

Purpose: Provides a centralized mechanism for handling exceptions and generating error responses.

app.UseExceptionHandler("/Home/Error"); //Web App

app.UseExceptionHandler(); //API

Details: Exception-handling middleware should be placed early in the pipeline to catch exceptions from subsequent middleware.

9. HTTPS Redirection Middleware

Purpose: Redirects HTTP requests to HTTPS, ensuring secure communication.

app.UseHttpsRedirection();

Details: This middleware is essential for enforcing HTTPS in production environments.

10. HSTS Middleware

Purpose: Enforces HTTP Strict Transport Security (HSTS) headers, instructing browsers to only access the site over HTTPS.

app.UseHsts();

Details: HSTS middleware should be used in conjunction with HTTPS redirection for enhanced security.

11. Run Middleware

Purpose: Defines a terminal middleware delegate that handles HTTP requests and generates responses directly, without passing control to subsequent middleware.

app.Run();

Details: app.Run() is used to set up a terminal middleware in the ASP.NET Core request processing pipeline. It is typically placed at the end in Program.cs file and is responsible for producing the final response.

Tap the ❤️ if you enjoyed this article—it motivates me to keep sharing more!

Have suggestions or thoughts to contribute?
Share them in the comments 💬. Your feedback is always valued and appreciated!

Share it with others who might benefit ♻️

There are 2 ways I can help you:

1. Enhance your .NET skills by subscribing to my YouTube Channel

2. Promote yourself to 9,000+ subscribers by sponsoring this newsletter

Cross-Origin Resource Sharing (CORS) is essential when building .NET web applications to allow them to handle requests from different origins.

By default, web applications are governed by the same-origin policy, which restricts web browsers from requesting a different origin for security reasons.

What is the Same-Origin Policy?

The same-origin policy ensures that a web application can only interact with resources from the same origin (i.e., the same domain). For instance, consider the following URLs:

• URL 1: https://www.facebook.com/GetFriends

• URL 2: https://www.facebook.com/GetPosts

Both URLs share the same origin because they have the same protocol (https), domain (www.facebook.com).

Consider these two URLs:

• URL 1: https://www.facebook.com/GetFriends

• URL 2: https://www.twitter.com/GetFollowers

These URLs have different origins since they belong to different domains (facebook.com vs twitter.com). In such cases, a browser will block requests to the second origin unless CORS is enabled.

Why Do We Need CORS?

If you have a .NET Core Web API providing data and multiple applications from different origins need to consume this API, the same-origin policy would block their requests. To facilitate cross-origin communication, we enable CORS in our web application. This allows it to:

1. Handle requests from different origins.

2. Bypass the browser's same-origin policy, ensuring that valid requests from external applications are accepted.

Without CORS, web browsers cannot make cross-origin requests, and it will give an error similar to this :

Acces to XMLHttpRequest at '{WebAPI_URL}' from origin '{ClientApp_URL}' has been blocked by CORS policy: No 'Acces-Control-Allow-Origin' header is present on the requested resource.

Example Scenario

Imagine you have a .NET Core Web API that handles user data for multiple client applications. These client applications might be hosted on different domains—let's say:

• https://app1.example.com

• https://app2.example.com

• https://mobile.example.com

In the provided scenario, I attempted hit the GetBooks method of a Web API from an Angular project without enabling CORS. As expected, it was blocked due to the same-origin policy.

To resolve this, I would need to enable CORS on the Web API, allowing requests from the Angular application’s origin. Let’s do it.

Fun Fact: A common misconception with CORS is that the request/call doesn't reach the server at all. However, the request does actually reach the server-side controller endpoint, but the browser blocks the response from being accessed by the front end due to the CORS policy.

How to Enable CORS in .NET

To properly handle CORS in a .NET web application, we need to define a list of allowed domains (origins) that can make requests to our API. A more flexible and maintainable approach is to store these allowed origins in the application's settings file, such as appsettings.json, and load them dynamically at runtime.

STEP-I: Store Allowed Domains in appsettings.json: Instead of hardcoding the allowed domains in the code, we can define them in the configuration file:

{
  "AllowedOrigins": [
    "https://app1.example.com",
    "https://app2.example.com",
    "https://mobile.example.com"
  ]
}

STEP-II: I've retrieved the array of allowed origins from the app settings and used them to register CORS services :

string allowedSpecificOrigins = "AllowSpecificOrigins";

WebApplicationBuilder? builder = WebApplication.CreateBuilder(args);

string[]? allowedOrigins = builder
                 .Configuration
                 .GetSection("AllowedOrigins")
                 .Get<string[]>();

builder.Services.AddCors(options =>
{
    options.AddPolicy(allowedSpecificOrigins,
        policy =>
           {
               policy.WithOrigins(allowedOrigins)
                     .AllowAnyMethod()
                     .AllowAnyHeader();
            });
});

builder.Services.AddControllers();

STEP-III: Enable CORS middleware :

app.UseCors(allowedSpecificOrigins);

Available Methods:

• AllowAnyOrigin: Permits requests from all origins without restriction.

• WithOrigins: Restricts requests to specific origins. You can pass one or more origins as arguments to this method.

• AllowAnyHeader: Permits requests with any headers.

• WithHeaders: Restricts requests to specific headers. You can pass one or more headers as arguments to this method.

• AllowAnyMethod: Permits requests with any HTTP method (e.g., GET, POST, PUT, DELETE).

• WithMethods: Restricts requests to specific HTTP methods. You can pass one or more methods as arguments to this method.

Important things to keep in mind about CORS

✔️ CORS is not a security feature. CORS is a W3C standard that allows a server to relax the same-origin policy.

✔️ An API isn’t safer by allowing CORS.

✔️ The order in which you register the CORS middleware is crucial. Ensure that the CORS registration is placed in the correct position within the middleware pipeline. Below is the default middleware order, including CORS :

Tap the ❤️ if you enjoyed this article—it motivates me to keep sharing more!

Have suggestions or thoughts to contribute?
Share them in the comments 💬. Your feedback is always valued and appreciated!

Share it with others who might benefit ♻️

There are 2 ways I can help you:

1. Enhance your .NET skills by subscribing to my YouTube Channel

2. Promote yourself to 9,000+ subscribers by sponsoring this newsletter

Implementation Links for Each .NET Library

Find the implementation links for each library under the relevant headings.

1- Mediator

Use Case: Implements the CQRS pattern for separating read and write operations.

Pros: Simplifies code structure, and promotes single responsibility.

According to Microsoft Docs:

CQRS stands for Command and Query Responsibility Segregation, a pattern that separates read and update operations for a data store.

Learn more about design patterns in simple explanations e.g. Facade Pattern, Null Object Pattern, Adapter Design Pattern, Decorator Pattern, Service Locator Pattern, and Repository Design Patterns

2- Dapper

Use Case: A micro-ORM for mapping database results to objects.

Pros: Lightweight, easy to use.

Trivia: You can use Entity Framework when you need a full-featured ORM with advanced capabilities like change tracking and migrations. Dapper is my first choice when I have to write lengthy SQL queries with a lot of tables and complex joins.

3- Serilog

Use Case: Logging frameworks for simple and structured logging (Serilog)

Pros: Flexible, supports various sinks (40+ sinks)

Trivia: If you require a more traditional logging framework then use NLog.

4- Bogus

Use Case: Generates fake data for testing and development.

Pros: Easy to use, customizable data generation.

Trivia: For simple applications, I would prefer to create my custom bogus implementation instead of going for a library.

5- Fluent Validation

Use Case: Validates models in a fluent interface style.

Pros: Clear syntax, easy to maintain.

Trivia: Use Data Annotations for simpler validation needs where built-in attributes suffice.

6- Refit

Use Case: Simplifying HTTP API calls in .NET applications.

Pros: Reduces boilerplate code for making HTTP requests.

Trivia: Refit under the hood use HttpClient

7- Health Checks

Use Case: Monitoring the health of applications and services

Pros: Provides a standardized way to observe the status of services, it can be integrated with monitoring tools for alerts. Additionally, it helps ensure application reliability and availability.

8,9- Hangfire and Quartz

Use Case: Background job processing.

Pros: Reliable, easy to schedule jobs, and helpful in complex scenarios.

Trivia: Use Background Services for simple use cases.

10- Noda Time

Use Case: Advanced date and time handling.

Pros: Comprehensive, handles time zones well.

Trivia: Use System.DateTime for simpler applications where advanced date-time handling is not required. BTW Jon Skeet is the owner of the Noda Time library

11- Autofac

Use Case: Dependency Injection container.

Pros: Flexible, supports advanced scenarios.

Trivia: Use Microsoft.Extensions.DependencyInjection for simpler dependency injection needs.

12- MiniProfiler

Use Case: Speed profiling of applications.

Pros: Easy to integrate, provides detailed insights.

Trivia: Use Application Insights if you need more comprehensive monitoring.

13- Mapster

Use Case: Object-to-object mapping.

Pros: Reduces boilerplate code, and improves maintainability.

Trivia: There is a big debate about mappers and custom mapping, and I have covered a few questions :

14- NSubstitute

Use Case: Mocking framework for unit testing.

Pros: Easy to set up, supports complex scenarios.

Trivia: I was a big fan of Moq but I quit because they were quietly collecting users' data

15- System.Text.Json

Use Case: JSON serialization/deserialization.

Pros: Mature, widely used, flexible, better performant

Trivia: NewtonSoft.Json is also a good option but I prefer System.Text.Json due to better performant.

16- BenchmarkDotNet

Use Case: Speed measurement of code.

Pros: Accurate, easy to use.

Trivia: It can be overkill for simple checks.

17- Swagger

Use Case: API documentation and testing.

Pros: Interactive documentation, easy to use.

Trivia: Use Postman Desktop Application, for API testing and documentation without the need for integrated solutions.

18- SignalR

Use Case: Real-time web functionality (e.g., chat applications).

Pros: Simplifies real-time communication, and supports various transports.

Use Web Sockets, if you need a more low-level approach to real-time communication without the overhead of a framework.

Tap the ❤️ if you enjoyed this article—it motivates me to keep sharing more!

Have suggestions or thoughts to contribute?
Share them in the comments 💬. Your feedback is always valued and appreciated!

Share it with others who might benefit ♻️

There are 2 ways I can help you:

1. Enhance your .NET skills by subscribing to my YouTube Channel

2. Promote yourself to 9,000+ subscribers by sponsoring this newsletter

Writing clean code is crucial for development. If writing code is art then writing clean code would be a masterpiece.

Check out the first post of the clean code tips series :

1- Give meaningful names

Using meaningful names makes code self-explanatory, reducing the need for additional comments.

Bad Example :

public class Emp
{
    public string n;
    public int a;

    public void d()
    {
       Console.WriteLine($"Name: {name}, Age: {age}");
    }
}

Good Example :

public class Employee
{
    public string name;
    public int age;

    public void DisplayInfo()
    {
        Console.WriteLine($"Name: {name}, Age: {age}");
    }
}

2- Avoid returning null

Returning null can lead to NullReferenceException errors when the caller attempts to access properties or methods on the returned object. It can also make the code harder to read and maintain, as the caller must always check for null before using the returned value.

Suppose we have this piece of code :

public class UserService
{
    public User? GetUserById(int id)
    {
        if (id <= 0)
        {
            return null; 
        }
        .... Rest logic of method ...
        return user;
    }
}

We can improve it with this, instead of returning null we can throw an exception and then handle it separately :

public sealed class UserService
{
    public User GetUserById(int id)
    {
        if (id <= 0)
        {
            // throws an exception instead of returning null
            throw new ArgumentException("Invalid user Id"); 
        }
        .... Rest logic of method ...
        return user;
    }
}

3- Keep class | method size small

A class should have one reason to change.

Smaller classes are easier to manage, test, and maintain.

At some points, this asks us to follow the Single Responsibility Principle.

Suppose we have this example in which we have a lot of code, with different concerns :

public sealed class OrderProcessing
{
    public void ProcessOrder(Order order)
    {
        if (!ValidateOrder(order))
        {
            throw new ArgumentException("Invalid order");
        }

        ChargePayment(order);
      
        UpdateInventory(order);

        SendConfirmationEmail(order);

        LogOrderDetails(order);
    }

    private bool ValidateOrder(Order order) {  }
    private void ChargePayment(Order order) {  }
    private void UpdateInventory(Order order) {  }
    private void SendConfirmationEmail(Order order) { }
    private void LogOrderDetails(Order order) { }
}

This could be improved like this where we have separate classes for each concern :

public sealed class OrderValidator
{
    public bool Validate(Order order){}
}

public sealed class PaymentProcessor
{
    public void Charge(Order order){}
}

public sealed class InventoryManager
{
    public void Update(Order order){}
}

public sealed class EmailService
{
    public void SendConfirmation(Order order){}
}

public sealed class OrderProcessing
{
    private readonly OrderValidator _validator;
    private readonly PaymentProcessor _paymentProcessor;
    private readonly InventoryManager _inventoryManager;
    private readonly EmailService _emailService;

    public OrderProcessing(
      OrderValidator validator, 
      PaymentProcessor paymentProcessor,
      InventoryManager inventoryManager,
      EmailService emailService)
    {
        _validator = validator;
        _paymentProcessor = paymentProcessor;
        _inventoryManager = inventoryManager;
        _emailService = emailService;
    }

    public void ProcessOrder(Order order)
    {
        if (!_validator.Validate(order))
        {
            throw new ArgumentException("Invalid order");
        }

        _paymentProcessor.Charge(order);
        _inventoryManager.Update(order);
        _emailService.SendConfirmation(order);
    }
}

Although there is no hard-code rule about how many lines of code a method should contain, 20-40 lines are enough for a method.

4- Don’t reinvent the wheel

Reinventing the wheel can lead to unnecessary duplication of effort, wasting valuable time and resources that could be better spent on developing unique features.

What exactly is reinventing the wheel, it means when we already have code for some issue and we start writing manually code to solve that cause then we are reinventing the wheel :

public sealed class CustomLogger
{
    public void Log(string message)
    {
        using (var writer = new StreamWriter("log.txt", true))
        {
            writer.WriteLine($"{DateTime.Now}: {message}");
        }
    }
}

We can achieve that by just injecting the ILogger interface, considering logging is already configured :

public sealed class Application
{
    private readonly ILogger _logger;

    public Application(ILogger logger)
    {
        _logger = logger;
    }
}

Read about how to implement logging in .NET :

• Logging with NLog

• Logging with Serilog

5- Use appropriate tools/IDE

Using the right tools or IDE enhances productivity by providing features like syntax highlighting, code completion, and error checking, which help catch mistakes early.

Keep reading the new update of Visual Studio, and invest time in learning about existing features of tools as well.

Additionally, these are two practices that I follow in my .NET projects, and I would recommend that you do the same:

1- Enabling Editor Config File

Enabling the editor config file in .NET projects to apply some sort of rules on all code

root = true

# C# files
[*.cs]

#### Core EditorConfig Options ####

# Indentation and spacing
indent_size = 4
indent_style = space
tab_width = 4

#### .NET Coding Conventions ####

# Organize usings
dotnet_separate_import_directive_groups = false
dotnet_sort_system_directives_first = true

2- Adding the props file

This props file is used to configure common settings and apply them across all projects for example:

<Project>
  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>
</Project>

Whenever you’re ready, there are 2 ways I can help you:

1. If you want to boost your .NET skills and do some code in action you can do that by subscribing to my YouTube Channel

2. Promote yourself to 11,000+ subscribers by sponsoring this newsletter

• What is the primary constructor?

• Understanding with example

• Benefits of using them

What is the primary constructor?

Primary constructors were introduced in .NET 8 and C# 12, a cleaner way of constructor initialization. We can use this syntax where we have a lot of constructor injections.

Understanding the Primary Constructor with Code

Let’s understand it with a simple example first before diving in depth. The older way of constructor injection :

public sealed class NewsletterService
{
    private readonly INewsletterRepository _newsletterRepository;

    public NewsletterService(INewsletterRepository newsletterRepository)
    {
        _newsletterRepository = newsletterRepository;
    }
}

This is how we can achieve the same with primary constructors:

internal class NewsletterService(INewsletterRepository newsletterRepository)
{
    public void Subscribe(string email)
    {
        newsletterRepository.Add(email);
    }
}

Pro(s) :

The following are the benefits of using primary constructors :

1. It removes a lot of boilerplate code

2. Simplifies the syntax

3. Much more readability

Whenever you’re ready, there are 2 ways I can help you:

1. If you want to boost your .NET skills and do some code in action you can do that by subscribing to my YouTube Channel

2. Promote yourself to 10400+ subscribers by sponsoring this newsletter

3. Patreon Community: Join and gain access to the 200+ articles I have published so far in one place. Join here

• What is the service locator pattern?

• When should we use it?

• How to use it in .NET

• Is using it a bad practice?

• Disadvantages

What is the service locator pattern?

We can inject any interface into the constructor and use it in dependency injection. The default dependency injection container in .NET will handle the instantiation and disposal of objects.

If, for some reason, we are unable to inject those interfaces and we need to resolve those dependencies, we can utilize the service locator pattern as a solution.

In this pattern, we inject our service provider into the class and we can retrieve the N number of services using that single provider.

When should we use this pattern?

There are situations where this pattern could be helpful, but it should be used wisely in the following cases:

1. When dealing with services scope mismatch issues

2. When working with an old code base that requires extensive changes for update

3. Sometimes when creating generic classes or maybe when types are not clear until runtime

How to use it in .NET?

We need to inject IServiceProvider in our desired class and then retrieve the required service by calling GetRequiredService method

public class UsersService
{
    private readonly IServiceProvider _serviceProvider;
	
    public UsersService(IServiceProvider ServiceProvider) 
    {
        _serviceProvider = ServiceProvider;
    }
}

Then we can use it at the controller level or method level :

public class UsersService
{
    private readonly IServiceProvider _serviceProvider;
    
    private readonly IUserRolesRepository _userRolesRepository;
	
    public UsersService(IServiceProvider ServiceProvider) 
    {
        _serviceProvider = ServiceProvider;
		
       _userRolesRepository =_serviceProvider
             .GetRequiredService<IUserRolesRepository>();
    }
	
    public void Method1()
    {
        var userRepository = _serviceProvider
                .GetRequiredService<IUserRepository>();
    }	
}

This is a very simple example of how we can use IServiceProvider, let’s move one step next.

Using a global implementation for a service provider

Instead of putting IServiceProvider everywhere, we can use a more universal approach by using a single class responsible for the services like this :

public class CachedServiceProvider 
{
	protected IServiceProvider ServiceProvider { get; }
	
	protected ConcurrentDictionary<Type, Lazy<object>> Services { get; }

	public CachedServiceProvider(IServiceProvider serviceProvider)
	{
	   ServiceProvider = serviceProvider;
		
	   Services = new ConcurrentDictionary<Type, Lazy<object>>();
		
	   Services
             .TryAdd(typeof(IServiceProvider), new Lazy<object>(() =>                ServiceProvider));
	}

	public virtual object GetService(Type serviceType)
	{
		return Services.GetOrAdd(
		  serviceType,
			_ => new Lazy<object>(() =>        ServiceProvider.GetService(serviceType)!)
		).Value;
	}
}

Using this approach our single class is responsible for providing services, and then we are using a dictionary to cache the services so the same service is not created again and again.

By using a concurrent dictionary we are making sure that it can accessed by multiple threads concurrently.

Is it bad practice to use this pattern?

Going with direct dependency injection should always be the first option because that is much cleaner, manageable, and easy to unit test.

But if that is not possible then we can opt for this pattern, like every pattern this also has some cons. But we can not say that using this is bad because it depends on the situation and use case.

Disadvantages of this pattern?

These are the disadvantages of using this pattern:

1. The biggest issue is testing, mocking and testing can become more complex because the service locator is often a singleton or a global instance.

2. It can make dependencies less obvious, as they are not directly visible in the code where services are used.

3. Over-reliance on the service locator can lead to poor design choices, where everything is fetched from the locator, leading to an anemic domain model

Whenever you’re ready, there are 2 ways I can help you:

1. If you want to boost your .NET skills and learn more about .NET you can do that by subscribing to my YouTube Channel

2. Promote yourself to 10400+ subscribers by sponsoring this newsletter

“To praise the sun is to praise your own eyes.” - Rumi

Dapper is an opensource performant ORM (Object Relational Mapping) library used extensively in the .NET world

If you want to learn how we can use it in .NET, read this article :

How to use Dapper in .NET 6.0 for CRUD Operations

• Adding an entity for the demo

• Introducing value type

• Handling conversion in configuration

• Querying data with Dapper

• Create type handler

Basic User Entity

We can take an example of a basic user entity, which contains a couple of properties :

public sealed class User
{
    public Guid Id { get; private set; }

    public string Name { get; private set; } = string.Empty;

    public string Email { get; private set; }

    public string PasswordSalt { get; private set; } = string.Empty;

    public string PasswordHash { get; private set; } = string.Empty;
}

Introducing Value Types

After a couple of time, we have decided to introduce value types in our project for example in the current situation we could add an Email value type like this :

public sealed record Email(string Value)
{
    public static Email Empty => new(string.Empty);
}

We could introduce multiple value types and a proper type for each type on the same pattern. So after this change, our User class would look like this:

public sealed class User
{
    public Guid Id { get; private set; }

    public string Name { get; private set; } = string.Empty;

    public Email Email { get; private set; }

    public string PasswordSalt { get; private set; } = string.Empty;

    public string PasswordHash { get; private set; } = string.Empty;
}

Handling Conversion in Configuration

We need to add configuration so that type can be handled automatically in the configuration class of our entity like this :

internal class UserConfiguration : IEntityTypeConfiguration<User>
{
    public void Configure(EntityTypeBuilder<User> builder)
    {
        builder.Property(user => user.Email)
            .HasMaxLength(400)
            .HasConversion(email => email.Value, value => new Email(value))
            .IsRequired();
    }
}

Querying data with Dapper

Suppose this is our example where we are trying to retrieve a user using Dapper.

Let’s ignore the discussion that I could have used EF Core, let’s suppose this query is much more complex and I am displaying this for the sake of how we can solve complex types of problems.

This code will throw an error right something similar to this :

Error is fine because the database Email type is a string, not the Email type we defined. This is where the type handler comes to the rescue.

How to create a type handler in .NET?

Type handlers handle complex types and parse them as per needs.

We can utilize SqlMapper.TypeHandler<T> from dapper for such a purpose.

Let’s create our Email type handler to resolve our issue :

This will take care of the conversion for us, you can add a debugger to make sure, it works.

The last thing is to register this type of handler with DI :

Whenever you’re ready, there are 2 ways I can help you:

1. Promote yourself to 10400+ subscribers by sponsoring this newsletter

2. Patreon Community: Read 200+ articles I have published so far in one place.