liveBook · Manning

Binding source

As explained in ASP.NET Core in Action, 3e

A binding source is a category of request or application data from which a handler parameter or object property can be populated.

A binding source tells ASP.NET Core where to get a value for a handler parameter or binding-model property. Model binding turns request data into the .NET values a handler uses, so the handler does not have to read the URL or body itself. The available sources and the rules for choosing one differ between minimal APIs and Razor Pages. section 7.1 section 16.2

For a minimal API handler, the first matching rule wins:

  • An explicit source attribute, such as [FromRoute], [FromQuery], or [FromBody], takes priority. section 7.8
  • Otherwise, ASP.NET Core checks well-known types, a type's BindAsync method, simple-type route and query values, eligible query-string arrays, and registered services; it finally tries the JSON body. section 7.8
  • For a simple type, a parameter name matching a route parameter selects the route value; otherwise, the query string is used. section 7.8

Razor Pages checks POSTed form values, route values, then query-string values by default, matching names without regard to case. It can fill separate properties of a complex model from different sources. By contrast, a minimal API binds a complex object from one source, and it does not automatically bind form fields as form values. In Razor Pages, use source attributes when a parameter must come from somewhere else: [FromHeader] selects a request header, while [FromBody] is required to bind a JSON body. section 16.2 section 16.2.3 section 16.5

A route value becomes a number

With `@page "{number}"`, a request containing `number=5` in the route can supply `OnGet(int number)`. The handler can calculate the square without extracting or converting the URL value itself. If Razor Pages finds no matching value, an `int` parameter receives its default value, 0; check whether that is acceptable for the handler. section 16.2.1

When a value comes from the wrong place, check the applicable source order and any explicit attributes. In a minimal API, a failed bind for a required parameter produces a 400 Bad Request response; it does not trigger a search of later sources. In Razor Pages, binding is followed by validation, whose result the page handler must check. section 7.8 section 16.5

How ASP.NET Core in Action, 3e covers it

How deep it goes
Explains source-selection order in both minimal APIs and Razor Pages, including explicit overrides and missing or failed bindings.
Examples
Uses a route-bound square calculation and a page handler that binds a user ID from a header and photos from JSON.
What it assumes
Introduces binding sources through HTTP requests and handler parameters without requiring prior knowledge of the source-selection rules.
What you can do after
Diagnose/debug with it by checking why a handler value came from a particular source or failed to bind.
How it connects
Connects model binding to route parameters, query strings, request bodies, dependency injection, and validation.
Cover of ASP.NET Core in Action, 3e
liveBookmanning.com
Read ASP.NET Core in Action, 3e on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of ASP.NET Core in Action, 3e. The section links point to the parts of the book it draws on.