Chapter 16: Binding and validating requests with Razor Pages

Introduction

This chapter introduces Razor Pages model binding and validation, framing how request data becomes binding models and must be validated before use.

• Razor Pages binding models: Describe how Razor Pages model binding extracts request values into C# binding models that are either passed as page-handler parameters or set on PageModel properties.
  Why it matters: Binding models give page handlers structured access to values supplied with a request.
• Validation of user input: Explain why binding models containing user-provided data must be validated before a Razor Pages handler uses them, and state that Razor Pages validation uses DataAnnotations attributes.
  Why it matters: Model binding makes request data convenient to use, but validation is needed before trusting that user-supplied data.
• MVC model roles: Distinguish binding models, which carry request data into page handlers, from view models and API models, which are used after handler execution to generate a response in ASP.NET Core's MVC implementation.
  Why it matters: Separating input models from response models clarifies the role each model plays during request processing.

Key terms: model binding, binding models, page handlers, PageModel, Razor Pages infrastructure, validation, DataAnnotations attributes, user input, view models, API models

16.1 Understanding the models in Razor Pages and MVC

This section distinguishes the binding model, application model, and PageModel in Razor Pages and explains how their separate responsibilities fit into ASP.NET Core’s MVC request flow.

• Razor Pages model roles: Describe the distinct roles of the binding model, application model, and PageModel in a Razor Pages request. Explain that they respectively handle incoming request data, business actions and data access, and handler/view data for the page.
  Why it matters: Separating these roles makes it clear where request input, application logic, and rendering data belong.
• Binding model request data: Explain what data forms a binding model and how Razor Pages commonly receives it. State that it can include route values, query-string values, and form or JSON request-body data, represented by one or more POCOs.
  Why it matters: A binding model turns raw HTTP request values into C# data that a page handler can use.
• Binding model placement: State the two ways a Razor Pages binding model can be supplied to handler code: as a public PageModel property decorated with [BindProperty], or as a parameter passed to a page handler.
  Why it matters: These two options determine where request-bound input appears in a Razor Page.
• Model separation rationale: Justify keeping binding models, application models, and page/view data separate by relating the separation to MVC, single responsibility, lower interdependencies, and easier changes. Describe the PageModel as the deliberate practical exception because it combines handler/controller and view-model responsibilities.
  Why it matters: Clear boundaries keep page code easier to modify without unintended effects in other parts of the application.

Key terms: binding model, application model, PageModel, page handler, view model, MVC, route parameters, query string, request body, form data

16.2 From request to binding model: Making the request useful

This section explains how Razor Pages model binding turns request data into properties or handler arguments, where those values come from, and how to organize binding targets.

• Razor Pages model binding: Explain that model binding extracts values from an incoming HTTP request and creates or populates C# binding models so ASP.NET Core can invoke Razor Page handlers. Describe that bound values are assigned to eligible PageModel properties or supplied as page-handler parameters.
  Why it matters: Model binding removes repetitive, error-prone request-parsing code so you can focus on application behavior.
• Binding targets and GET opt-in: Describe the three Razor Pages binding-target approaches: [BindProperty] properties, page-handler parameters, and applying [BindProperties] to the PageModel. State that [BindProperty] properties need public setters and are not bound on GET requests unless SupportsGet is enabled.
  Why it matters: Choosing an appropriate binding target controls which request values your page receives and whether views can reuse them.
• Binding source precedence: Trace how Razor Pages searches binding sources by default: form values first, then route values, then query-string values, taking the first matching value. Describe that a complex model's individual properties can come from different sources, and that a property can select a specific source.
  Why it matters: Knowing source order lets you predict which client-supplied value wins and avoid binding data from an unintended part of a request.
• Binding-target design tradeoffs: Justify choosing [BindProperty] properties when request values must also be available to render the Razor view, and choosing handler parameters for simple, isolated handler inputs such as a product ID. Describe why binding every PageModel property with [BindProperties] risks accidentally binding properties that were not intended as inputs.
  Why it matters: Keeping input data deliberately scoped makes Razor Pages easier to understand and reduces unintended binding.

Key terms: model binding, binding model, PageModel, page handler, [BindProperty], [BindProperties], SupportsGet, binding sources, form values, route values

16.2.1 Binding simple types

This section explains how Razor Pages model binding supplies simple page-handler parameters from request data and what happens when values are missing or conflict.

• Simple parameter model binding: Explain how a simple page-handler parameter acts as a binding model and is populated automatically when its name matches a request value, such as a route parameter. Describe how a request for /CalculateSquare/5 binds the route value number=5 to an int number parameter before OnGet executes.
  Why it matters: Automatic binding lets handler code use typed values without manually extracting them from the URL or request.
• Default binding source precedence: Describe the three default binding sources for simple Razor Pages parameters—form values, route values, and query-string values—and explain that they are searched in that order. State that form values take precedence when the same named value occurs in multiple sources, and matching is not case-sensitive.
  Why it matters: Knowing the source order prevents surprising values when a request contains duplicate names in its form, route, and query data.
• Missing values and type conversion: State the values assigned when no binding source contains a requested value: value types receive default(T), nullable and string types receive null, and reference types are created with their parameterless constructor. Describe that request values are strings and the binder can convert primitive .NET types, types with TryParse, and types with a TypeConverter.
  Why it matters: A missing value can silently become 0, false, null, or a new object, so handlers must account for the resulting behavior.

Key terms: model binding, binding model, page handler, route values, binding sources, form values, query string values, model binder, default(T), nullable types

16.2.2 Binding complex types

This section explains how Razor Pages model binding populates complex objects, collections, dictionaries, and uploaded-file types from request data.

• Complex binding models: Explain why a class that groups related request values is a binding model and how it keeps page-handler parameters or PageModel properties from proliferating as requirements grow.
  Why it matters: Binding related input into one object makes handlers cleaner and makes adding new fields less disruptive.
• Complex property binding process: Trace how the model binder creates a complex binding model and populates its public settable properties by matching property names against available binding-source name-value pairs, including optional model-name prefixes.
  Why it matters: Knowing the binding process lets you name request fields correctly and understand why a model property was or was not populated.
• Collection and dictionary formats: Describe the request key formats that bind a list or collection, including named indexed keys, unnamed indexed keys for a single list, and repeated parameter-name keys; state that dictionaries use comparable formats with dictionary keys in place of indexes.
  Why it matters: Collection field names must follow formats the model binder recognizes, especially when requests are not generated by Razor form helpers.
• File upload binding: State that Razor Pages can bind an uploaded file as IFormFile, and can bind multiple uploaded files as IFormFileCollection, IEnumerable<IFormFile>, or List<IFormFile>; explain why file uploads should be avoided unless needed because they introduce security and denial-of-service risks.
  Why it matters: File inputs require dedicated binding types and create risks that ordinary form fields do not.

Key terms: binding model, PageModel, page handler, [BindProperty], model binder, binding sources, public settable properties, default public constructor, List<string>, collections

16.2.3 Choosing a binding source

This section explains how Razor Pages chooses model-binding sources by default and how attributes explicitly bind handler parameters or properties to request data.

• Default binding sources: Describe the three request sources that Razor Pages model binding uses by default: form data, route data, and query-string values. Explain that explicit source attributes are usually unnecessary when these defaults match the incoming data.
  Why it matters: Knowing the defaults lets you accept ordinary form, route, and query values without unnecessary binding configuration.
• Explicit binding-source attributes: Explain how [FromHeader], [FromQuery], [FromRoute], [FromForm], and [FromBody] direct Razor Pages to bind a parameter or binding-model property from a specific source. Describe the example in which [FromHeader] binds userId from a header and [FromBody] reads JSON into a List<Photo>.
  Why it matters: Explicit source selection lets a handler use request headers and body content as well as the normal form and URL sources.
• Request-body binding constraints: Describe the constraints on body binding: Razor Pages requires [FromBody] for JSON binding, only one parameter or property may use [FromBody], and [FromBody] cannot be combined with [FromForm] because both consume request-body data. State that JSON is the default input format, while other formats require configured input formatters.
  Why it matters: These constraints prevent invalid handler signatures and clarify why a request body cannot safely be bound more than once.
• Additional binding controls: Describe how [BindNever] excludes a parameter from model binding, [BindRequired] adds a validation error when a value is absent or empty, and [FromServices] obtains a parameter through dependency injection. Recognize that [ModelBinder] can customize the source, bound name, and binding type, but is rarely needed.
  Why it matters: These controls help protect against unwanted binding, require essential input, and handle exceptional binding cases.

Key terms: model binder, binding models, form data, route data, query string, [FromHeader], [FromQuery], [FromRoute], [FromForm], [FromBody]

16.3 Validating binding models

This section introduces built-in Razor Pages validation for binding models using the DataAnnotations approach already covered for user input.

• Razor Pages model validation: Explain that Razor Pages has built-in support for validating binding models, reusing DataAnnotations validation requirements declared on the model.
  Why it matters: Built-in validation lets a Razor Page check submitted user input against rules declared on its binding model.

Key terms: Razor Pages, binding models, validation, DataAnnotations attributes

16.3.1 Validation in Razor Pages

This section explains Razor Pages' built-in validation pipeline, why validation must run on the server, and how binding models declare validation rules.

• Razor Pages validation lifecycle: Trace when Razor Pages validation runs and what happens after it. Explain that validation runs automatically after model binding and before the page handler, but the handler still executes when validation fails unless application code checks and handles the result.
  Why it matters: Automatic validation produces a result, but your handler must still decide how to respond to invalid input.
• Server-side validation requirement: Justify validating user input on the server even when the browser provides client-side validation. Describe client-side validation as useful instant feedback that users can bypass, whereas server-side validation is necessary for safety and for enforcing data format, ranges, required values, and business rules.
  Why it matters: Browser checks improve usability, but only server-side validation can be trusted to enforce an application's rules.
• Binding-model validation declarations: Describe how DataAnnotations attributes declaratively place validation requirements on a binding model. State that rules involving relationships between properties can use IValidatableObject, and that another validation framework such as FluentValidation is an alternative.
  Why it matters: Declaring rules on the binding model avoids repeatedly writing common validation code for every request.

Key terms: model binding, validation, page handler, binding model, client-side validation, server-side validation, business requirements, DataAnnotations, validation attributes, IValidatableObject

16.3.2 Validating on the server for safety

This section explains how Razor Page handlers safely handle server-side validation failures and use POST-REDIRECT-GET after successful form submissions.

• ModelState validation handling: Explain that Razor Pages validates a binding model before the page handler runs, but the handler still executes and must check ModelState.IsValid before using the submitted data.
  Why it matters: Checking ModelState explicitly prevents invalid user input from being processed as though it were valid.
• Invalid form redisplay: Describe the invalid-request branch: return Page() when ModelState is invalid so the form is rendered again with the submitted Input values and validation messages from ModelState.
  Why it matters: Redisplaying the form with its values and errors lets the user understand and correct invalid input instead of losing their work.
• POST-REDIRECT-GET pattern: Explain that after a successful POST, a Razor Page should return RedirectToPage() to redirect the browser to a URL that it then requests with GET, rather than returning HTML directly to the POST.
  Why it matters: POST-REDIRECT-GET prevents a browser refresh from repeating a form POST and causing duplicate payments or other side effects.
• Explicit validation control: Justify explicit ModelState checks in Razor Pages by explaining that invalid requests usually need a custom HTML redisplay path, possibly with additional loaded data, and that handler code can handle business-rule errors alongside DataAnnotations errors.
  Why it matters: Explicit validation handling makes complex form recovery and application-specific rules clear rather than relying on inflexible automatic behavior.

Key terms: ModelState, ModelStateDictionary, ModelState.IsValid, PageModel, page handler, Page(), PageResult, Input, ErrorMessage, DataAnnotation

16.3.3 Validating on the client for user experience

This section explains how browser and JavaScript client-side validation improves form feedback while server-side validation remains essential.

• Client-side validation purpose: Explain that client-side validation checks form values before a request is sent, so users see errors immediately and get a shorter feedback cycle. State that this improves user experience but does not replace validation on the server.
  Why it matters: Fast feedback makes forms easier to use, while server validation keeps submitted data safe to process.
• Browser and JavaScript approaches: Distinguish built-in HTML5 constraint validation from JavaScript-based client-side validation. Describe that an email input type can cause modern browsers to block an invalid email format, whereas JavaScript checks entered values before form submission and is the common Razor Pages approach.
  Why it matters: Knowing which layer performs the check helps you understand both the available behavior and its browser limitations.
• Razor Pages validation generation: Describe how DataAnnotation attributes on a view model provide metadata that Razor uses to generate client-side validation HTML. State that Razor Pages automatically configures client-side validation for most built-in attributes, but custom ValidationAttributes run only on the server by default and need extra wiring to run in the client.
  Why it matters: This explains why standard validation attributes can provide browser feedback with little extra Razor Pages code and where custom rules need additional work.

Key terms: client-side validation, server-side validation, user experience, HTML5 constraint validation, email input type, JavaScript, DataAnnotation attributes, view model, Razor engine, validation HTML

16.4 Organizing your binding models in Razor Pages

This section recommends a consistent, safer convention for organizing Razor Pages binding models, route values, and validation.

• Single binding property pattern: Describe the recommendation to bind request data through one property marked with [BindProperty], using an InputModel class when several values must be bound. Explain that this consistent pattern makes the attribute harder to forget and makes Razor Pages easier for others to understand.
  Why it matters: A consistent binding shape makes page behavior clearer and reduces accidental omissions in your Razor Pages.
• Nested InputModel organization: Explain why the binding model is commonly defined as a nested class named InputModel inside its Razor Page PageModel. State that the model is usually specific to that page, so nesting keeps related code together and using the same name across pages improves consistency.
  Why it matters: Keeping a page-specific input type beside its page makes the code easier to locate and understand.
• Overposting avoidance: Distinguish [BindProperties] from [BindProperty] and explain why the section advises against [BindProperties]. State that [BindProperties] on the PageModel binds all of its properties and can expose the application to overposting attacks, whereas binding one explicit property is safer.
  Why it matters: Explicitly limiting what can be bound helps prevent users from posting values the page did not intend to accept.
• Handler route parameters and validation: Describe the recommendation to accept simple route values, such as an id, as parameters on OnGet and OnPost handlers instead of binding them to a property with SupportsGet=true. State that user input must always be validated before the application uses it.
  Why it matters: Keeping simple route values in handler parameters avoids unnecessary binding configuration, while validation protects the application from invalid input.

Key terms: [BindProperty], InputModel, model binding, PageModel, nested class, binding model, [BindProperties], overposting attacks, route parameters, OnGet

16.5 Summary

This summary recaps Razor Pages models, request model binding sources and rules, and the need to validate bound input on both server and client.