Chapter 17: Rendering HTML using Razor views

Introduction

This chapter introduces Razor views as the HTML-generating part of Razor Pages, covering dynamic Razor markup and reusable view composition.

• Razor Pages terminology: Distinguish Razor Pages, an individual Razor Page, its PageModel, page handlers, and Razor views. Explain that the PageModel handles binding models and handlers, while the Razor view is the final stage that generates the HTML response.
  Why it matters: Keeping these terms separate clarifies which part of a Razor Pages application handles requests and which part renders the user interface.
• Dynamic Razor rendering: Explain how Razor markup combines static HTML with C# and values from a PageModel to generate an HTML response. Describe how C# control flow enables conditional output and loops that HTML alone cannot provide.
  Why it matters: Razor lets a server-rendered page display application data and vary its markup for each request.
• Reusable view composition: Describe layouts and partial views as reusable subviews that extract common view elements and compose them into a final HTML page. State that this reduces repeated markup across views.
  Why it matters: Reusing shared markup makes views easier to maintain and keeps a site's common structure consistent.

Key terms: Razor Pages, Razor Page, PageModel, page handler, Razor view, Razor template, Razor markup syntax, Razor, Razor templates, HTML

17.1 Views: Rendering the user interface

This section introduces Razor views as the presentation component that uses PageModel data and mixed C#/HTML templates to render dynamic HTML responses in Razor Pages.

• View role in Razor Pages: Explain where a Razor view fits in a Razor Pages request and how it produces the final HTML response after a page handler runs.
  Why it matters: Understanding the view’s place in the request flow helps you keep request handling, application logic, and UI rendering separate.
• Presentation-data separation: Describe the separation of concerns between the page handler, PageModel properties, and the Razor view, including why views should generally read prepared properties rather than call PageModel methods.
  Why it matters: Keeping data collection and HTML generation separate makes the UI easier to understand and maintain.
• Dynamic Razor template output: Explain how Razor templates combine ordinary HTML with C# constructs to generate HTML that can vary at runtime.
  Why it matters: Razor’s ability to mix markup and C# is what lets server-rendered pages adapt their output to the current user and data.
• Tag Helper purpose: State what Tag Helpers look like in a Razor template and how they can customize the HTML element they are attached to, especially when building forms.
  Why it matters: Recognizing Tag Helpers prepares you to use the form-building features introduced in the next chapter.
• Razor view compilation: Describe when Razor Pages are normally compiled and distinguish normal build-time compilation from optional runtime compilation during local development.
  Why it matters: This distinction explains why changing a deployed Razor Page normally requires rebuilding the application.

Key terms: Razor view, Razor Page, page handler, PageModel, PageResult, middleware pipeline, separation of concerns, application model, view, Razor template

17.2 Creating Razor views

This section introduces Razor views as the proper way for Razor Pages and MVC controllers to generate HTML responses while keeping UI rendering separate from request-handling logic.

• Razor views for HTML responses: Explain that Razor views should generate HTML responses for users in Razor Pages and MVC applications, rather than building HTML strings directly in page handlers or controllers.
  Why it matters: Views provide the intended place to build the user interface without mixing markup into request-handling code.
• Separation of request and UI: Describe how using Razor views supports MVC separation of concerns by keeping request logic in page handlers or controllers and HTML user-interface rendering in views.
  Why it matters: Keeping rendering separate from request logic makes an application easier to develop and maintain as its pages grow.
• View data for dynamic HTML: State that data can be passed from page handlers to Razor views, where the view can use it to generate dynamic HTML.
  Why it matters: Passing data into a view lets one template render user-facing output that reflects application data.

Key terms: Razor views, Razor Pages, MVC controllers, HTML response, page handlers, MVC separation of concerns, dynamic HTML

17.2.1 Razor views and code-behind

This section explains how a Razor Page view, its optional code-behind PageModel, and Razor directives work together to handle a request and render HTML.

• Razor view and code-behind roles: Describe the respective roles of the .cshtml Razor view and the .cshtml.cs code-behind file in a typical Razor Page. Explain that the view contains Razor markup and the template that generates HTML, while the code-behind contains the PageModel, page handlers, and typical application interactions.
  Why it matters: Separating display markup from request-handling code makes a Razor Page easier to understand and maintain.
• Page and model directives: Explain the purposes of the @page and @model directives in a Razor Page. State that @page makes the file a routable Razor Page, while @model names the PageModel associated with the view rather than relying on the files' matching names.
  Why it matters: These directives tell the Razor Pages framework whether a view can receive requests and which PageModel should serve it.
• Razor Page request processing: Trace what happens after a request is routed to a Razor Page with an associated PageModel: the framework uses @model to select the PageModel, binds properties marked with [BindProperty], runs the appropriate handler for the HTTP verb, and executes the Razor template to generate HTML. Describe the optional alternative in which no PageModel is specified and an implicit handler renders the view directly.
  Why it matters: This request flow connects routing, model binding, handler execution, and view rendering into one Razor Pages response.

Key terms: Razor view, .cshtml, code-behind, .cshtml.cs, PageModel, page handlers, @page directive, @model directive, Razor Page, [BindProperty]

17.2.2 Introducing Razor templates

This subsection introduces Razor templates as interleaved HTML and C# that render into ordinary HTML sent to the browser.

• Razor template composition: Explain that a Razor view template mixes HTML markup with C# code, using HTML to describe browser output and C# to determine dynamic parts of that output.
  Why it matters: Razor lets a server-rendered page retain readable HTML while using C# to vary what the user sees.
• Template rendering output: Describe how Razor rendering copies the plain HTML portions of a template unchanged and produces a final response containing only ordinary HTML markup for the browser.
  Why it matters: Understanding that the browser receives HTML, not Razor syntax, clarifies where Razor rendering occurs.
• Dynamic list generation: Describe how C# control flow such as a for loop can generate repetitive HTML, such as list-item elements for a list of to-do strings, instead of manually writing every repeated element.
  Why it matters: Generating repeated markup from code avoids manually duplicating HTML when the displayed data varies.
• Hardcoded and model data: Distinguish the example's hardcoded list values from the more common application case where data to display is exposed through properties on a PageModel.
  Why it matters: This distinction connects a simple static-looking template example to the data-driven pages used in an application.

Key terms: Razor view templates, HTML markup, C# code, Razor engine, rendered, HTML output, for loop, Razor template, <li> element, to-do items

17.2.3 Passing data to views

This section explains how Razor Pages pass data from page handlers to views, emphasizing PageModel properties and reserving ViewData for values shared with layouts.

• Data-passing mechanism choices: Distinguish the available ways to make data available to a Razor view and state the recommended order of use. Explain why HttpContext should not be used to transfer data between a page handler and its view, and why injecting services into views should be sparing.
  Why it matters: Choosing the appropriate mechanism keeps view data clear, typed where possible, and scoped to its real purpose.
• PageModel view data access: Describe how a Razor view receives display data from public properties on its associated PageModel. State that the @model directive identifies the PageModel type and that the view reads the instance through the uppercase Model property, such as @Model.Title.
  Why it matters: Public PageModel properties provide the standard, strongly typed and IntelliSense-supported path from handler data to rendered HTML.
• ViewData layout sharing: Explain that ViewData is a string-keyed dictionary of objects shared throughout one request, making it suitable for values such as a page title that layouts need to read. Describe setting a ViewData value in a view or in a page handler, including the [ViewData] attribute option, and explain why PageModel properties remain preferable whenever the value is only for the associated view.
  Why it matters: ViewData lets a page communicate request-specific values to shared layout markup without forcing every PageModel into a common base class.

Key terms: PageModel properties, ViewData, TempData, HttpContext, @inject, dependency injection, PageModel, @model, Model, public properties

17.3 Creating dynamic web pages with Razor

This section introduces Razor’s ability to use C# while emphasizing that Razor templates should remain simple and maintainable.

• Razor and C# capabilities: Explain that Razor syntax can express virtually anything that can be done in C#, because .cshtml files are compiled into normal C# code with raw HTML represented as strings.
  Why it matters: This explains why Razor can produce dynamic pages rather than being limited to static HTML.
• Simple template design: Justify keeping Razor templates as simple as possible even though they can contain complex C# behavior, because simpler templates are easier to work with and maintain.
  Why it matters: Keeping presentation templates simple makes an application easier to understand and change over time.

Key terms: Razor syntax, .cshtml files, C#, raw HTML, Razor templates, maintain

17.3.1 Using C# in Razor templates

This section shows how Razor templates evaluate C# expressions for HTML output and run non-output C# code in code blocks.

• Razor expression output: Explain how a Razor expression uses @ to evaluate a single C# expression and write its result directly into the HTML response. Describe when parentheses in @() are required to mark an expression containing whitespace.
  Why it matters: Razor expressions are the common way to place calculated values and PageModel data into rendered HTML.
• Literal at-sign escaping: State how to render a literal @ character rather than starting a Razor expression: write it as @@.
  Why it matters: Escaping the character prevents Razor from interpreting intended page text as C#.
• Razor code block behavior: Describe a Razor code block as normal C# enclosed by @{}, used to execute code without writing its values to HTML. Distinguish its required C# semicolons from Razor expressions, which do not need semicolons when outputting values.
  Why it matters: Choosing a code block for setup code and expressions for output keeps Razor templates valid and prevents unexpected broken HTML.

Key terms: Razor expressions, @, @(), HTML output, PageModel, ViewData, @@, Razor expression, Razor code block, @{}

17.3.2 Adding loops and conditionals to Razor templates

This section shows how Razor templates use familiar C# loops and conditionals to generate HTML dynamically while keeping view logic limited.

• Razor control-flow syntax: Describe how to use C# control-flow constructs such as if, foreach, for, and while in a Razor template by prefixing the control statement with @. Explain that Razor generally infers the transitions back and forth between C# blocks and surrounding HTML.
  Why it matters: This lets a view vary the HTML it sends to the browser based on runtime data.
• Data-driven HTML generation: Explain how loops and conditionals make a Razor view generate different HTML from the data supplied at runtime. Describe the to-do example: outstanding tasks in the model can produce a list item for each task, while conditions can hide or show portions of the UI.
  Why it matters: Dynamic rendering lets one template produce an interface that matches the current model instead of fixed static HTML.
• View-logic restraint: Justify keeping logic in Razor views simple even though loops and conditionals are available. Explain that mixing C# and HTML increases view complexity and that simple templates are easier to read and maintain.
  Why it matters: Restrained view logic makes rendered UI code easier for developers to understand and change safely.

Key terms: Razor templates, @ symbol, if, foreach, for, while, dynamic HTML, PageModel, IsComplete, Tasks

17.3.3 Rendering HTML with Raw

This section explains Razor’s default HTML encoding, why it protects against injection attacks, and the guarded use of Html.Raw() to render trusted HTML strings.

• Razor HTML encoding: Explain that Razor HTML-encodes values produced by C# expressions before writing them to the response. Describe how a string such as "<strong>Check oil</strong>" is displayed as literal text rather than interpreted as an HTML element when rendered with @task.
  Why it matters: Default encoding prevents dynamic values from unexpectedly becoming executable markup in a page.
• Html.Raw trusted markup: Describe how Html.Raw() writes a string directly to the HTML output without HTML encoding. Justify using it only when the HTML is trusted and avoiding it for user-entered or user-derived values because it can enable malicious code injection.
  Why it matters: Bypassing Razor’s normal encoding can create a serious security hole if untrusted content reaches the page.
• Html Helpers and Tag Helpers: Distinguish the legacy Html helper approach from Tag Helpers: HtmlHelper methods remain available through the Html property, but Tag Helpers are presented as the cleaner, largely superseding approach for generating dynamic markup in ASP.NET Core.
  Why it matters: Recognizing the older helper style helps you read existing views while favoring the newer Razor approach in new markup.

Key terms: Razor templates, HTML-encode, C# expressions, output stream, Html.Raw(), Html property, HTML-encoded, user input, malicious code, HtmlHelper

17.4 Layouts, partial views, and _ViewStart

This section introduces ways Razor views centralize shared markup and common view setup to reduce duplication and simplify site-wide HTML changes.

• Razor layout purpose: Explain that a Razor layout is a template containing common code that cannot be rendered directly, but is rendered together with normal Razor views.
  Why it matters: Layouts provide a single place to manage markup shared by many pages.
• Shared markup maintenance: Describe why extracting repeated HTML into layouts reduces duplication and makes application-wide markup changes easier and less error-prone.
  Why it matters: Centralizing repeated page structure means a change to shared UI does not require editing every view.

Key terms: layout, Razor views, Razor template, layouts, common markup, duplication

17.4.1 Using layouts for shared markup

This section explains how Razor layouts centralize shared page markup and insert each view's content into a common HTML structure.

• Layout purpose and organization: Explain that a layout is a Razor template containing markup shared by multiple pages, reducing duplication of common HTML such as headers, footers, CSS, and JavaScript references. Describe that an application can use multiple, nested layouts for different areas of the application.
  Why it matters: Layouts let you maintain shared page structure in one place while allowing different parts of an application to have appropriate designs.
• View and layout composition: Describe how a view selects a layout by setting its Layout property and how the layout's @RenderBody() call marks where that view's content is inserted. State that a layout must call @RenderBody() and is not a standalone routed Razor Page, so it does not use the @page directive.
  Why it matters: Understanding this composition explains how a page's specific content becomes part of the final HTML sent to the browser.
• Layout conventions and ViewData: Describe the common convention of placing shared layouts in Pages/Shared and naming the base layout _Layout.cshtml, which permits a short layout name such as "_Layout". Explain that a layout can read ViewData, for example to render a page title in the HTML title element and browser tab.
  Why it matters: Following these conventions keeps shared templates easy to find and lets each view supply page-specific values to shared markup.

Key terms: layout files, Razor templates, Pages/Shared, _Layout.cshtml, Layout property, @RenderBody(), child views, @page directive, ViewData, <title>

17.4.2 Overriding parent layouts using sections

This section explains how Razor sections place child-view content into specific locations in layouts, including nested layouts and rules for required content.

• Razor section placement: Explain how a child view defines a named Razor section with @section and how its parent layout inserts that content with @RenderSection(). Describe how sections let a view place different content, such as main and sidebar content, in different layout locations.
  Why it matters: Sections let a layout control the page structure while each view supplies content for the appropriate regions.
• Required and optional sections: Distinguish required sections from optional sections in a layout. Explain that a required section must be declared by every view using the layout, whereas an optional section may be omitted and then produces no rendered HTML, as with a per-view Scripts section.
  Why it matters: Choosing whether a section is required lets layouts enforce essential regions without forcing every page to emit unnecessary markup or scripts.
• Nested layout section rules: Describe how a layout can itself set its Layout property to create a nested layout hierarchy. State the layout flow-control rules: an unrendered defined section must be ignored with IgnoreSection(), and a layout must either render its body with RenderBody() or ignore it with IgnoreBody() to avoid an exception.
  Why it matters: These rules let you compose multi-level layouts without leaving required view content unhandled.

Key terms: sections, @section, @RenderSection(), child view, parent layout, required sections, optional sections, Scripts, nested layouts, Layout

17.4.3 Using partial views to encapsulate markup

This section explains how Razor partial views split reusable HTML into focused templates, how they are rendered and located, and when a view component is more appropriate.

• Partial view purpose: Explain that a partial view is a reusable part of a Razor view used to split large views into smaller chunks or reuse a piece of markup across multiple Razor Pages. Distinguish it from a Razor Page by saying that it renders HTML only and does not handle requests, model binding, validation, or page handlers.
  Why it matters: Partial views let you reuse presentation markup without copying it between pages.
• Partial view rendering: Describe rendering a partial with the <partial /> Tag Helper by supplying the partial view's name and the model data it should render. Explain that different Razor Pages, such as single-item and recent-items pages, can use the same partial with their relevant data.
  Why it matters: Passing a partial its display data makes one markup template usable in multiple places.
• Partial view discovery: Trace how Razor locates a partial referenced by name without an absolute path or file extension: it searches upward from the invoking Razor Page's folder through parent Pages folders, then Pages/Shared and Views/Shared, and uses the first match. Describe how including the .cshtml extension restricts the lookup to the current folder, while an absolute path restricts it to that exact location.
  Why it matters: Knowing the lookup rules helps you place shared partials intentionally and diagnose why the wrong file is found.
• View component boundary: Distinguish partial views from view components by explaining that partials are for reusable markup, whereas a view component can execute arbitrary code as well as render HTML and is preferable when the reusable UI needs significant code or business logic. State that ASP.NET Core replaced legacy child actions with view components rather than invoking controller actions from views.
  Why it matters: Choosing a view component for logic-heavy UI keeps views from directly invoking controller actions.

Key terms: partial views, Razor Pages, PageModel, handlers, <partial /> Tag Helper, model, _ToDo.cshtml, partial view discovery, Pages/Shared, Views/Shared

17.4.4 Running code on every view with _ViewStart and _ViewImports

This section shows how _ViewImports and _ViewStart remove repeated Razor view setup, and how partial views can support AJAX updates with trade-offs.

• Shared Razor directives: Describe how _ViewImports.cshtml supplies Razor directives, such as @using, @model, and @addTagHelper, to views in its folder and descendant folders. Distinguish directives that belong in _ViewImports from arbitrary C# code, which does not.
  Why it matters: _ViewImports keeps repeated view declarations in one place instead of copying them into every Razor view.
• Default layout initialization: Explain how _ViewStart.cshtml runs Razor code before each Razor Page view, typically to set a default Layout. Describe how an individual Razor Page can override that layout and identify that _ViewStart does not run for layouts or partial views.
  Why it matters: A shared default layout avoids repeating layout assignments while still allowing a page to choose a different layout.
• Special file scope and order: State that the Razor engine requires the exact names _ViewImports.cshtml and _ViewStart.cshtml, and that placing them in the root Pages folder applies them across the app's pages rather than placing them in Shared. Describe how additional files in a Pages subfolder apply to that subset of views after the root-level files.
  Why it matters: Correct filenames, placement, and ordering determine whether shared view configuration is found and how it is overridden for a folder.
• AJAX partial-view trade-offs: Explain that a server-rendered Razor app can use JavaScript and AJAX to request and update part of a page without a full-page reload, often by exposing partial views through additional Razor Page handlers. Distinguish the potential responsiveness and reduced data transfer from the added complexity, especially in large or highly dynamic applications.
  Why it matters: This helps you decide whether incremental AJAX updates fit a Razor app or whether a client-side framework with APIs, or Blazor, is a better fit.

Key terms: _ViewImports.cshtml, Razor directives, @using, @model, @addTagHelper, _ViewStart.cshtml, Layout, Razor Page views, layouts, partial views

17.5 Summary

This summary consolidates how Razor views generate dynamic HTML, share data and reusable markup, and safely organize view-wide behavior.