DEV Community: Kazem

MCP Doesn't Make Your Agent Smarter: It Just Tells It What's Already There

Kazem — Tue, 22 Sep 2026 06:12:16 +0000

Every explanation of MCP I've read starts by making it sound like a new kind of intelligence, and that's exactly what trips people up. You read "Model Context Protocol" and your brain fills in something clever happening under the hood: some extra reasoning layer, some new capability the model didn't have before. It isn't that. MCP doesn't make an LLM smarter or an agent more capable. It just standardizes how an agent finds out what tools it has and how to call them. That's the whole thing. Once you see it that way, it stops being a mystery and starts looking like plumbing you've built a version of before.

What the agent actually needs

An LLM on its own only produces text. Ask it to book a flight and the best it can do is describe how you'd book one yourself. It can't reach out and click anything. An agent is what you get when you wrap that LLM with tools, memory, and a loop: it can call something, look at the result, decide what to do next, and call something else. That loop is what turns "answer a question" into "go do a thing."

To go do a thing, the agent needs a way to reach the outside world. That's what a tool is: searchFlights(), bookFlight(), whatever. Underneath, those tools usually just call an API:

Agent → Tool → API → External service

None of this is new. It's the same shape as any integration you've written. The interesting part is what happens when there isn't just one API.

The problem: every service describes itself differently

Say there are a few hundred airlines, each with its own API. One returns:

{ "flightNumber": "123", "origin": "SFO", "destination": "JFK" }

Another returns the same information as:

{ "number": "123", "from": "SFO", "to": "JFK" }

Different field names, probably different endpoint names too. If you want one agent that can work with all of them, you end up writing a separate adapter per airline:

Agent
 ├── Airline A Adapter
 ├── Airline B Adapter
 ├── Airline C Adapter
 └── ...

Add a service, write another adapter. That's not a hard problem conceptually, it's just tedious in a way that scales badly. This is the exact problem MCP is aimed at, not "agents can't think," but "agents can't discover and use arbitrary services without someone hand-wiring each one."

MCP is a way to describe capabilities, not a way to gain them

MCP (Model Context Protocol) gives a service a standard way to say: here's what I can do, here's what input each thing needs, here's what it returns. An MCP server for an airline might expose something like:

Capabilities:
  searchFlights
  bookFlight

with a schema attached to each one, roughly:

{
  "name": "searchFlights",
  "description": "Search available flights",
  "inputSchema": {
    "type": "object",
    "properties": {
      "from": { "type": "string" },
      "to": { "type": "string" }
    },
    "required": ["from", "to"]
  }
}

An MCP client, the thing your agent runs inside, connects to that server and discovers this. The agent no longer needs Airline A: /api/flights, Airline B: /flights-list, Airline C: /list-flights hardcoded anywhere. It asks the server what's available and gets a consistent shape back, regardless of what the underlying API actually looks like.

The MCP server sits between the agent and your API, not in place of it

This is the part that's easy to miss: the MCP server isn't the business logic. It's a thin layer in front of logic you already have.

Without MCP, if you wrote the agent yourself, you'd hardcode the API calls directly into it:

var flights = await httpClient.GetFromJsonAsync<Flight[]>(
    "/api/flights?from=SFO&to=JFK"
);

await httpClient.PostAsJsonAsync(
    "/api/flights/book",
    booking
);

The agent has to know the API's shape. With an MCP server in between, you wrap the same calls as tools:

[McpTool("searchFlights")]
public async Task<List<Flight>> SearchFlights(string from, string to)
{
    return await flightApi.Search(from, to);
}

[McpTool("bookFlight")]
public async Task<BookingResult> BookFlight(
    string flightId,
    string firstName,
    string lastName,
    string email)
{
    return await flightApi.Book(flightId, firstName, lastName, email);
}

Look at what's inside those methods: flightApi.Search(...), flightApi.Book(...). That's still your existing client hitting your existing API. The MCP layer's job is only to describe those two methods to the agent in a shape it can discover and call. The chain is:

MCP Tool → Flight API Client → Flight Service

You're not rebuilding the Flight Service. You're exposing it.

What the round trip looks like

Say the user asks: "Find me the cheapest flight from SFO to JFK." The LLM looks at the tools it's been given, decides searchFlights fits, and produces a tool call:

{ "name": "searchFlights", "arguments": { "from": "SFO", "to": "JFK" } }

That goes to the MCP client, which sends it to the MCP server, which turns it into the actual HTTP call:

LLM → tool call → MCP Client → MCP Server → HTTP request → Flight API

The API responds with something like:

[
  { "id": "FL123", "price": 280, "airline": "Air A" },
  { "id": "FL456", "price": 220, "airline": "Air B" }
]

That comes back up through the same chain, the agent hands it to the LLM, and the LLM picks FL456 as the cheaper option. If the user then says "book it," the same pattern repeats with bookFlight, and the API eventually returns a booking reference. Nothing in this sequence required the model to know anything about the Flight API's actual shape. It only needed the tool's name and schema.

Why this matters if you're a backend developer

This is the part that made MCP click for me, because I already have a service with exactly this shape. ProcessHub, the workflow platform I've been building, has modules like:

ProcessHub
 ├── Workflow
 ├── Employee
 ├── Loan
 ├── Task
 └── Notification

I could expose an MCP server on top of it with tools like:

getEmployee
getPendingTasks
getLoanStatus
getWorkflowStatus
approveTask
rejectTask

None of that is new backend work. It's the same application services that already back the UI. The MCP server just makes them discoverable and callable by an agent instead of only reachable through a browser click.

Then a request like "check the status of Ali Rezaei's loan request" becomes a sequence the LLM can work out on its own: call getEmployee, then getLoanStatus, then getWorkflowStatus. Or "find the loan requests waiting on my approval" maps straight to getPendingTasks. The agent isn't reasoning about loans or workflows in some deeper sense, it's matching a request to the tools it was told exist, the same way it matched "find the cheapest flight" to searchFlights.

That's the actual value for someone in my position: you don't rebuild anything to make your system agent-usable. You write a thin MCP layer over the application services you already have, and the discovery and calling problem, the part that used to mean one bespoke adapter per integration, gets handled by the protocol instead.

One thing worth keeping in mind: permission

None of this means the agent should just go do things unsupervised. For anything sensitive, booking something, approving a task, changing data, it makes sense for the agent to ask first:

Agent: I want to book this flight. Approve?
User: Approve

Only then does the actual call happen. For something like approveTask on a loan workflow, that confirmation step isn't optional. It's the difference between a useful assistant and one you can't trust near real data.

Where this leaves things

The LLM still does the thinking. The agent still does the looping between the LLM and its tools. What MCP adds is a way for the agent to find out what's callable, without someone hand-coding that discovery for every single service. If you've already got working APIs behind your product, most of the work isn't teaching an agent to be smart about them. It's writing the thin layer that tells the agent they exist.

What Software Engineers Skip Before Building an AI Agent

Kazem — Tue, 22 Sep 2026 05:16:22 +0000

If you're coming into AI agents from software engineering, you've probably run into LLM, Embedding, Vector Database, RAG, Tool Calling, LangChain, LangGraph, and MCP as separate topics. Different blog posts, different tutorials, different mental models. That's the problem. In a real system, all of these are pieces of one architecture, and until you see how they connect, you're just memorizing framework APIs.

Here's the piece that matters most: building an agent is not a prompting trick. It's a systems engineering problem. The concerns that already define backend work don't disappear because there's an LLM involved. You just get one more component in the system, and this one is non-deterministic.

The LLM is a processing service with a limited input

Strip away the hype and an LLM is close to a service call:

Input → LLM → Output

Except the input isn't a plain string. The model works in tokens, and there's a hard limit on how many tokens it can process per request. You can't dump an entire database or every file in a company into a prompt and hope for the best. That's the first real constraint on any AI system's architecture:

Application → Context → LLM

The job becomes deciding what context the model actually gets.

Context window is working memory, and managing it is architecture

Think of the context window like a process's working memory. In a real request it usually has to hold the system prompt, conversation history, the user's query, retrieved documents, and tool results, all at once. If that exceeds the model's capacity, you can't send everything. So managing context becomes its own design problem:

Conversation → Select relevant history → Retrieve relevant documents → Build context → LLM

This is the seed of everything that follows. RAG and agents are both, in different ways, answers to "what goes in the context window."

Embeddings and vector search: finding things by meaning

An LLM is good at generating text, but it's not the right tool for searching a large body of information by meaning. That's what embeddings are for: they turn text into a numeric vector. "How do I reset my password?" becomes something like [0.12, -0.44, 0.81, ...]. Two pieces of text with similar meaning end up with vectors that are close together: "How can I reset my password?" and "I forgot my password, what should I do?" land near each other even though the wording is different. That's the whole basis of semantic search.

Once you have embeddings for a large set of documents, you need somewhere to store and query them — a vector database. The structure is simple: each document has its text, its metadata, and its embedding. A user query gets embedded the same way, and vector search returns the documents closest to it in that space. You're no longer matching keywords; you're matching meaning.

Chunking, and why the boundary between chunks matters

You don't embed a 200-page PDF as one vector. You split it into chunks — an employee handbook becomes a leave policy, a remote work policy, a salary policy, a security policy, each with its own embedding.

The one detail worth remembering: if you cut a document at an arbitrary point, you can lose context right at the boundary. Say one chunk ends with "Employees can request annual leave after completing their probation period..." and the next starts with "The probation period is normally three months..." Split cleanly, and the connection between those two facts disappears. That's why chunks usually overlap a bit at the edges, so information doesn't get lost exactly where you cut.

RAG is a pipeline, not a database

Now the pieces connect. Retrieval-Augmented Generation means: before the LLM answers, go find relevant information from an external source and add it to the context.

User Query → Embedding → Vector Search → Relevant Chunks → Prompt → LLM → Answer

Someone asks "how many days of annual leave do employees get?" The system embeds the question, searches the vector store, finds the leave policy chunk, adds it to the prompt, and the LLM answers from that context instead of guessing.

It's worth being precise here, because the terms get used interchangeably and they shouldn't be. A vector database is storage plus vector search. Nothing more. RAG is a pipeline: embed, retrieve, build context, prompt, generate. A vector DB can be part of a RAG system, but the two aren't the same thing.

Prompt engineering is application logic

Even with the right document retrieved, you still have to hand it to the model correctly — system instructions, retrieved context, then the question. The basic patterns here are zero-shot (no examples, just "classify this ticket as billing, technical, or account"), one-shot (one example first), and few-shot (several examples before the real input). None of this is exotic, but it's worth treating seriously: the prompt isn't a string you write once and forget. It's part of the application's logic, the same way a SQL query or a validation rule is.

An LLM alone is not an agent

This is where the real distinction starts. A plain LLM call is input → LLM → output, once. An agent runs a loop:

User Request → LLM → Decide what to do → Tool → Tool Result → LLM → Decide again → ... → Final Answer

An agent isn't "an LLM with a better prompt." It's a system that decides, based on its current state and goal, what action to take next.

Take a question like "what's the current price of this product?" The LLM doesn't know that. It has no live access to your database. So you give it a tool: get_product_price(product_id), or search_database(query), or send_email(...). The LLM decides it needs the price, calls the tool, gets a result, and uses that to answer. The LLM is the decision maker; the tool does the actual work.

Zoomed out, an agent is an observe → reason → act loop. For something simple, like checking the weather in Tehran, that's: understand the request, pick the weather tool, call it, get the result, respond. For something harder, it might be: search a database, analyze the result, call another API, compare results, produce a final answer. That's when "agent" stops being a buzzword and starts being an actual engineering problem.

LangChain, Chains, and LangGraph

As these systems grow, wiring every piece together by hand (LLM, retriever, vector DB, tool, parser, memory) gets unwieldy. LangChain is a set of abstractions for building this kind of application so you're not connecting everything from scratch. It's worth being clear about what it is, though: LangChain isn't AI. It's a framework for building LLM-based applications.

A Chain is a pipeline of fixed steps — question → prompt → LLM → parser → result, or question → retriever → documents → prompt → LLM → answer. That's fine when the path is mostly known in advance. Agents usually aren't like that; you don't know the next step ahead of time.

That's what LangGraph is for. Once a workflow branches — analyze, then either search a database or call an API depending on what's needed, then decide, then respond — a simple chain isn't enough. You have state, nodes, and edges. LangGraph models this as something closer to a state machine or a graph: state, a node processes it, the state updates, a conditional edge decides where to go next. Understanding that model matters more than memorizing LangGraph's API surface.

MCP: standardizing how an agent reaches tools

If an agent needs to talk to a calculator, a weather API, a database, a filesystem, GitHub, and some internal API, and each one needs its own custom integration, the architecture gets messy fast. The Model Context Protocol standardizes that connection. An MCP server exposes a set of tools — a Weather server might expose get_weather(city) and get_forecast(city); a Company Knowledge server might expose search_documents(query) and get_document(id). The agent doesn't need to know how the tool is implemented internally.

From an architecture standpoint, MCP is a standard boundary between the AI application and everything external to it. That separation is what lets you add capabilities without touching the agent's core logic: today it's a calculator and a weather API, tomorrow it's GitHub, Postgres, the filesystem, and a handful of internal services, and the reasoning loop itself doesn't have to change.

Putting it together: an org knowledge search example

Say a company has 100,000 documents — HR policies, engineering docs, contracts, product docs, security policies. Someone asks: "do I need my manager's approval for this kind of request?"

The system embeds the question, searches the vector database for the top relevant chunks, builds a prompt from the system instructions, the question, and those chunks, and sends it to the LLM. If answering fully requires something the documents don't have — say, the employee's own approval level — the agent can call a tool, hit an employee service, get the result, and feed it back to the LLM. That's a plain RAG system turning into an agent the moment it needs to act instead of just retrieve.

The difference between RAG and agent is worth stating plainly. RAG says: find relevant information and hand it to the model. Agent says: based on the goal and current state, decide what to do. RAG can be one of an agent's capabilities — retrieval is just one action among several it might choose.

An agent is not a magical entity: it's a small distributed system

It's easy to talk about an agent as if it's an independent thing that "does stuff." It isn't. It's a set of components: LLM, prompt, state, memory/context, tools, retrieval, external services, control flow. An agent is closer to an application architecture than to a model.

That framing is the useful one for a software engineer, because it means the classic problems show back up: authentication, authorization, retries, timeouts, rate limiting, logging, observability, caching, state management, error handling, idempotency, security, cost control. None of that disappears because there's an LLM in the loop. If anything, it matters more, because now one of your components is non-deterministic.

This is, honestly, close to what I've spent the last while building at work, minus the LLM. An approval workflow with a real task inbox, an append-only audit log, a scheduler driving both background jobs and workflow timing, human-in-the-loop suspend/resume — that's state management, idempotency, and control flow, the exact same concerns an agent needs, just without a model deciding the next step. Swap a human approver for an LLM making the routing decision and the shape of the problem barely changes.

A reasonable learning path

You don't need to learn every framework at once. A logical order looks something like: LLM → tokens and context window → embeddings → vector search → RAG → prompt engineering → tool calling → agents → LangChain → LangGraph → MCP → production concerns. Build something small at each step — a chat app for the LLM stage, a document search for RAG, a tool-calling agent for a calculator or weather API, a multi-step workflow for LangGraph, the same tools behind an MCP server for the last stage.

The mental model underneath all of it:

Component	Responsibility
LLM	Understands and generates language, decides based on context
Context window	What's actually available to the model
Embedding	Turns meaning into a vector
Vector DB	Stores and searches vectors
RAG	Brings relevant information into context
Prompt	Defines context and instructions
Tool	Performs a specific action
Agent	Decides and executes across multiple steps
LangChain	Abstractions for building LLM applications
LangGraph	Models workflow and state as a graph
MCP	Standardizes how the application reaches tools/servers

If you skip these concepts, you end up memorizing framework calls instead of understanding what you're building. The real question isn't "how do I build an agent." It's "how do I build a system where an LLM can use real data and real tools in a way that's controllable, observable, and trustworthy." That's the point where AI engineering just becomes software engineering again.

The Part That Was Never About Syntax

Kazem — Fri, 11 Sep 2026 18:38:19 +0000

Ask an AI to build you an online ordering system and it will. Models, endpoints, a checkout flow, a decent-looking admin page. It works. You can place an order.

Then the interesting part starts.

What happens if 100,000 people place orders at the same time? What if the payment succeeds but creating the order fails? What if two people try to buy the last item at exactly the same moment? What if the database goes down?

None of those questions are about syntax.

The distance has been shrinking the entire time

I've been thinking about this lately: maybe the history of programming is, at its core, the history of reducing the distance between humans and machines.

At first we had to talk to machines in 0s and 1s. Then Assembly. Then C and C++, then Java, Python, JavaScript, and everything after. Each generation took another layer of the machine's complexity away from the programmer.

Today you can build real software without knowing exactly how a CPU executes every instruction. Nobody treats that as a loss. It's just where the line moved.

AI moves the line again. Instead of asking "how do I write this code?", you can say "I want this system to do this," and a large part of turning that intention into code gets handled for you.

Which brings up the obvious question.

So are programmers going to disappear?

I don't think so. But the meaning of "programmer" will probably change.

Because building something that works is different from building something that is well-designed.

Those two things look identical in a demo. They stop looking identical the first time the system meets real traffic or real money. The ordering system that handles one order at a time and the one that handles a hundred thousand are not the same system, even when the happy-path code is nearly the same.

So go back to those questions.

With 100,000 concurrent orders, you're thinking about where the contention is, what's holding a lock, what's queued and what's synchronous, what falls over first.

When the payment succeeds but the order fails, money left the customer's account and there's nothing to show for it. That's a correctness problem about state living in two systems at once, and clean code inside either one doesn't fix it.

Two people buying the last item at the same moment is a race. Whether you handle it depends on decisions made well before anyone wrote a line of business logic.

And if the database goes down: what does the system do, what does the user see, what's recoverable when it comes back?

These are questions about understanding the system and the limitations of the machine. You can't answer them by knowing the language better. You answer them by knowing what happens when the thing runs.

What the abstraction never removed

Every layer so far took away a machine detail, and once it was gone we stopped thinking about it.

AI takes away the code-writing layer. But the questions above were never in that layer. They sat on top of it the whole time, and they're still sitting there after the layer underneath gets automated.

Code writer to problem solver

I think the future won't belong to the person who can write code faster. It'll belong more to the person who better understands:

what needs to be built,
why it should be built this way,
what trade-offs are involved,
and how to know whether what we built actually works correctly.

That last one is worth sitting with. When you write the code yourself, you carry a rough model of it in your head, and that model is part of how you judge whether it's right. When you didn't write it, you don't get that for free. Knowing whether a system works becomes something you do deliberately instead of a byproduct of having typed it.

So the role shifts. Code writer to problem solver, or system designer, or whatever name ends up sticking. The label matters less than where the work goes.

And maybe AI isn't just another new tool. Maybe it's the next stage of the same journey that started with machine code and has always had one goal: to reduce the distance between what humans want and what machines can do.

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.

DEV Community: Kazem

MCP Doesn't Make Your Agent Smarter: It Just Tells It What's Already There

What the agent actually needs

The problem: every service describes itself differently

MCP is a way to describe capabilities, not a way to gain them

The MCP server sits between the agent and your API, not in place of it

What the round trip looks like

Why this matters if you're a backend developer

One thing worth keeping in mind: permission

Where this leaves things

What Software Engineers Skip Before Building an AI Agent

The LLM is a processing service with a limited input

Context window is working memory, and managing it is architecture

Embeddings and vector search: finding things by meaning

Chunking, and why the boundary between chunks matters

RAG is a pipeline, not a database

Prompt engineering is application logic

An LLM alone is not an agent

LangChain, Chains, and LangGraph

MCP: standardizing how an agent reaches tools

Putting it together: an org knowledge search example

An agent is not a magical entity: it's a small distributed system

A reasonable learning path

The Part That Was Never About Syntax

The distance has been shrinking the entire time

So are programmers going to disappear?

What the abstraction never removed

Code writer to problem solver

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

`async void`

A new `HttpClient` per call