Route, query, header, body — four places a value could come from. Model binding is what finds the right one.

Every lesson in this Part has quietly leaned on one thing without fully explaining it: a handler parameter just... gets its value. int id shows up populated from the URL. CreateOrderRequest request shows up populated from a JSON body. This isn't magic, and it isn't guesswork — it's a specific, named mechanism called model binding, and understanding it precisely is what separates "my endpoint usually works" from "I know exactly why my endpoint's parameters get the values they get."

This also ties directly back to something you already know: back in lessons 047 and 131, you learned how System.Text.Json deserializes a JSON string into a C# object, from the client's side — calling GetFromJsonAsync against someone else's API. Model binding is largely the same deserialization machinery, running on the server side of that same conversation, turning an incoming JSON request body into your action or handler's parameter.

In this lesson, you'll learn the explicit binding-source attributes — [FromRoute], [FromQuery], [FromBody], [FromHeader], [FromServices] — the general idea of binding-source inference, and an important, honest distinction between how Controllers and Minimal APIs each approach that inference.

What Is It?

The Simple Explanation

Model binding is the process ASP.NET Core uses to take pieces of an incoming HTTP request — parts of the URL, the query string, headers, the request body — and populate them into the parameters of your action or handler method, or into the properties of a class those parameters describe.

The Technical Definition

Model binding maps data from one or more defined sources in an HTTP request into strongly-typed .NET parameters or objects, using a set of binder components, each responsible for one kind of source. Which source a given parameter binds from is either stated explicitly, using a [From...] attribute, or determined by the framework's own binding-source inference rules when no attribute is present. For request bodies specifically, the binder relies on System.Text.Json — the same serializer from lessons 047 and 131 — to deserialize the incoming JSON into your target type.

Why Does It Exist?

The Problem — Every Piece of Request Data Lives Somewhere Different

An HTTP request scatters its data across genuinely different places: an id might sit in the URL path, a filter or page size in the query string, an API version in a header, and the actual payload in a JSON body. Without model binding, every handler would need to manually reach into HttpContext.Request, pull the right raw string out of the right place, parse it, and handle the case where it's missing or malformed — for every single parameter, on every single endpoint.

The Solution — Declare the Shape, Let the Framework Do the Extraction

Model binding turns that repetitive extraction work into a declaration. You describe the shape you want — a parameter list, or a class — and the framework figures out, source by source, how to fill it in from the raw request. You write int id; you don't write the string-parsing code that turns a URL segment into an int.

Big Picture

GET /api/orders/42?includeItems=true
Header: X-Correlation-Id: 9f2a...
Body:   { "note": "Rush this one" }

   ROUTE ("42")  ─────┐
   QUERY ("true") ────┤
   HEADER (guid) ─────┼──▶  MODEL BINDING  ──▶  your parameters, populated
   BODY (JSON) ───────┘

Every one of those four values lands in a different physical part of the HTTP request, yet they can all end up as ordinary, strongly-typed C# values on your method's parameter list — that convergence is exactly what model binding does.

How It Works

[HttpGet("{id:int}")]
public IActionResult GetById([FromRoute] int id) => ...

[HttpGet]
public IActionResult GetAll([FromQuery] bool? includeItems) => ...
// GET /api/orders?includeItems=true

[HttpPost]
public IActionResult Create([FromBody] CreateOrderRequest request) => ...

public IActionResult Get([FromHeader(Name = "X-Correlation-Id")] string correlationId) => ...

public IActionResult Get([FromServices] IOrderService orderService, int id) => ...

Simple Example

One action, using all four request-data sources explicitly:

[ApiController]
[Route("api/[controller]")]
public class OrdersController(IOrderService orderService) : ControllerBase
{
    [HttpPatch("{id:int}")]
    public IActionResult UpdateNote(
        [FromRoute] int id,
        [FromQuery] bool notify,
        [FromHeader(Name = "X-Correlation-Id")] string correlationId,
        [FromBody] UpdateNoteRequest request)
    {
        orderService.UpdateNote(id, request.Note);
        if (notify) orderService.NotifyCustomer(id, correlationId);
        return NoContent();
    }
}

public record UpdateNoteRequest(string Note);

What each attribute tells the framework: id comes out of the {id:int} URL segment. notify comes from ?notify=true in the query string. correlationId comes from the named request header. request comes from deserializing the raw JSON body into an UpdateNoteRequest, using System.Text.Json under the hood — the exact same serializer, and the same case-insensitive property matching, you saw from the consuming side back in lesson 131.

Real-World Example

The same idea in a Minimal API handler — same sources, different syntax, and this is exactly where the "separate inference rules" caveat matters most:

app.MapPatch("/api/orders/{id:int}", (
    int id,                                                      // route
    bool notify,                                                 // query string
    [FromHeader(Name = "X-Correlation-Id")] string correlationId,
    UpdateNoteRequest request,                                   // body (complex type)
    IOrderService orderService) =>                                // DI
{
    orderService.UpdateNote(id, request.Note);
    if (notify) orderService.NotifyCustomer(id, correlationId);
    return Results.NoContent();
});

Notice that [FromRoute] and [FromQuery] weren't needed here — the general inference rules from the callout above cover this straightforward case identically well for both Controllers and Minimal APIs. But the moment a signature gets less obvious — say, a second complex-typed parameter, or a simple type you actually want bound from the body instead of the query string — that's exactly the point where the two styles' inference rules can diverge, and where reaching for an explicit [From...] attribute (as this lesson's callout recommends) stops being optional caution and starts being the only reliable way to know what will happen.

Under the Hood

Common Confusion

Model binding ≠ model validation

Binding answers "what value does this parameter have?" Validation answers "is that value acceptable?" They're separate, sequential steps. A parameter can bind perfectly successfully (the JSON deserialized fine) and still fail validation (a required field was present but empty, or a number was out of range). Don't conflate a binding failure (malformed JSON, wrong type) with a validation failure (well-formed data that just doesn't satisfy your business rules) — they're different problems with different causes.

"Controllers and Minimal APIs bind identically" — close, but not guaranteed

For simple, obvious signatures, they behave the same way in practice. But they are implemented as two separate systems with their own inference logic, built at different points in ASP.NET Core's history for different handler shapes. Treat the general rules in this lesson as a reliable starting mental model, not as a guarantee that every edge case behaves identically across both styles — verify against current documentation, or just be explicit, when it matters.

Common Mistakes

Mistake 1 — Two [FromBody] parameters on the same action

Adding a second complex parameter and marking it [FromBody] too, expecting the framework to split the JSON body across both.

The body is a single stream, consumed once — only one parameter can bind from it. If you need multiple pieces of data, combine them into one request DTO, or move the extras to the route/query/headers.

Mistake 2 — Assuming a complex query parameter "just works" without checking

Adding a class-typed filter/search-options parameter to a GET endpoint and assuming it'll bind neatly from multiple query string keys, without verifying the actual inference behavior for your specific handler style.

For anything beyond the simplest case, be explicit, test the actual request against your endpoint, or structure the parameter as individual simple-typed query parameters instead of one complex object.

Mistake 3 — Confusing a binding error with a validation error while debugging

Spending time adding [Required] or other validation attributes to fix a 400 that's actually caused by malformed JSON the deserializer couldn't even parse in the first place.

Check the actual error response body — a binding failure and a validation failure look different in the details, and fixing the wrong one wastes time chasing a symptom instead of the cause.

When Should I Use It?

This isn't optional — any action or handler with parameters is using model binding, whether you reach for explicit attributes or not. The real decision is how much you rely on inference versus stating sources explicitly:

• For small, obvious signatures (a single route id, a single body DTO), inference is reliable and keeps the code clean — the Minimal API examples throughout lesson 256 relied on exactly this.
• For anything ambiguous, mixed, or where you're porting logic between Controllers and Minimal APIs, prefer explicit [From...] attributes — they're self-documenting and remove any dependency on inference behavior you'd otherwise have to double-check.

Mental Model

Key Takeaway

Check Your Understanding

You've now seen exactly how request data becomes handler parameters. Let's check the details are clear.

You've now completed the full arc of this Part — from Kestrel accepting a connection, all the way down to exactly how a single parameter gets its value. That's the whole ASP.NET Core request pipeline, in your own words.

dotnetmadeeasy.com — Learn C# and .NET, the right way.