DEV Community: Kazem

ABP and Elsa Both Want to Own Your API: Pick One

Kazem — Wed, 26 Aug 2026 03:38:51 +0000

When I scaffolded my project, an enterprise workflow platform on ABP Framework, Elsa 3.x, EF Core, and PostgreSQL, I ran into a problem that never shows up in either framework's docs, because each framework assumes it's the only one in the room.

ABP wants you to expose functionality through application services. That's the whole point of the framework: you write a C# class, decorate it with a permission attribute, and ABP auto-generates a REST controller for it. No manual routing, no manual DTO wiring if you let AutoMapper profiles do the work.

Elsa also wants to expose functionality over HTTP. It ships an HttpEndpoint activity that lets a workflow itself define a route, accept a request, and respond, no ASP.NET controller involved at all. You drop the activity into a workflow definition and Elsa wires up the endpoint for you.

Put those two together on the same project and you get two frameworks each offering to be your public API. That's not a hypothetical: it's what I had in front of me the day I needed to expose "start an approval workflow" and "complete a human task" to the rest of the system. Elsa would happily let me do it inside the workflow definition. ABP would happily let me do it as an application service. Pick wrong and you end up with two different ways to call what is conceptually the same operation: discoverable through two different mechanisms, secured by two different permission systems, versioned (or not) by two different conventions.

Why this is worse than it sounds

The obvious reaction is "just pick one and move on." The problem is that Elsa's HttpEndpoint is convenient in a way that's easy to fall for. You're already inside the workflow definition, you already have the business logic for what happens when a request comes in, and Elsa gives you a working route with zero extra files. For a demo, or a single standalone workflow, that's a fine trade.

But ProcessHub isn't a single workflow. It's a platform where workflows are one implementation detail behind an approval-task inbox, an audit trail, role-based access, and caching. The moment you let Elsa own the public boundary for even one endpoint, you've committed to two rules for how the outside world talks to your system:

"For approval submission, call this ABP application service, which is authorized by an ABP permission, logged by the ABP audit system, and documented by the ABP Swagger integration."
"For task completion, call this Elsa HttpEndpoint, which is authorized however that workflow definition wired it up, logged wherever Elsa's execution log happens to write it, and documented nowhere in particular."

Neither rule is wrong in isolation. Together, they mean every new integration has to ask "wait, is this one of the Elsa-exposed operations or an ABP one?" before it can even find the right client to call. That's the kind of inconsistency that looks small in a design doc and turns into a support ticket six months later when someone can't find the endpoint for a feature they know exists.

The rule I landed on

The public boundary is the application service, not the workflow engine's own endpoints. Elsa runs entirely behind that boundary. No HttpEndpoint activities, no direct client-to-Elsa communication of any kind.

Concretely, that means the approval flow looks like this:

public class WorkflowTaskAppService : ApplicationService, IWorkflowTaskAppService
{
    private readonly IApprovalTaskRepository _tasks;
    private readonly IRunTaskRequestHandler _runTaskHandler;

    [Authorize(ProcessHubPermissions.Tasks.Complete)]
    public async Task CompleteAsync(CompleteTaskInput input)
    {
        var task = await _tasks.GetAsync(input.TaskId);

        // ApprovalTask is our own aggregate, not Elsa's execution state.
        task.Complete(CurrentUser.Id, input.Decision, input.Comment);
        await _tasks.UpdateAsync(task);

        // Resume the suspended Elsa workflow through our handler,
        // not through any endpoint Elsa exposes itself.
        await _runTaskHandler.ResumeAsync(task.WorkflowInstanceId, input.Decision);
    }
}

The workflow itself contains a RunTask activity that suspends execution and waits. Nothing about that activity is reachable from outside the process. The only door in is WorkflowTaskAppService, authorized by an ABP permission (ProcessHubPermissions.Tasks.Complete). It shows up in the same Swagger document as every other endpoint in the system, and it gets logged by the same audit tables that log everything else: the append-only domain tables I built independent of Elsa's own execution log, specifically so audit history doesn't depend on which engine happens to be running underneath.

ApprovalTask is worth calling out too. It's a domain aggregate I own, not Elsa's workflow instance state. The application service reads and writes it directly. Elsa's job is to drive the state machine that decides when a task becomes eligible and what happens after it's resolved. It doesn't get to be the system of record for what the task inbox shows a user.

Why the "just use both" instinct is wrong here

I get why the instinct is to use HttpEndpoint for anything workflow-shaped and application services for everything else. It feels like using each tool for what it's good at. But that's a category error. HttpEndpoint is good at "this workflow needs to react to an inbound webhook from a third party who doesn't know or care about your internal architecture." It is not good at "this is a first-class operation my own frontend calls," because it opts that operation out of every convention ABP gives you for free: permission checks, DTO validation, Swagger docs, the audit trail, the unit-of-work interceptor that wraps SaveChanges around the request.

Once I framed it that way, the rule got easy to defend in code review. If the caller is internal, meaning my own UI or my own downstream services, it goes through an application service, full stop. If the caller is a genuinely external system triggering a workflow with no other integration in the codebase (say, a webhook from a payment provider), HttpEndpoint is fine, because there's no ABP convention being bypassed. There was never an ABP endpoint for that caller anyway.

The Native AOT wrinkle, and why it doesn't change the answer

There's a second reason application services stay the boundary, and it's less about design taste and more about what ABP actually costs you. ABP builds application services on dynamic proxies and interceptors: the unit-of-work wrapper, the auto-validation, the auditing all run through interception at runtime. That's convenient, but it means Native AOT is off the table for this codebase. If you're chasing trimmed, ahead-of-time-compiled binaries, ABP's application service layer isn't going to get you there.

It also means unit-testing an application service in true isolation is awkward. Mock the repository, call the method directly, and you've bypassed the interceptor pipeline that does half the actual work (the unit-of-work commit, the auditing, the authorization check). I stopped fighting that and write integration tests through the HTTP boundary instead, hitting the real controller ABP generates. Slower than a pure unit test, but it's testing the thing that's actually going to run in production, interceptors included.

None of that pushed me toward letting Elsa own more of the surface. If anything it reinforced the opposite: if application services are going to cost me AOT and force integration-style testing, I want that cost paid once, at one consistent boundary, not paid partially while a second boundary quietly exists elsewhere with different rules.

The general version of this

If you're bringing ABP into a project that already has an opinionated engine underneath it, whether that's a workflow engine, a job scheduler, or a message bus with its own HTTP hooks, check whether that engine wants to expose its own API surface. A lot of them do, because it's a nice feature to advertise in isolation. Almost none of them coordinate with whatever else in your stack is also trying to be "the" API.

The fix isn't a framework setting. It's a decision you make explicitly and write down: one thing owns the public boundary, and everything else, no matter how convenient its shortcut looks, runs behind it. On ProcessHub that's the ABP application service layer: modules instead of Program.cs registrations, permission attributes instead of manual IAuthorizationService checks, with Elsa treated as an internal state machine and nothing more. It's a small rule. It's also the one I've had to re-explain the most, because the alternative always looks like less code in the moment you're writing it.

The .NET Production Checklist Is Really a List of Places the Framework Lies to You

Kazem — Wed, 26 Aug 2026 03:37:41 +0000

Most of this checklist isn't about .NET at all. It's a list of every place the framework's defaults will quietly hurt you in production, because the happy path was built to make dotnet run work on your laptop, not to survive three replicas behind a load balancer with a database that has a connection limit.

None of these are exotic problems. They're the kind of thing you only learn by getting paged for them once.

Migrations: the happy path runs them on every replica

The default story is simple: your app starts up, EF Core applies pending migrations, you're live. It works great with one instance.

It falls apart the moment you scale past one. Three replicas start at roughly the same time, all three try to apply the same migration, and now you're debugging a race condition in your schema instead of your code. Sometimes it's harmless: the migration is idempotent, one replica wins, the others fail quietly and move on. Sometimes it isn't, and you get a half-applied schema or a deadlock on the migrations history table.

The fix is boring: migrations run as a single deploy step, not as part of application startup. One job, one shot, before any replica of the new version starts serving traffic. It's less convenient than "it just happens," but "it just happens" is exactly the kind of behavior that's fine until it isn't.

Health checks: "alive" and "ready" are not the same question

/health as a single endpoint answers one question badly. What you actually need are two different questions with two different consequences:

Is the process alive? (Should Kubernetes restart the pod?)
Is the process ready to take traffic? (Should the load balancer route to it?)

A service can be alive and not ready — it's up, but its database connection is down, or it's still warming a cache. If your only health check conflates the two, either you route traffic to a pod that can't serve it, or you restart a pod that's actually fine and just waiting on a dependency to come back.

Split them: /health/live checks that the process itself is up. /health/ready checks that its dependencies are reachable. Only /health/ready gates traffic. This is a small amount of extra wiring for a failure mode that otherwise shows up as "why did we get 500s during a routine dependency blip."

Shutdown: three timeouts, each one has to be bigger than the last

Graceful shutdown looks like it should be free — the framework gives you IHostApplicationLifetime, you hook ApplicationStopping, done. But shutdown in a container orchestrator is actually a chain of three separate timeouts, and if you only configure the first one, the other two will cut you off anyway:

IHostApplicationLifetime: your code's chance to stop accepting new work and finish what's in flight.
ShutdownTimeout: how long the host waits for that to happen before it forces termination. This has to be set above your longest in-flight request, or the host kills requests that were about to finish cleanly.
terminationGracePeriodSeconds: how long Kubernetes waits before sending SIGKILL. This has to be set above ShutdownTimeout, or Kubernetes kills the process before your own shutdown timeout even gets a chance to fire.

Get the ordering wrong and you'll see intermittent failed requests during every deploy, and they'll look like application bugs. They're not. They're a shutdown grace period that's smaller than the request it was supposed to protect.

Connection pools: the number that has to be true across every replica

This one is a simple formula that's easy to forget applies at all once you're running more than one instance:

Max Pool Size × replicas < DB max_connections

A pool size of 100 is fine for one replica against a database that allows 200 connections. Scale to three replicas and you're asking for 300 connections against a limit of 200. That shows up as intermittent connection exhaustion under load, usually during a traffic spike, which is exactly when you have the least patience for debugging it.

Pair this with actual resiliency: EnableRetryOnFailure() for transient database errors, and a standard resilience handler on your outbound HTTP clients. Networks fail. The question is whether your service treats that as routine or as an unhandled exception.

The runtime image: no SDK, no root

FROM mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled AS runtime
WORKDIR /app
COPY out .
USER $APP_UID
ENTRYPOINT ["./Sample.Api"]

Two things happen here that are easy to skip if you just want a working Dockerfile. This is a chiseled/distroless image: no shell, no package manager, no SDK, nothing beyond what the app needs to run. If someone gets code execution inside the container, there isn't much there to pivot with. On top of that, USER $APP_UID runs the process as a non-root user instead of the container default.

Neither of these makes the app faster or fixes a bug you'll notice in staging. They're the difference between a compromised container being a dead end and being a foothold. The publish step that gets you here is also worth keeping:

dotnet publish src/Sample.Api -c Release -o out /p:PublishReadyToRun=true

PublishReadyToRun=true precompiles a chunk of the IL to native code ahead of time, which matters for the next item.

Warm-up: the first requests are the slowest ones

.NET JITs your code as it runs: tier-0 first, optimizing later tiers as methods get hot. That's a reasonable tradeoff for a long-running process. It's a bad one for the first few requests a brand-new pod receives, because those requests get compiled cold, right when they're also the ones deciding whether your rollout looks healthy.

The fix is to send a warm-up request after deploy, before the pod joins the load balancer. It costs a few seconds. What it buys you is not showing your actual users the slowest version of every code path, right as a new deploy goes live.

Everything else on the list is the same pattern

Structured logging to stdout, so your log aggregator doesn't have to parse whatever format someone chose two years ago. OpenTelemetry traces and metrics with a correlation ID that survives a hop across services, so a slow request can actually be traced instead of guessed at. Response compression and output caching where they pay off, not everywhere, just where the numbers say so. Resource limits and DOTNET_GCHeapHardLimitPercent set explicitly, because an unbounded GC heap in a container with a memory limit is just a slower way of getting OOMKilled. Backups verified by an actual restore, because a backup nobody has restored is a hope, not a backup.

None of these are interesting individually. What they have in common is that they're all invisible until the day they aren't — and by then it's an incident, not a checklist item.

The CI gate that keeps this from being a one-time exercise

The checklist part is only half of it. None of it stays true unless CI enforces it on every change:

dotnet format --verify-no-changes → dotnet build -warnaserror → dotnet test → vulnerability scan

Format check first, so style drift doesn't show up as noise in review. Build with warnings as errors, so a warning today doesn't become a bug next quarter because everyone got used to ignoring the build output. Tests. Then a vulnerability scan against your dependencies, because dotnet list package --vulnerable catching something in CI is a much better day than catching it after it's in production.

The tooling underneath is less important than the discipline of running it on every PR instead of remembering to run it manually before a release: CSharpier or dotnet format for formatting, Roslyn analyzers and SonarAnalyzer for static analysis, NetArchTest or ArchUnitNET if you want architecture rules enforced by a test rather than a code review comment, and Husky.NET for pre-commit hooks.

Why this checklist reads the way it does

Every item here comes from the same root cause: the defaults optimize for one instance on your machine, not for several instances that all have to agree on the same schema, the same connection budget, and the same shutdown sequence at once. Add an orchestrator with its own lifecycle rules on top, and that gap becomes the whole checklist.

None of this is specific to .NET's quirks. It's what "production" means once more than one thing has to agree on the state of the world at the same time.

The .NET Production Checklist Is Really a List of Places the Framework Lies to You

Kazem — Tue, 25 Aug 2026 12:13:17 +0000

None of these are exotic problems. They're the kind of thing you only learn by getting paged for them once.

Migrations: the happy path runs them on every replica

The default story is simple: your app starts up, EF Core applies pending migrations, you're live. It works great with one instance.

Health checks: "alive" and "ready" are not the same question

/health as a single endpoint answers one question badly. What you actually need are two different questions with two different consequences:

Is the process alive? (Should Kubernetes restart the pod?)
Is the process ready to take traffic? (Should the load balancer route to it?)

Shutdown: three timeouts, each one has to be bigger than the last

IHostApplicationLifetime: your code's chance to stop accepting new work and finish what's in flight.
ShutdownTimeout: how long the host waits for that to happen before it forces termination. This has to be set above your longest in-flight request, or the host kills requests that were about to finish cleanly.
terminationGracePeriodSeconds: how long Kubernetes waits before sending SIGKILL. This has to be set above ShutdownTimeout, or Kubernetes kills the process before your own shutdown timeout even gets a chance to fire.

Connection pools: the number that has to be true across every replica

This one is a simple formula that's easy to forget applies at all once you're running more than one instance:

Max Pool Size × replicas < DB max_connections

The runtime image: no SDK, no root

FROM mcr.microsoft.com/dotnet/aspnet:10.0-noble-chiseled AS runtime
WORKDIR /app
COPY out .
USER $APP_UID
ENTRYPOINT ["./Sample.Api"]

dotnet publish src/Sample.Api -c Release -o out /p:PublishReadyToRun=true

PublishReadyToRun=true precompiles a chunk of the IL to native code ahead of time, which matters for the next item.

Warm-up: the first requests are the slowest ones

Everything else on the list is the same pattern

None of these are interesting individually. What they have in common is that they're all invisible until the day they aren't — and by then it's an incident, not a checklist item.

The CI gate that keeps this from being a one-time exercise

The checklist part is only half of it. None of it stays true unless CI enforces it on every change:

dotnet format --verify-no-changes → dotnet build -warnaserror → dotnet test → vulnerability scan

Why this checklist reads the way it does

None of this is specific to .NET's quirks. It's what "production" means once more than one thing has to agree on the state of the world at the same time.

Never Use UseInMemoryDatabase in ASP.NET Tests

Kazem — Tue, 25 Aug 2026 12:04:25 +0000

A test suite can pass completely against UseInMemoryDatabase and still break the moment the same code runs against real Postgres. Green checkmarks, CI happy, PR merged — and then a query that relied on a foreign key constraint does the wrong thing in production, because nothing in the test run had a foreign key to enforce.

That's the one rule in ASP.NET testing I don't compromise on: never test against UseInMemoryDatabase. It's not a relational database. No constraints, no transactions, and its LINQ translation doesn't match what EF Core actually generates against Postgres or SQL Server. You get green tests that lie to you about what happens in production.

Why the in-memory provider fails you

EF Core's in-memory provider was built for quick prototyping, not for verifying behavior. It stores your entities in a plain in-memory collection and evaluates LINQ against that collection using regular .NET semantics. That sounds convenient until you remember that a real database doesn't work that way.

A unique index violation, a cascade delete, a check constraint, a NOT NULL column — none of that exists in the in-memory provider. Your test can happily insert two rows that would collide on a unique constraint in Postgres, and it'll pass. A query that translates to a specific SQL expression against Npgsql might translate completely differently against the in-memory LINQ provider, or not translate at all. A bug in your query gets masked because the fake provider is more forgiving than the real one.

Transactions are the other big gap. If your code relies on transactional rollback, or on isolation between concurrent operations, the in-memory provider gives you none of that. So you end up testing a database that behaves nothing like the one your users hit.

What to use instead

Testcontainers. Spin up a real Postgres instance in a container for the test run, and point EF Core at it like you would in production.

// Real Postgres per test run — not an in-memory provider
public sealed class ApiFactory : WebApplicationFactory<Program>, IAsyncLifetime
{
    private readonly PostgreSqlContainer _db = new PostgreSqlBuilder()
        .WithImage("postgres:17-alpine").Build();

    protected override void ConfigureWebHost(IWebHostBuilder builder)
        => builder.ConfigureTestServices(services =>
        {
            services.RemoveAll<DbContextOptions<AppDbContext>>();
            services.AddDbContext<AppDbContext>(o => o.UseNpgsql(_db.GetConnectionString()));
            services.AddSingleton<TimeProvider>(new FakeTimeProvider());
        });

    public async Task InitializeAsync() { await _db.StartAsync(); /* apply migrations */ }
    public new async Task DisposeAsync() => await _db.DisposeAsync();
}

ApiFactory boots the real ASP.NET pipeline through WebApplicationFactory<Program>, but swaps the database connection to point at a containerized Postgres instead of whatever's configured for the app normally. Same constraints, same transaction behavior, same SQL your production database will actually run.

The pyramid, ASP.NET-flavored

Once you accept that integration tests need a real database, the shape of your test suite follows from that.

Integration tests (~60%) — this is where most of the value is. WebApplicationFactory<Program> boots the real pipeline in memory, but against a real database in a container. You're exercising the actual HTTP pipeline, the actual EF Core mappings, the actual constraints. Highest value per line, and it's basically the same idea as Laravel feature tests, if you're coming from that world.

Unit tests (~35%) — domain rules, calculators, validators, mappers. No I/O, so they're fast. This is where you test the logic that doesn't need a database or an HTTP request to verify.

E2E (~5%) — Playwright, reserved for the handful of flows that must never break. Login, checkout, whatever your equivalent is. E2E tests are slow and brittle by nature, so you don't want your whole suite living here.

Here's what a couple of integration tests look like against ApiFactory:

public sealed class PostApiTests(ApiFactory factory) : IClassFixture<ApiFactory>
{
    [Fact]
    public async Task Creates_a_post_for_an_authenticated_user()
    {
        var client = factory.CreateAuthenticatedClient(userId: TestUsers.Author);

        var response = await client.PostAsJsonAsync("/api/posts",
            new { title = "Hello", body = "World" });

        response.StatusCode.ShouldBe(HttpStatusCode.Created);

        var dto = await response.Content.ReadFromJsonAsync<PostDto>();
        dto!.Title.ShouldBe("Hello");
    }

    [Fact]
    public async Task Forbids_editing_someone_elses_post()
    {
        var post = await factory.SeedAsync(new PostBuilder().WithAuthor(TestUsers.Other));
        var client = factory.CreateAuthenticatedClient(userId: TestUsers.Author);

        var response = await client.PutAsJsonAsync($"/api/posts/{post.Id}", new { title = "Hacked" });

        response.StatusCode.ShouldBe(HttpStatusCode.Forbidden);
    }
}

Notice what these tests actually assert on: HTTP status codes and response bodies. Not internal method calls, not whether some service was invoked with the right arguments. You go through the HTTP boundary the same way a real client would. If you start asserting on internal call sequences instead, your tests become coupled to implementation details, and refactoring turns into a chore even when behavior hasn't changed.

The supporting rules

A few things make this pyramid work in practice, beyond just using Testcontainers.

Test data should come from builders, not raw object initializers scattered through every test file. new PostBuilder().WithAuthor(TestUsers.Other) in the second test above is the ASP.NET equivalent of a Laravel factory: a readable way to construct exactly the entity state a test needs.

Isolation matters just as much. Wrap each test in a transaction and roll it back, or reset the database between runs with something like Respawn. What you don't want is shared mutable seed data that one test can quietly corrupt for the next one, because that's how you end up with tests that pass individually and fail when run together, one of the more annoying categories of flakiness to debug.

Time-dependent code needs a FakeTimeProvider instead of assertions built around DateTime.UtcNow. If your code branches on expiry windows or scheduling, you want that time to be a value you control in the test, not whatever the clock happens to say when CI runs. ApiFactory above registers FakeTimeProvider as a singleton for exactly this reason.

And outbound HTTP calls should be faked with a stub HttpMessageHandler or WireMock.NET. A test suite that hits the real internet is a flaky suite, full stop. Any external call, whether a third-party API or a webhook, should be intercepted at the HTTP client level so your tests aren't at the mercy of some other service's uptime.

The toolchain

xUnit is the default runner choice, though NUnit and MSTest work fine if that's what a codebase already uses. Shouldly or FluentAssertions handle assertions. Worth checking FluentAssertions' license terms before using it commercially, since those changed. Mocking is NSubstitute or Moq, take your pick.

None of these choices matter as much as the database decision. You can swap test runners and assertion libraries without much consequence. But if your integration tests run against UseInMemoryDatabase, you don't actually know what your code does against Postgres — you know what it does against a LINQ-over-a-list emulation of a database, which is a different thing that happens to share an interface.

The fix isn't complicated. Testcontainers spins up and tears down fast enough that it doesn't meaningfully slow your suite down, and the confidence it buys you is the whole point of writing integration tests in the first place. If your tests aren't telling you the truth about production, they're not saving you the time debugging in production later — they're just moving the debugging to a worse moment.

Async in .NET Has Traps Laravel Never Prepared Me For

Kazem — Tue, 25 Aug 2026 11:48:06 +0000

Most of the move from Laravel to .NET has been mechanical: different syntax, same instincts. Controllers are controllers, dependency injection is dependency injection, an ORM is an ORM. Async is where that stops working. It has no Laravel equivalent, and it's where most of the incidents I've seen actually come from.

PHP doesn't have this problem because PHP doesn't really have this concept. A request comes in, runs on its own process or thread, and there's no shared thread pool to starve. .NET's async model is built around a shared thread pool, and if you get async wrong, you're not just writing slower code. You can deadlock the request, swallow an exception the process never tells you about, or run the server out of sockets under load.

Blocking on async code

// ❌ deadlock / thread-pool starvation under load
var user = _service.GetUserAsync(id).Result;

This line looks harmless. It compiles, it works in dev, it might even work in production for a while under light load. Then traffic goes up and requests start hanging.

.Result blocks the calling thread until the async call finishes. Under load, the thread pool is busy running other requests, and the continuation for GetUserAsync is waiting for a free thread to resume on. If the pool is saturated, that continuation never gets scheduled, the blocked thread never unblocks, and you've got a deadlock. At minimum you get thread-pool starvation, where things slow down instead of failing outright, which is actually worse to diagnose.

The fix is not clever:

// ✅
var user = await _service.GetUserAsync(id, ct);

Async all the way down. The moment you mix in one blocking call, you've undone the point of using async in the first place. It's not a style preference. A single .Result or .Wait() buried three layers deep in an otherwise-async call chain is enough to bring a whole request path down under load.

`async void`

// ❌ exception is unobservable, process may crash
public async void Handle(Event e) { ... }

async void exists for one legitimate case: UI event handlers, where the framework calls you and there's nowhere to await. Everywhere else it's a trap. An exception thrown inside an async void method doesn't propagate the way you'd expect. It doesn't get captured by the caller's try/catch. It gets rethrown on the synchronization context, and for a lot of hosting models that means it can crash the process outright.

Compare that to an async Task method: exceptions get captured in the returned Task, and the caller can await it, catch it, log it, whatever. An async void method just fires the exception into the void.

// ✅
public async Task HandleAsync(Event e, CancellationToken ct) { ... }

Same shape, completely different failure behavior. If you're wiring up an event handler and it's not a UI callback, it should return Task.

A new `HttpClient` per call

// ❌ new HttpClient per call → socket exhaustion
using var http = new HttpClient();

This one's sneaky. HttpClient implements IDisposable, so the using block looks like correct, responsible code. It isn't. Disposing an HttpClient doesn't immediately release the underlying socket. It goes into a TIME_WAIT state. Do this on every request and under enough load you exhaust the available sockets on the box, and now everything making outbound HTTP calls starts failing, not just this one client.

The usual next move people make is to fix that by making the HttpClient static and reusing it forever. That solves socket exhaustion but introduces a different bug: a static HttpClient doesn't respect DNS changes, because the connection stays pinned to whatever IP it resolved first. If the downstream service moves (a failover, a DNS update, a container restart behind a load balancer), your static client keeps hammering the old address.

The actual fix is IHttpClientFactory:

// ✅
builder.Services.AddHttpClient<IPaymentClient, PaymentClient>()
    .AddStandardResilienceHandler();     // retry + circuit breaker + timeout

It manages the connection pool for you, rotates handlers on a schedule so DNS changes get picked up, and AddStandardResilienceHandler() gives you retry, circuit breaker, and timeout behavior in one line. There's no manual HttpClient lifecycle to get wrong.

The rules that fall out of this

Once you've been burned by these a couple of times, they collapse into a short list I now just follow by default:

Async all the way down. One blocking call anywhere in the chain undoes the benefit of everything above it and can deadlock the request.

Take a CancellationToken in every async method and pass it on. If the client disconnects, that should stop costing you a database connection. Threading the token through every layer is tedious the first few times and then it's just muscle memory.

IHttpClientFactory, always. Manual HttpClient instances exhaust sockets. A static one misses DNS changes. There isn't a third option that's actually safe.

Nothing mutable in a singleton without a real concurrency primitive. ConcurrentDictionary, SemaphoreSlim, Channel<T>, Interlocked: pick the one that fits, but don't put a plain Dictionary or a counter on a singleton and assume it'll be fine because it worked in local testing with one user.

Background work belongs in BackgroundService/IHostedService, or better, a durable queue. Hangfire, Quartz, a real broker. Task.Run(...) and forget feels fine in dev and then dies with the pod on a rolling deploy, taking whatever it was doing with it. If the work needs to actually complete, it needs to survive a restart, and Task.Run doesn't.

For caching, HybridCache, in-process plus distributed with stampede protection, is the current default answer. IDistributedCache with Redis covers cross-instance state when you need something simpler or already have Redis in the stack.

None of these are exotic. They're all things the framework already gives you a correct way to do. The trap isn't that .NET makes async hard, it's that the wrong version of each of these compiles, runs, and looks identical to the right version until the thread pool is under real load. Laravel never put me in that position, because it never had a shared thread pool to starve.

Authorize Can't See Your Data

Kazem — Tue, 25 Aug 2026 11:18:48 +0000

The first authorization bug I ever shipped wasn't a missing [Authorize] attribute. It was the opposite — everything had [Authorize], the tests were green, and it still let one user edit another user's stuff. The attribute was doing exactly what it promised. I just wanted it to promise something else.

That's the gap that trips people up: [Authorize] answers "is this user allowed to hit this endpoint." It has no idea "is this user allowed to touch this specific row." Those are two different questions, and ASP.NET Core gives you two different tools for them.

Authentication first, briefly

Before authorization, there's the "who are you" question, and the answer depends on who's asking:

Scenario	Approach
Internal API behind corporate SSO	OIDC via Entra ID / Keycloak, JWT bearer
Public API for third parties	JWT bearer + a proper identity provider (Duende, Keycloak, Auth0)
Server-rendered app	Cookie authentication + ASP.NET Core Identity
Service-to-service	Client credentials flow, or mTLS inside the cluster

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(o =>
    {
        o.Authority = builder.Configuration["Auth:Authority"];
        o.Audience  = "sample-api";
        o.TokenValidationParameters = new()
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromSeconds(30)   // default 5 min is too generous
        };
    });

Notice the ClockSkew. The default is five minutes, which is generous enough that an expired token can still get through for a while after it should have died. Worth tightening on anything that matters.

And don't hand-roll token issuance or password hashing. Use an identity provider, or ASP.NET Core Identity, which already does PBKDF2/Argon2-grade hashing, lockout, and 2FA. This isn't the place to prove you can implement crypto yourself.

Where policy-based authorization stops

Once you know who the user is, [Authorize] policies handle the "what role can hit what endpoint" layer well:

builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("CanPublish", p => p.RequireClaim("permission", "posts.publish"));
    o.AddPolicy("Adults", p => p.Requirements.Add(new MinimumAgeRequirement(18)));
    o.FallbackPolicy = new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build();
});

[Authorize(Policy = "CanPublish")]
public async Task<IActionResult> Publish(Guid id) { ... }

This works fine for "can this role publish posts at all." It falls apart the moment the question becomes "can this user publish this post." [Authorize] runs before the action method does anything. It never loaded the post, so it has nothing to check the user against — it can only see claims and roles, not data.

This is the same shape of problem as a Laravel policy, if you've worked in that world. A policy method takes the model instance and the user and decides together. [Authorize] alone can't do that, because by the time it runs, there's no instance yet.

Resource-based authorization

The fix is IAuthorizationService, called after the resource is loaded, with the resource passed in as an argument:

public sealed class PostAuthorizationHandler
    : AuthorizationHandler<OperationAuthorizationRequirement, Post>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext ctx,
        OperationAuthorizationRequirement requirement,
        Post resource)
    {
        if (resource.AuthorId.ToString() == ctx.User.FindFirstValue(ClaimTypes.NameIdentifier))
            ctx.Succeed(requirement);

        return Task.CompletedTask;
    }
}

// In the handler, once the resource is loaded:
var result = await authorization.AuthorizeAsync(User, post, Operations.Update);
if (!result.Succeeded) return Forbid();

[Authorize] alone cannot express "the owner of this post," because it doesn't have the post. Anything instance-specific goes through IAuthorizationService: load the resource first, then ask the authorization service whether this user can do this operation on this specific instance. It's a deliberate two-step. The decision genuinely depends on data that only exists once you've queried it, so there's no way to collapse it into a single attribute.

I ran into this exact shape while building the approval workflow core for on my current project. Tasks get completed through a WorkflowTaskAppService, and the access check there has to look past the role claim: is this specific task assigned to this user, or does their role let them act on it. That can't happen at the attribute level. It happens after the ApprovalTask is loaded, against that instance. same reasoning as the Post example, different domain.

Anonymous should be the exception, not the default

The FallbackPolicy line in the snippet above is easy to skip past, but it's doing real work:

o.FallbackPolicy = new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build();

Without it, any endpoint without an explicit [Authorize] is open by default. With it, the default flips: everything requires authentication unless you explicitly mark it [AllowAnonymous]. Forgetting [Authorize] on one new controller is the classic way to ship an open endpoint. A fallback policy turns that mistake from silent to loud — a forgotten attribute now means "user gets a 401," not "endpoint quietly accepts anyone."

It's a small config change, but it changes what kind of mistake is possible. Instead of relying on everyone remembering to lock every new controller, you're relying on someone remembering to unlock the few that should be public. That second failure mode is much easier to catch in review.

The checklist worth keeping around

A few of these are directly related to the resource-based point above, others are just things that are cheap to get right and expensive to get wrong later:

HTTPS + HSTS; UseHttpsRedirection
Fallback authorization policy; anonymous is opt-in
Rate limiting (AddRateLimiter) on auth and expensive endpoints
Secrets from a vault, never from appsettings.json or the repo
Parameterized queries only — FromSqlInterpolated, never string concatenation into FromSqlRaw
Don't log tokens, PII, or full request bodies; scrub structured log properties
app.UseCors() with an explicit origin list, never AllowAnyOrigin + credentials
Dependency scanning: dotnet list package --vulnerable --include-transitive in CI

None of these are exotic. Most authorization bugs I've seen didn't come from someone doing something clever wrong — they came from reaching for [Authorize] when the actual question needed a resource loaded first.

Getting Request Handling Right in .NET APIs

Kazem — Mon, 24 Aug 2026 11:29:30 +0000

Every request handler answers three questions: where does this data come from, is it well-formed, and is it legal? Most bugs I see in API code come from answering these in the wrong place: validating something in the controller that belongs in the domain, or trying to bind data that should've been rejected by a route constraint before your code even ran. .NET already gives you the tools to keep these separate. The trick is using them for what they're actually for.

Where does the data come from

Take a single action signature:

[HttpPost("{id:guid}/comments")]
public async Task<IActionResult> Add(
    [FromRoute] Guid id,
    [FromQuery] bool notify,
    [FromBody]  CommentRequest body,
    [FromHeader(Name = "X-Idempotency-Key")] string? idempotencyKey,
    [FromServices] ICommentService service,
    CancellationToken ct)

Five different binding sources, five different jobs. id comes from the route because it identifies the resource. notify sits in the query string since it's an optional modifier, and body, the actual payload, belongs in the request body. The idempotency key is transport-level metadata rather than part of the resource, so it comes from a header. The service isn't part of the request at all; it comes from DI.

None of this is exotic. It's just naming things by where they belong instead of dumping everything into one bag and sorting it out in code. When you see a handler that manually reads Request.Query["notify"] inside the method body, that's usually a sign someone skipped past the binding attributes rather than a sign they weren't available.

Route constraints do part of this job before your action even runs. {id:guid} rejects anything that isn't a valid GUID at the routing layer. The request never reaches your handler, so you don't write an if (!Guid.TryParse(...)) check that's really just working around a mistake. {page:int:min(1)} does the same thing for pagination: no page zero, no negative pages, no need for a manual bounds check in every paginated endpoint. Use them. They're free correctness you don't have to write yourself.

Is the input well-formed

Once the request is bound, the next question is whether the values make sense on their own: not whether the operation is allowed, just whether the shape is right.

public sealed record CreatePostRequest
{
    [Required, StringLength(200, MinimumLength = 3)]
    public required string Title { get; init; }

    [Required]
    public required string Body { get; init; }

    public DateTimeOffset? PublishedAt { get; init; }
}

With [ApiController] on the controller, a failing model state returns 400 plus a ValidationProblemDetails body automatically. You don't write that branch yourself. And as of .NET 10, minimal APIs get the same thing without a hand-rolled filter: AddValidation() wires up DataAnnotations validation directly, so the gap between controllers and minimal APIs on this point mostly closes.

For anything past "is this field required and how long," DataAnnotations starts to strain. Conditional rules, cross-field checks, async checks like uniqueness: that's FluentValidation territory. I keep it in the Application layer, not on the entity. The reason is the question it's answering: request validation asks "is this input well-formed?" The domain asks "is this operation legal?" Those are different questions with different answers depending on context, and collapsing them into one validation step is where things get messy. A title being too short is always wrong. A post being published while the author is suspended is only wrong because of state the entity itself owns. Mixing those means either the entity ends up depending on request shapes it shouldn't know about, or the request validator starts reaching into business rules it has no business enforcing.

Shaping the response

On the way out, prefer TypedResults over Results:

return TypedResults.Ok(dto);                                  // 200
return TypedResults.Created($"/api/posts/{dto.Id}", dto);     // 201 + Location
return TypedResults.NoContent();                              // 204
return TypedResults.NotFound();                               // 404
return TypedResults.ValidationProblem(errors);                // 400
return TypedResults.Problem(statusCode: 409, title: "Conflict");
return TypedResults.Stream(stream, "text/csv", "export.csv");

The difference isn't cosmetic. The concrete type flows into OpenAPI generation and is assertable in tests: you can check that an endpoint returns Created<PostDto> instead of asserting on a generic IActionResult and hoping the status code lines up. Results still works, but you lose that.

For large collections, don't buffer the whole thing into a list before returning it:

app.MapGet("/export", (AppDbContext db, CancellationToken ct) =>
    db.Posts.AsNoTracking().AsAsyncEnumerable());   // IAsyncEnumerable → streamed JSON

IAsyncEnumerable streams the JSON as rows come off the database instead of materializing everything in memory first. For an export endpoint especially, that's the difference between a response that starts immediately and one that hangs while the server loads ten thousand rows before writing a single byte.

Contract hygiene

A few rules I hold to regardless of the endpoint:

DTOs both ways, always. Never accept or return entities directly. Over-posting (a client sending fields it shouldn't be able to set, which then get bound straight onto your entity) is a real vulnerability, not a theoretical one. And returning entities means every change to your domain model is also a silent breaking change to your API clients, whether you meant it to be or not.

Version from day one, either /api/v1/... or a header. Retro-fitting versioning onto an API that's already live and already has consumers is painful in a way that's hard to appreciate until you're the one doing it.

For docs, AddOpenApi() / MapOpenApi() generates the OpenAPI document now. Swashbuckle's templates left as of .NET 9. Pair it with Scalar or Swagger UI for the browsable page.

ProblemDetails everywhere, including on 500s. One error shape across the whole API means clients write one error-handling path instead of special-casing whatever shape each endpoint happened to return.

And status codes should mean what they say: 401 is "who are you," 403 is "I know who you are and no," 409 is a concurrency conflict, 422 is semantically invalid input: the request was well-formed but the operation itself can't happen. Getting these right isn't pedantry. It's the difference between a client that can programmatically decide whether to retry, prompt for re-authentication, or just fail, versus a client that has to parse your error message to figure out what happened.

What trips people up isn't any single piece of this. It's blending the layers: validating business rules in a request DTO, or handling routing concerns inside a service method. Keep each question where it belongs, and the framework does most of the work for you.

Controllers vs Minimal APIs: Stop Picking a Winner

Kazem — Mon, 24 Aug 2026 11:04:42 +0000

Every .NET 10 project I start now has the same five-minute argument with myself: Controllers or Minimal APIs?

Both are first-class citizens in .NET 10, with the same routing, DI, filters, and model binding under the hood. So the question isn't which one is "better." It's which shape fits the API you're actually building. And that decision matters a lot less than what you do once you've made it.

The actual tradeoff

Here's how I think about it:

	Controllers (MVC)	Minimal APIs
Best for	Large APIs, convention-heavy teams, model binding edge cases, existing MVC codebases, framework integration (ABP, OData)	Small/medium services, vertical slices, high-throughput endpoints, AOT scenarios
Discovery	Attribute routing, conventions	Explicit `Map*` calls
Overhead	Slightly more per request	Lowest
Risk	"Fat controller" gravity	`Program.cs` becomes a 900-line wall unless you split into endpoint modules

Notice the risk column. Both approaches share the same failure mode: everything ends up in one place because nobody stopped it early. Controllers accrete logic because it's easy to add "just one more method" to an existing class. Minimal APIs accrete Map* calls in Program.cs for the same reason: the file's already open, the pattern's already there, why not.

What matters is keeping either one from collapsing into a dumping ground, not which style you start with.

What that looks like for Minimal APIs

If you're going with Minimal APIs, don't stack your endpoints in Program.cs. Pull them into modules and register them with an extension method:

// Minimal API, organized as a module — not dumped in Program.cs
public static class PostEndpoints
{
    public static IEndpointRouteBuilder MapPosts(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/api/posts")
            .WithTags("Posts")
            .RequireAuthorization()
            .AddEndpointFilter<ValidationFilter>();

        group.MapGet("/", async (IPostService svc, [AsParameters] PostQuery q, CancellationToken ct)
            => TypedResults.Ok(await svc.SearchAsync(q, ct)));

        group.MapPost("/", async Task<Results<Created<PostDto>, ValidationProblem>>
            (CreatePostRequest req, IPostService svc, CancellationToken ct) =>
        {
            var dto = await svc.CreateAsync(req, ct);
            return TypedResults.Created($"/api/posts/{dto.Id}", dto);
        });

        return app;
    }
}

// Program.cs
app.MapPosts();

MapGroup gives you a single place to attach tags, auth, and filters for a whole slice of routes, instead of repeating .RequireAuthorization() on every individual Map* call. Program.cs stays one line per feature. That's the whole trick, and it only works if you do it from the start, before you have twenty endpoints to retrofit.

What that looks like for Controllers

The controller side has its own version of the same discipline, and it's basically the same spirit I'd apply in Laravel: keep the controller thin and let it do exactly one job, translating an HTTP request into a call on something else.

A few things I hold to on every controller:

Thin. Bind → delegate → shape a response. No EF queries in a controller action, no business rules. If you're writing a Where clause in a controller, that logic belongs in a service.

Always [ApiController]. It gives you automatic 400s on model-binding failures and infers binding sources for you. There's no good reason to opt out of this on a real API controller.

Never return a raw entity. Return IActionResult or TypedResults, and shape the response explicitly. Your database schema is not your API contract. The moment you return an EF entity directly, every column you add to that table becomes a payload change for every client, whether you meant it to or not.

Always accept and forward CancellationToken. And never async void, never .Result, never .Wait(). Under load, blocking on an async call like that is a thread-pool starvation deadlock waiting to happen, the kind of bug that shows up in production instead of dev, under exactly the traffic you were trying to handle.

So which one do I pick

It depends on the shape of what I'm building. That's not a cop-out; it's the actual answer. A handful of high-throughput, independently-scaled endpoints with no shared model-binding complexity? Minimal APIs, one module per feature. A large API integrating with something like ABP or OData, where framework conventions are doing real work for me? Controllers.

What I've stopped doing is treating the choice as the interesting part. What matters is whether, six months in, the routing layer is still organized the way it was on day one: whether Program.cs is still readable, whether controllers are still thin. That's a discipline problem, not an API-style problem.

Pick the shape that fits, then actually enforce the guardrails that keep it from turning into the thing you were trying to avoid in the other approach.

Middleware Order Is Behavior, Not Style

Kazem — Mon, 24 Aug 2026 11:04:01 +0000

Middleware ordering looks like a formatting preference, like where you put your using statements. It isn't. Put UseAuthorization() before UseAuthentication() in a pipeline and every request sails through as anonymous. No error, no warning, nothing in the logs to flag it. The app just quietly stops checking who anyone is.

That's the thing about ASP.NET Core middleware: it's a pipeline, and pipelines are order-sensitive by nature. Each component gets the HttpContext, can act before and after the next one runs, and can short-circuit the whole thing. Swap two lines and you haven't changed how the code looks: you've changed what "authenticated" or "handled" means for every request that comes through. And the framework won't tell you.

The short-circuit and what runs after it

Here's a tenant-resolution middleware that shows most of the moving parts at once:

public sealed class TenantMiddleware(RequestDelegate next)
{
    public async Task InvokeAsync(HttpContext context, ITenantStore store)   // scoped svc injected per-call
    {
        var tenantId = context.Request.Headers["X-Tenant"].FirstOrDefault();

        if (string.IsNullOrEmpty(tenantId))
        {
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
            await context.Response.WriteAsJsonAsync(new ProblemDetails
            {
                Title = "Missing X-Tenant header.", Status = 400
            });
            return;                                     // short-circuit: next is never called
        }

        context.Items["Tenant"] = await store.FindAsync(tenantId);

        await next(context);                            // everything after this runs on the way out

        context.Response.Headers["X-Tenant"] = tenantId; // ⚠ too late if the response already started
    }
}

app.UseMiddleware<TenantMiddleware>();

If the header is missing, we return a 400 and never call next(context). That's the short-circuit: nothing further down the pipeline runs, including routing, auth, or the endpoint itself. It's a deliberate gate, and it's the same mechanism that makes ordering matter everywhere else in the pipeline: whatever runs before next() sees the request on the way in, and whatever runs after sees it on the way out, only if something further down didn't already short-circuit it.

That last line is worth pausing on: setting a response header after await next(context) assumes the response hasn't started yet. If anything downstream has already begun streaming the response, which is common the moment you're dealing with larger payloads or certain content types, that header write does nothing. No exception, no warning. It just silently fails to take effect.

There's a second trap in that same snippet that has nothing to do with ordering: ITenantStore store is injected as a parameter on InvokeAsync, not through the constructor. That's not a style choice either. Convention-based middleware like this is instantiated once, at startup, and reused as a singleton for the lifetime of the app. If you constructor-inject a scoped service, like most DbContext-backed stores, you're capturing it once and reusing that same instance across every request, which is exactly the kind of bug that only shows up under concurrent load, well after you've stopped looking at this file. Injecting scoped services as InvokeAsync parameters sidesteps that, because the DI container resolves them fresh per request. The other option is to implement IMiddleware and register it explicitly, which gives you per-request instantiation instead of the singleton convention.

The pipeline as a dependency graph

Once you've internalized that middleware runs in a strict, request-in/response-out sequence, the rest of a typical pipeline reads less like a checklist and more like a dependency graph:

app.UseExceptionHandler();      // outermost — must wrap everything to catch it
app.UseHsts();
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();               // decides WHICH endpoint
app.UseRateLimiter();
app.UseCors();
app.UseAuthentication();        // WHO are you        — must be after UseRouting
app.UseAuthorization();         // are you ALLOWED    — must be after authentication
app.UseOutputCache();
app.MapControllers();           // executes the endpoint

UseExceptionHandler() goes first because it needs to wrap everything else. Register it last and it's inside the pipeline instead of around it, so it won't catch exceptions thrown by the middleware registered before it. That's easy to miss because a handler like this can look correct in isolation and pass a test built around a deliberately-thrown exception in a controller action, while still doing nothing the one time an earlier middleware fails.

UseAuthentication() has to come after UseRouting(), and UseAuthorization() has to come after UseAuthentication(). Flip that last pair, authorization before authentication, and you get the anonymous-request problem: every request is evaluated as anonymous because the authorization middleware runs before anything has had a chance to establish who the caller is. The request doesn't error. It just gets treated as if no one is logged in, which in a lot of setups means either "reject everyone" or, worse, "allow everyone" depending on how your policies are written.

Neither mistake throws a compile-time error or a runtime warning. The pipeline builds fine. Requests come through. The behavior is just wrong, and the only way to catch it is to actually exercise the auth path or read the pipeline order carefully enough to reason through what each stage assumes about the ones before it.

Handle exceptions once, centrally

The UseExceptionHandler() line pairs with an IExceptionHandler implementation, which is where cross-cutting exception handling actually lives:

public sealed class DomainExceptionHandler(IProblemDetailsService problems) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(HttpContext ctx, Exception ex, CancellationToken ct)
    {
        if (ex is not DomainException domain) return false;   // let the next handler try

        ctx.Response.StatusCode = StatusCodes.Status422UnprocessableEntity;

        return await problems.TryWriteAsync(new ProblemDetailsContext
        {
            HttpContext = ctx,
            ProblemDetails = { Title = "Domain rule violated", Detail = domain.Message }
        });
    }
}

builder.Services.AddExceptionHandler<DomainExceptionHandler>();
builder.Services.AddProblemDetails();

If you find yourself wrapping every controller action in try/catch, that's usually a sign the exception handling belongs here instead. Registering multiple IExceptionHandler implementations lets you handle different exception types separately (TryHandleAsync returning false just passes the exception to the next registered handler), while every response still comes back as a consistent RFC 9457 ProblemDetails payload instead of whatever ad hoc shape each action happened to return.

Middleware or endpoint filter?

Not everything belongs in the middleware pipeline just because it can go there. The distinction that's actually useful:

Use middleware for	Use an endpoint filter / action filter for
Anything cross-cutting on every request (logging, auth, correlation IDs, compression)	Concerns tied to a specific endpoint or group (validation, idempotency keys, resource authorization)
Work that must run before routing	Work that needs the bound arguments / model

Middleware runs before the framework has matched a route or bound any parameters, so it's the right place for things that apply uniformly: logging every request, stamping a correlation ID, checking who the caller is. The moment you need the actual bound arguments of a specific endpoint (validating a request body, checking an idempotency key against a specific resource), you're past what middleware can see cleanly, and an endpoint filter is the better fit. Trying to do argument-level validation in middleware usually means re-parsing or re-binding something the framework is about to do anyway.

None of this is complicated once you see the pipeline for what it is: a strict, ordered sequence where each stage's correctness depends on assumptions about what already ran. The bugs aren't exotic. They're one-line reorderings that compile clean, run clean, and quietly change what your API does.

EF Core bugs that look like correct code

Kazem — Mon, 24 Aug 2026 09:40:31 +0000

Most EF Core bugs I've seen in production aren't from bad code. They're from code that looks right. It compiles, it passes review, it works fine locally against a database with twelve rows in it. Then it hits a table with five thousand rows, or a second replica, or a request that gets cancelled halfway through, and it falls over in a way nobody wrote a test for.

None of the mistakes below are exotic. They're the default behavior of EF Core when you don't opt out of it, or the default behavior of a deployment when nobody thought about what "five pods start at the same time" actually means. Here's the setup I use and the list of ways it goes wrong if you skip a step.

The entity

namespace Sample.Domain.Posts;

public sealed class Post
{
    public Guid Id { get; private set; } = Guid.CreateVersion7();  // sequential → index-friendly
    public required string Title { get; set; }
    public required string Slug { get; init; }
    public string Body { get; set; } = string.Empty;
    public DateTimeOffset? PublishedAt { get; private set; }
    public Guid AuthorId { get; init; }
    public uint RowVersion { get; set; }        // optimistic concurrency token

    public void Publish(TimeProvider clock)
    {
        if (PublishedAt is not null)
            throw new DomainException("Post is already published.");

        PublishedAt = clock.GetUtcNow();
    }
}

Two things here that are easy to skip and annoying to retrofit later. Timestamps are stored as UTC (DateTimeOffset), rendered in the user's timezone only at the edge — I do the same thing on my project, storing everything UTC and rendering in Asia/Turkey, because "what timezone is this in" is a much worse question to answer after the data already exists in three different formats.

Second: the clock comes in as TimeProvider, not a call to DateTime.UtcNow buried inside the method. It's a small thing, but it's the difference between a test that can assert "publishing sets the timestamp to exactly this value" and a test that has to accept "sometime around now."

Configuration, not attributes

public sealed class AppDbContext(DbContextOptions<AppDbContext> options) : DbContext(options)
{
    public DbSet<Post> Posts => Set<Post>();

    protected override void OnModelCreating(ModelBuilder b)
        => b.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly);
}

public sealed class PostConfiguration : IEntityTypeConfiguration<Post>
{
    public void Configure(EntityTypeBuilder<Post> b)
    {
        b.ToTable("posts");
        b.HasKey(p => p.Id);
        b.Property(p => p.Title).HasMaxLength(200).IsRequired();
        b.HasIndex(p => p.Slug).IsUnique();
        b.HasIndex(p => new { p.PublishedAt, p.Id });
        b.Property(p => p.RowVersion).IsRowVersion();
    }
}

Mapping lives in IEntityTypeConfiguration<T> classes instead of [MaxLength] and [Required] attributes scattered across the entity. The entity is domain code — it shouldn't need to know it's being persisted to a posts table with a unique index on Slug. Keep persistence concerns out of the domain and the entity stays readable as just "what a Post is," not "what a Post is plus how Postgres stores it."

Migrations as a deploy step, not a startup hook

dotnet tool install --global dotnet-ef
dotnet ef migrations add CreatePosts -p src/Sample.Infrastructure -s src/Sample.Api
dotnet ef database update -s src/Sample.Api

# Production: generate idempotent SQL, review it, apply it in the deploy pipeline
dotnet ef migrations script --idempotent -o migrate.sql -s src/Sample.Api

This is the one I'd flag hardest: don't call db.Database.Migrate() at app startup in a multi-replica deployment. It looks convenient: the app migrates itself, one less step to remember. But five pods racing to alter the same schema on boot is how you get a half-migrated database at 3am, and you find out about it from an alert, not from a code review comment. Migrations run as a separate deploy step, an init container or a pipeline stage, with a single runner. On a K3s deployment where the whole point is running multiple replicas, this isn't an edge case, it's the normal startup path.

The other rule, same as I'd apply to any migration system including Laravel's: migrations are append-only once merged. You don't go back and edit a migration that's already shipped, you write a new one.

Reads that don't drag the change tracker along

[ApiController]
[Route("api/posts")]
public sealed class PostsController(IPostService posts) : ControllerBase
{
    [HttpGet]
    [ProducesResponseType<PagedResult<PostDto>>(StatusCodes.Status200OK)]
    public async Task<IActionResult> Index([FromQuery] PostQuery query, CancellationToken ct)
        => Ok(await posts.SearchAsync(query, ct));

    [HttpGet("{id:guid}", Name = "GetPost")]
    public async Task<IActionResult> Show(Guid id, CancellationToken ct)
        => await posts.FindAsync(id, ct) is { } dto ? Ok(dto) : NotFound();

    [HttpPost]
    public async Task<IActionResult> Store(CreatePostRequest request, CancellationToken ct)
    {
        var dto = await posts.CreateAsync(request, ct);
        return CreatedAtRoute("GetPost", new { id = dto.Id }, dto);   // 201 + Location
    }

    [HttpDelete("{id:guid}")]
    public async Task<IActionResult> Destroy(Guid id, CancellationToken ct)
    {
        await posts.DeleteAsync(id, ct);
        return NoContent();                                          // 204
    }
}

// The read side — project to a DTO in SQL, don't materialize entities you won't mutate
public async Task<PagedResult<PostDto>> SearchAsync(PostQuery q, CancellationToken ct)
{
    var query = db.Posts
        .AsNoTracking()
        .Where(p => p.PublishedAt != null && p.PublishedAt <= clock.GetUtcNow());

    if (!string.IsNullOrWhiteSpace(q.Search))
        query = query.Where(p => EF.Functions.ILike(p.Title, $"%{q.Search}%"));

    var total = await query.CountAsync(ct);

    var items = await query
        .OrderByDescending(p => p.PublishedAt).ThenBy(p => p.Id)
        .Skip((q.Page - 1) * q.PageSize).Take(q.PageSize)
        .Select(p => new PostDto(p.Id, p.Title, p.Slug, p.PublishedAt))   // projection
        .ToListAsync(ct);

    return new PagedResult<PostDto>(items, total, q.Page, q.PageSize);
}

This is the routine version. The interesting part is the list of ways a piece of code that looks just like this one goes wrong.

The traps that cost real money

Forgetting AsNoTracking() on reads. The change tracker snapshots every entity it loads so it can detect what changed on SaveChanges(). On a list endpoint returning 5,000 rows you're never going to mutate, that snapshotting is pure overhead. It's easy to miss because nothing throws — the endpoint just gets slower and nobody notices until the row count grows.

N+1 via Include in a loop. Lazy loading is off by default, which is the right call. But a foreach with a .Load() inside it, or an Include chain built inside a loop, recreates the exact N+1 problem lazy loading was supposed to prevent. The fix isn't a rule you remember, it's counting queries in tests, logging query counts and asserting on them, because this one hides well in code review.

Cartesian explosion. Two collection Includes in a single query multiply rows: if a post has several comments and several tags, you don't get one row per relationship back, you get every combination multiplied together. AsSplitQuery() fixes it by running separate queries instead of one join, but you have to know to reach for it.

Client-side evaluation. If a Where clause can't translate to SQL, EF Core 3+ throws instead of silently pulling the whole table into memory and filtering there. That's on purpose. The fix is to read the exception and rewrite the predicate, not to slap a .ToList() before the filter to make the error go away. That "fix" is how you get the exact behavior the throw was designed to prevent.

No cancellation token. Every async DB call should take the request's CancellationToken. Skip it and an aborted request (the user closed the tab, the client timed out) keeps the query running and burning DB time for work nobody's waiting on anymore.

SaveChanges per row in a loop. Updating rows by loading each one, mutating it, and calling SaveChangesAsync() inside the loop turns one update into a round trip per row. Batch the changes into one SaveChanges call, or better, use ExecuteUpdateAsync / ExecuteDeleteAsync for set-based operations that don't need entities loaded into memory at all.

Long-lived DbContext. It's registered Scoped for a reason. It isn't thread-safe, and its change tracker grows unbounded the longer it's kept alive. Holding onto one across requests, or sharing it across concurrent operations, is asking for either an InvalidOperationException mid-request or a slow memory leak.

Individually these read like a checklist. In practice they're the shape production incidents actually take: an endpoint that behaves fine solo and falls over under concurrent load, a migration that half-applies because two pods started within the same second.

Commit first, dispatch after

await using var tx = await db.Database.BeginTransactionAsync(ct);

var post = new Post { Title = req.Title, Slug = Slugify(req.Title), AuthorId = userId };
db.Posts.Add(post);
await db.SaveChangesAsync(ct);

await outbox.EnqueueAsync(new PostCreated(post.Id), ct);   // same transaction
await tx.CommitAsync(ct);

The rule here is simple to state and easy to violate without noticing: never publish to a message bus or call a third-party API inside a transaction. If the transaction rolls back after the message already went out, you've told the rest of the system about a Post that doesn't exist. Write to an outbox table in the same transaction as the domain change, commit, then dispatch from the outbox afterward. The message only goes out if the write actually stuck.

This pattern matters more the more moving parts a system has downstream: background jobs, other services reacting to events, things that can't be un-told once they've happened. It's the same reasoning behind offloading side effects to a job runner instead of doing them inline: the database transaction is where correctness gets decided, and everything after commit is just telling the rest of the world what already happened.

None of this is advanced EF Core. It's the boring stuff: entity design, mapping, migrations, queries that don't drag more into memory than they need to. The bugs aren't hard to fix once you see them. The hard part is that the code that has them doesn't look wrong.

Register, Then Run: The Discipline Hiding in Program.cs

Kazem — Mon, 24 Aug 2026 07:41:20 +0000

The first time I tried to register a service after builder.Build() in ASP.NET Core, I got an error that made no sense to me. The container was already sealed, it said. I'd spent years in Laravel, where you can bind things into the container more or less whenever you feel like it, and my instinct was to go looking for the service registration wherever the code needed it. ASP.NET Core doesn't work that way, and once I understood why, a handful of other things that had confused me stopped being confusing.

Two phases, strictly ordered

Here's what a minimal Program.cs looks like:

var builder = WebApplication.CreateBuilder(args);

// ---------- 1. REGISTRATION: build the DI container + config ----------
builder.Services.AddDbContext<AppDbContext>(o =>
    o.UseNpgsql(builder.Configuration.GetConnectionString("Default")));
builder.Services.AddScoped<IPostService, PostService>();
builder.Services.AddProblemDetails();
builder.Services.AddOpenApi();
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
builder.Services.AddHealthChecks().AddDbContextCheck<AppDbContext>();

var app = builder.Build();   // container is now SEALED — no more registrations

// ---------- 2. PIPELINE: order is behaviour ----------
app.UseExceptionHandler();
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();

// ---------- 3. ENDPOINTS ----------
app.MapControllers();
app.MapHealthChecks("/health/ready");
app.MapOpenApi();

app.Run();

Everything on builder.Services happens before builder.Build(). Everything on app happens after. You register everything, build the container once, and only then configure the pipeline. There's no Startup.cs anymore, either. If you're reading a tutorial with Startup.ConfigureServices, it's pre-.NET 6.

This isn't a syntax quirk. It's the same register-then-run discipline you'll run into again as soon as you touch DI lifetimes or configuration, and skipping past it is exactly how people carry over habits from more dynamic frameworks and get burned.

The captive dependency trap

DI lifetimes in ASP.NET Core come in three flavors:

Lifetime	One instance per	Use for
Singleton	Application	Stateless services, caches, config, `IHttpClientFactory`
Scoped	HTTP request	`DbContext`, repositories, unit of work, anything request-specific
Transient	Every resolution	Cheap, stateless helpers

The DI scope is created per request, and everything registered as Scoped (your DbContext, your unit of work) lives and dies with it. The trap is injecting a Scoped service into a Singleton. The singleton is built once, so it captures whatever instance of the scoped service happened to be around at that moment (usually the first request's) and holds onto it forever. Your DbContext becomes a shared, thread-unsafe, ever-growing object that nobody intended to create.

The default container throws on this in development, via ValidateScopes. Keep that on, and turn on ValidateOnBuild too so CI catches it before it ships:

builder.Host.UseDefaultServiceProvider((ctx, o) =>
{
    o.ValidateScopes = true;
    o.ValidateOnBuild = true;
});

If you genuinely need scoped work inside a singleton or a BackgroundService, you don't fight the lifetime. You create a scope explicitly:

using var scope = _serviceScopeFactory.CreateScope();
var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();

Configuration

Configuration in ASP.NET Core is layered: appsettings.json, then appsettings.{Environment}.json, then user secrets in dev, then environment variables, then command line, each one overriding the last.

Binding options follows a simple rule: validate at startup, not at first use.

// Bind + validate at startup, not at first use
builder.Services.AddOptions<SmtpOptions>()
    .Bind(builder.Configuration.GetSection("Smtp"))
    .ValidateDataAnnotations()
    .ValidateOnStart();

// Consume
public sealed class Mailer(IOptions<SmtpOptions> options) { ... }

There are three ways to consume it, and picking the wrong one is another version of the captive dependency problem: IOptions<T> is a singleton snapshot, taken once and frozen. IOptionsSnapshot<T> re-reads per request. IOptionsMonitor<T> gives you change notifications and is the only one of the three that's safe to use inside a singleton. Never put secrets in appsettings.json. Use user secrets locally, and a real secret store in production.

What this means for project structure

A layered solution (Domain, Application, Infrastructure, Api) enforces a dependency rule: arrows point inward, Domain knows nothing about EF Core or HTTP. If your Domain project needs a using Microsoft.EntityFrameworkCore;, the layering is broken.

Two things I've learned from actually building this, not from a tutorial: four projects is the ceiling for a small service, not the floor. A single well-organized project with folders is fine below roughly ten endpoints, and it's much easier to move around later. And for feature-heavy apps, vertical slices (a folder per feature containing its endpoint, handler, DTOs, and validator) tend to scale better in practice than horizontal layers. Layers keep dependencies honest; slices keep changes local. Pick one on purpose, and write down why, because you'll want to remember the reasoning the next time someone asks why the project isn't laid out the "standard" way.

The .csproj File Nobody Reads

Kazem — Mon, 24 Aug 2026 07:19:27 +0000

Most people copy a .csproj from the last project and never look at it again. It's the file you generate once with dotnet new webapi and then ignore for the rest of the project's life. I think that's a mistake: a handful of settings in there decide how much your build actually catches before broken code reaches production.

Before getting to those settings, it's worth clearing up something a lot of people are fuzzy on: the difference between the SDK and the Runtime.

SDK vs Runtime

The .NET download page gives you two options, and a lot of beginners aren't sure which one they need.

The SDK is the full developer toolkit. It includes the Runtime, the compiler, the dotnet CLI, build tools, and project templates. If you're writing code, this is what you install.

The Runtime is smaller and only runs applications. You can't create a project with it, build one, or restore NuGet packages. It's meant for production servers where the app has already been built elsewhere. These days a lot of production setups just use a Docker image with the Runtime baked in, so even that distinction shows up less than it used to.

Easy way to remember it: developers install the SDK, production servers usually need only the Runtime.

One thing that makes this less painful than it sounds: the SDK has roll-forward support. Install the .NET 10 SDK and it can still build projects targeting net8.0 or net9.0. You don't need five SDK versions installed just because you're bouncing between older repos.

Why this matters right now

Microsoft ships two kinds of releases: LTS (Long-Term Support) and STS (Standard-Term Support). LTS versions get support for several years and are what most companies run in production. .NET 8 and .NET 10 fall into this category. STS versions get new features sooner but with a shorter support window, which is fine if your team upgrades often and less fine if it doesn't.

For most enterprise applications, the answer is simple: use the latest LTS.

.NET 8 and .NET 9 both reach end of support on November 10, 2026. If you're running either in production, that's the actual deadline to have an upgrade plan. And if you're going to touch the project anyway to bump the target framework, that's the moment to also look at what else is sitting in the .csproj that you never configured on purpose.

The settings that actually matter

A typical .csproj looks something like this:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
    <AnalysisLevel>latest-recommended</AnalysisLevel>
  </PropertyGroup>

</Project>

ImplicitUsings is the least consequential of the group. It just means you stop writing using System;, using System.Linq;, and so on at the top of every file, since the common namespaces get included automatically. Nice, but cosmetic.

The rest change what your build is willing to tolerate.

TreatWarningsAsErrors turns a warning from something you can ignore into something that stops the build cold. Normally a warning is just noise in the output and the project compiles anyway. With this on, a warning fails the build the same way a compile error would. Warnings usually point at real problems, and this setting forces you to deal with them the moment they appear instead of letting them pile up as debt someone else has to clean up later.

EnforceCodeStyleInBuild checks your style rules (the ones defined in .editorconfig) at build time, not just when someone happens to run a linter. That means the whole team follows the same conventions automatically, because the build won't let inconsistent formatting through.

AnalysisLevel set to latest-recommended turns on the newest Roslyn analyzers your SDK version supports. These catch things beyond simple syntax problems: possible bugs, performance issues, API misuse, and other patterns that are technically valid C# but bad practice. Catching that at build time, before the code ships, is a lot cheaper than catching it in production.

None of these are exotic. They're one line each in a PropertyGroup. But the difference between a build that just compiles your code and a build that actively checks it is exactly these three lines.

Repository-wide, not per-project

If you're running more than one project in a solution, repeating these settings in every .csproj gets old fast, and it's easy for them to drift out of sync. Directory.Build.props at the repo root lets you define shared settings once and have every project pick them up.

The same idea applies to package versions. Instead of each project picking its own version of a NuGet package, Directory.Packages.props centralizes that in one place: fewer version conflicts, easier upgrades, and everyone in the solution referencing the same version of the same package.

Both of these are about whether the build system does useful work on your behalf before your code goes anywhere near production. Worth checking what's actually in that file next time you open a project, especially one still targeting .NET 8 or 9 with that November 2026 deadline on the calendar.

DEV Community: Kazem

ABP and Elsa Both Want to Own Your API: Pick One

Why this is worse than it sounds

The rule I landed on

Why the "just use both" instinct is wrong here

The Native AOT wrinkle, and why it doesn't change the answer

The general version of this

The .NET Production Checklist Is Really a List of Places the Framework Lies to You

Migrations: the happy path runs them on every replica

Health checks: "alive" and "ready" are not the same question

Shutdown: three timeouts, each one has to be bigger than the last

Connection pools: the number that has to be true across every replica

The runtime image: no SDK, no root

Warm-up: the first requests are the slowest ones

Everything else on the list is the same pattern

The CI gate that keeps this from being a one-time exercise

Why this checklist reads the way it does

The .NET Production Checklist Is Really a List of Places the Framework Lies to You

Migrations: the happy path runs them on every replica

Health checks: "alive" and "ready" are not the same question

Shutdown: three timeouts, each one has to be bigger than the last

Connection pools: the number that has to be true across every replica

The runtime image: no SDK, no root

Warm-up: the first requests are the slowest ones

Everything else on the list is the same pattern

The CI gate that keeps this from being a one-time exercise

Why this checklist reads the way it does

Never Use UseInMemoryDatabase in ASP.NET Tests

Why the in-memory provider fails you

What to use instead

The pyramid, ASP.NET-flavored

The supporting rules

The toolchain

Async in .NET Has Traps Laravel Never Prepared Me For

Blocking on async code

async void

A new HttpClient per call

The rules that fall out of this

Authorize Can't See Your Data

Authentication first, briefly

Where policy-based authorization stops

Resource-based authorization

Anonymous should be the exception, not the default

The checklist worth keeping around

Getting Request Handling Right in .NET APIs

Where does the data come from

Is the input well-formed

Shaping the response

Contract hygiene

Controllers vs Minimal APIs: Stop Picking a Winner

The actual tradeoff

What that looks like for Minimal APIs

What that looks like for Controllers

So which one do I pick

Middleware Order Is Behavior, Not Style

The short-circuit and what runs after it

The pipeline as a dependency graph

Handle exceptions once, centrally

Middleware or endpoint filter?

EF Core bugs that look like correct code

The entity

Configuration, not attributes

Migrations as a deploy step, not a startup hook

Reads that don't drag the change tracker along

The traps that cost real money

Commit first, dispatch after

Register, Then Run: The Discipline Hiding in Program.cs

Two phases, strictly ordered

The captive dependency trap

Configuration

What this means for project structure

The .csproj File Nobody Reads

SDK vs Runtime

Why this matters right now

The settings that actually matter

Repository-wide, not per-project

`async void`

A new `HttpClient` per call