Chapter 13: Creating a website with Razor Pages

Introduction

This chapter introduces Razor Pages as ASP.NET Core’s approach for building server-rendered HTML applications and previews how it uses the MVC design pattern.

• ASP.NET Core application categories: Distinguish the three application categories described: machine-consumed APIs, user-facing HTML web applications, and applications that provide both. Explain that APIs return machine-readable data such as JSON or XML, whereas Razor Pages generates HTML for people using the site.
  Why it matters: Choosing whether an app serves machines, people, or both determines the kind of responses and UI approach it needs.
• Razor Pages responsibilities: Describe Razor Pages as the mechanism for a server-rendered, page-based HTML application: it handles URL requests, receives form-posted data, and generates HTML that lets users view and navigate the application.
  Why it matters: These responsibilities explain what Razor Pages contributes when building a traditional interactive website.
• Chapter learning progression: Outline the chapter’s progression: create a simple Razor Pages app from a template and compare it with minimal APIs, examine a more complex page, introduce the MVC design pattern and its maintainability benefits, then show how Razor Pages implements MVC on the ASP.NET Core MVC framework.
  Why it matters: This roadmap helps connect the initial hands-on example to the later explanation of how Razor Pages and MVC fit together.

Key terms: API, JSON, XML, HTML web application, Razor Pages, server-rendered HTML, server-rendered, page-based applications, HTML, URLs

13.1 Your first Razor Pages application

This section introduces creating a Razor Pages application from the default template and previews how its middleware, HTML generation, and page handlers compare with minimal APIs.

• Razor Pages template application: Describe the section's plan for starting with a new Razor Pages application created from a template and inspecting the generated app.
  Why it matters: Starting from the template provides the working application used to introduce Razor Pages concepts.
• Minimal API comparison: Explain that the section compares Razor Pages with a minimal API application, identifying both similarities and differences as an orientation for the new application model.
  Why it matters: Comparing the new approach with minimal APIs connects Razor Pages to request-handling ideas already introduced in the book.
• Razor Pages request components: State that the section introduces the extra default-template middleware, Razor Pages HTML generation, and page handlers as the Razor Pages counterpart to minimal API endpoint handlers.
  Why it matters: These components frame how a Razor Pages application is configured, produces a web page, and handles request logic.

Key terms: Razor Pages, template, minimal API application, middleware, HTML, page handlers, endpoint handlers

13.1.1 Using the Web Application template

This section shows how to create, run, and inspect the starter Razor Pages application produced by the ASP.NET Core Web App template.

• Web App template creation: Describe how to create a Razor Pages application with the ASP.NET Core Web App C# template in Visual Studio or with the .NET CLI. State the specified template choices: .NET 7.0, HTTPS enabled, Docker disabled, and top-level statements retained.
  Why it matters: The template provides a working Razor Pages starting point that later sections extend and explain.
• Starter application behavior: Describe how to build and run the generated app using F5 in Visual Studio or dotnet run in the project folder. Explain that it opens a Welcome page with Home and Privacy navigation, and that Privacy displays a separate page.
  Why it matters: Running the template confirms that the generated application works before its pages and configuration are explored.
• Razor Pages project structure: Explain that a Razor Pages project has the same general structure as a minimal API project but adds Pages and wwwroot folders. Describe that Pages contains files defining web pages, whereas wwwroot is the browser-accessible location for static CSS, JavaScript, images, and static HTML served by static file middleware.
  Why it matters: Knowing which files define pages and which assets browsers can request directly is essential when building a server-rendered website.
• Program.cs template difference: State that, beyond the Pages and wwwroot folders, the significant difference from a minimal API project is Program.cs. Describe that it keeps the same basic structure but adds services and middleware for a typical Razor Pages application.
  Why it matters: This sets up why the next section changes service registration and the request pipeline for Razor Pages.

Key terms: ASP.NET Core Web App, Razor Pages, Web Application template, Configure for HTTPS, Enable Docker, top-level statements, F5, dotnet run, Welcome page, Home

13.1.2 Adding and configuring services

This section configures a Razor Pages application in Program.cs by registering Razor Pages, arranging middleware, mapping Razor Page endpoints, and starting the app.

• Razor Pages application setup: Describe the six Program.cs setup steps for a Razor Pages app: create a WebApplicationBuilder, register services, build the WebApplication, add middleware, map endpoints, and call Run to start handling requests. State that Razor Pages uses the same overall application setup structure as minimal APIs.
  Why it matters: The familiar Program.cs structure lets you focus on the application model without relearning how an ASP.NET Core app starts.
• Razor Pages middleware pipeline: Explain the middleware pipeline configured for the Razor Pages app, including why middleware order matters. Describe the roles of exception handling and HSTS outside development, HTTPS redirection, static files, routing, and authorization, and explain that explicitly placing routing after static files controls its position.
  Why it matters: Middleware determines which requests reach Razor Pages and ensures static assets, errors, HTTPS, and security concerns are handled in the intended order.
• Razor Page endpoint execution: Trace how Razor Pages are enabled and executed: register Razor Pages services, call MapRazorPages to expose Razor Page endpoints, let RoutingMiddleware use the request URL to select a page, and let EndpointMiddleware execute that page to generate the HTML response. State that EndpointMiddleware is automatically added at the end of the pipeline.
  Why it matters: This request path explains how an incoming URL ultimately becomes the HTML produced by a selected Razor Page.

Key terms: WebApplicationBuilder, WebApplication, Build(), Run(), Program.cs, ExceptionHandlerMiddleware, HstsMiddleware, HttpsRedirectionMiddleware, StaticFileMiddleware, RoutingMiddleware

13.1.3 Generating HTML with Razor Pages

This section explains how Razor Pages are found for requests and how .cshtml templates combine Razor directives, C#, HTML, layouts, and PageModels to generate a web response.

• Razor Page discovery: Describe how a request is routed to a Razor Page: routing generally maps a URL path to a matching .cshtml file under the project's Pages folder, and endpoint middleware invokes that page. State the convention illustrated by /Privacy mapping to Pages/Privacy.cshtml.
  Why it matters: Understanding this convention lets you connect a browser URL to the file that produces its page.
• Razor template directives and output: Explain how a Razor Page combines static HTML with dynamic C# and identify the roles of @page, @model, @{ ... }, and @ expressions. State that @page must be the first line to make the .cshtml file a Razor Page, code inside @{ ... } executes without itself being written to the response, and @ expressions write values into the HTML output.
  Why it matters: These rules let you read and create a page template that produces dynamic HTML correctly.
• Page models and layouts: Describe the separation of responsibilities in a Razor Page: the .cshtml template focuses on presentation, its associated PageModel conventionally resides in a same-named .cshtml.cs file, and complex logic, service access, and data manipulation belong in the PageModel. Explain that layouts supply shared markup such as headers and footers and combine with a page template, avoiding repeated markup across pages.
  Why it matters: Keeping presentation, application logic, and shared page chrome separate makes a site easier to maintain.

Key terms: Razor Pages, Pages folder, routing middleware, endpoint middleware, .cshtml, Razor, @page, @model, PageModel, ViewData

13.1.4 Handling request logic with page models and handlers

This section explains how Razor Page page models and convention-based handlers run request logic separately from Razor templates, illustrated by a GET request to the Privacy page.

• Page models and handlers: Describe the role of a Razor Page page model and its page handlers. State that the model derives from PageModel, is commonly kept in a .cshtml.cs code-behind file, and contains methods that run in response to requests.
  Why it matters: Page models provide the place to put the server-side behavior for an individual Razor Page.
• Convention-based handler behavior: Explain how Razor Pages selects handlers by convention, using OnGet as the handler for a GET request. Describe that a handler can return void to render the associated Razor template or return an IActionResult for instructions such as a redirect, an error, or another response.
  Why it matters: Handler naming and return values determine both which page logic runs and how the page produces its response.
• Logic and markup separation: Justify keeping request behavior in page handlers separate from HTML generation in Razor templates. Explain that handlers can perform complex work such as loading database data or creating an invoice, while UI changes can be made without changing that logic and logic changes need not alter the HTML.
  Why it matters: Separating behavior from markup reduces the chance that a UI or logic change accidentally breaks the other concern.
• Privacy request path: Trace the request path for the sample /Privacy Razor Page. Describe that the request passes through middleware, endpoint middleware routes it to the Privacy Razor Page, OnGet executes and the page generates HTML, and the response travels back through middleware to the web server and browser.
  Why it matters: Tracing this flow connects Razor Page execution to the ASP.NET Core request pipeline already used by the application.

Key terms: page model, PageModel, page handler, code-behind file, Razor Page, OnGet, GET request, void, IActionResult, Razor template

13.2 Exploring a typical Razor Page

This section examines a typical Razor Page whose handler binds request input, uses an injected service to load data, and supplies that data to a Razor view for HTML rendering.

• Typical Razor Page flow: Trace how the to-do category page handles a request: its OnGet handler receives a category value through model binding, uses an injected ToDoService to obtain items, exposes those items through the PageModel, and lets the Razor view generate the HTML response.
  Why it matters: This is the basic request-and-response flow behind Razor Pages that contain application logic.
• Handler rendering convention: Describe how returning Page() from a page handler indicates that its associated Razor view should be rendered, and state that a void handler renders that view by convention as if it had returned Page().
  Why it matters: Knowing this convention explains why simple Razor Page handlers can omit an explicit return while still displaying their view.
• MVC-like PageModel responsibility: Explain why the PageModel's page handler resembles a controller in MVC: it accepts user input, delegates application work to the application's service or “brains,” and makes data available for the Razor view to render.
  Why it matters: This connection prepares you to understand how Razor Pages applies the MVC design pattern without requiring a separate controller class for each page.

Key terms: PageModel, page handler, OnGet, model binding, ToDoService, dependency injection, Page(), Razor view, void, MVC

13.3 Understanding the MVC design pattern

This section explains MVC as a separation of application data and business logic from UI rendering, and maps its roles and request flow to Razor Pages.

• MVC component responsibilities: Describe the model, view, and controller responsibilities in the MVC pattern as presented for Razor Pages. Distinguish the application model from the Razor Page PageModel class.
  Why it matters: Knowing which responsibility belongs where helps keep request logic, business logic, and HTML rendering separate.
• Razor Pages request flow: Trace how a Razor Pages request proceeds through an MVC-style interaction: a page handler receives the HTTP request, uses injected services to fetch or update the application model, chooses a response, passes a view model to a view when rendering HTML, and the view generates the UI.
  Why it matters: This flow explains how separate Razor Pages components collaborate to turn an HTTP request into a response.
• Model-view decoupling benefits: Explain that MVC keeps the application model independent of the final view representation, so business logic is not tied to UI constructs and can be tested more easily. State that the view generates the final representation but does not perform business logic.
  Why it matters: Separating business logic from fragile UI code makes the important parts of an application easier to test and maintain.

Key terms: MVC, model, view, controller, PageModel, page handler, HTTP request, injected services, application model, view model

13.4 Applying the MVC design pattern to Razor Pages

This section positions Razor Pages as an MVC-based framework built on ASP.NET Core MVC and introduces how routed requests reach page handlers to produce HTML.

• Razor Pages MVC foundation: Explain that Razor Pages follows the MVC design pattern and is implemented on top of the underlying ASP.NET Core MVC framework. Distinguish Razor Pages page handlers from direct ASP.NET Core MVC controllers and action methods.
  Why it matters: This foundation explains why Razor Pages has MVC-style request handling while offering a page-focused programming model.
• MVC versus MVVM classification: Distinguish Razor Pages' MVC basis from MVVM by describing the two-way relationship expected in MVVM. State that Razor Pages PageModels do not provide the two-way data binding that would make them MVVM view models.
  Why it matters: Recognizing the difference prevents confusing a server-rendered Razor Page and its PageModel with a two-way-bound desktop or client-side UI.
• Razor Page request processing: Trace how an unhandled request reaches a Razor Page: earlier middleware runs first, RoutingMiddleware selects the Razor Page handler, and EndpointMiddleware executes it. Describe Razor Pages or ASP.NET Core MVC as the more robust framework used when a request needs business-logic interaction and HTML UI generation beyond narrow middleware concerns.
  Why it matters: This request path connects Razor Pages to the ASP.NET Core middleware pipeline and explains where page execution begins.

Key terms: Razor Pages, ASP.NET Core MVC, MVC design pattern, controllers, action methods, page handlers, MVVM, Model-View-View Model, PageModel, two-way data binding

13.4.1 Directing a request to a Razor Page and building a binding model

This section traces how a Razor Pages request is routed to a page endpoint and turned into bound request data before its handler runs.

• Razor Page request routing: Explain how routing matches a request such as /category/Simple to a registered Razor Page route template and selects the appropriate page handler. Describe that each Razor Page route template corresponds to a Razor Page endpoint.
  Why it matters: Routing determines which Razor Page gets the opportunity to handle an incoming URL.
• Binding model construction: Describe a binding model as one or more C# objects that contain request data required by a page handler. Explain that it is built from bindable PageModel properties and handler method parameters, potentially using route, query-string, and request-body values.
  Why it matters: The binding model makes incoming HTTP request data usable by a page handler.
• Category handler invocation: Trace the example request from /category/Simple through binding to execution: the category string is bound to "Simple", a Razor Page instance is created through its constructor, and the value is passed to the OnGet handler so it can choose which to-do items to display.
  Why it matters: This concrete flow shows how a URL value becomes input that controls a page's response.

Key terms: routing middleware, route patterns, route template, Razor Page endpoint, page handler, binding model, binding, PageModel, query string, category

13.4.2 Executing a handler using the application model

This section explains how a Razor Pages handler acts as the MVC controller by validating a request, calling the application model, and choosing a response.

• Page handler coordination role: Explain how a page handler serves as the controller in the MVC pattern by coordinating, rather than containing, the work needed to generate a response. State that it validates the binding model, invokes application-model actions through services, and selects a response based on the result.
  Why it matters: Keeping the handler focused on coordination prevents request-handling code from absorbing the rest of the application's responsibilities.
• Application model composition: Describe the application model as the non-UI portion of the application, including the domain model, services, and database interaction. Explain that its domain model holds complex business logic in infrastructure-independent classes that are easier to test.
  Why it matters: Separating non-UI business work into the application model makes the application easier to organize and test.
• Single application-model entry point: Describe how a page handler typically calls a single entry point in the application model, which can coordinate multiple underlying services. Give the to-do category example: authorization, category searching, database loading, and file-based picture loading can occur behind that call before details are returned.
  Why it matters: A single application-model call lets the handler remain focused on request coordination even when fulfilling the request requires several operations.

Key terms: page handler, controller, MVC pattern, binding model, application model, domain model, services, database interaction, infrastructure

13.4.3 Building HTML using the view model

This section explains how a Razor Pages PageModel supplies view-model data to a Razor view, which independently renders the final HTML response.

• PageModel as view model: Explain that a view model contains all data a view needs to render a UI, usually transformed application-model data plus presentation details such as a page title. Describe how, in Razor Pages, the PageModel itself typically serves as that view model by exposing required data through properties.
  Why it matters: Knowing where view data lives helps you separate the data prepared for a page from the HTML that displays it.
• View and handler responsibilities: Distinguish the page handler's responsibility for selecting the view execution and data from the Razor view's responsibility for generating the HTML. Trace that the Razor view uses PageModel properties to produce the final HTML response, which travels back through the middleware pipeline to the browser.
  Why it matters: This distinction prevents presentation markup from being confused with request-handling and application logic.

Key terms: view model, application model, PageModel, Razor view, page handler, HTML response, middleware pipeline

13.4.4 Putting it all together: A complete Razor Page request

This section combines the Razor Pages request-to-response flow and explains why its MVC separation of concerns reduces tight coupling.

• Complete Razor Page request: Trace a complete Razor Pages request from the incoming URL through the page handler, application model, and view to the HTML response. Explain that the traditional MVC roles remain visible in Razor Pages: the handler acts as controller, alongside the application model and view.
  Why it matters: Seeing the whole flow makes it easier to locate which part of a Razor Pages application should handle a given responsibility.
• MVC responsibility boundaries: Explain the separation of concerns in Razor Pages: the view turns data into HTML, the application model performs business logic, and the page handler validates the request and selects the required response. Justify these boundaries as a way to change and test components independently.
  Why it matters: Keeping UI, business logic, and request decisions separate makes changes less likely to break unrelated parts of an application.
• Handler response selection: State that page handler methods run in response to requests and choose the type of response by returning an IActionResult. Distinguish this response-selection role from the view's role of generating HTML.
  Why it matters: A handler can choose an appropriate response for a request instead of being limited to rendering one HTML page.

Key terms: Razor Pages, MVC pattern, page handler, controller, application model, view, separation of concerns, tight coupling, page handler methods, IActionResult

13.5 Summary

This summary recaps how Razor Pages are discovered and handled, how Razor renders dynamic HTML, and how separation of concerns structures a Razor Pages application.