One file, one class
The Razor compiler reads one file and writes one C# class. For .razor the class derives from ComponentBase (or the type named by @inherits) and its BuildRenderTree method describes the markup. For .cshtml the class derives from RazorPage<TModel> (or PageBase for a Razor Page) and its ExecuteAsync method writes the markup and runs the code in order. A file never refers to another by including its text: files are combined by name, by layout, by partial views, by component tags, and by the import files below.
The file kind (component or legacy view) is decided by the extension: .razor is a component, .cshtml is a view, and anything else a project names is treated as a view. The kind decides which directives exist (see Directives) and whether @ at the start of an attribute name is a directive attribute (components) or a C# expression (views).
Kinds of file
| File | What it is | Notes |
|---|---|---|
Counter.razor | A Blazor component | The file name is the component name: <Counter />. Routable when it has @page. A partial class in Counter.razor.cs may hold the code; Counter.razor.css is scoped CSS. |
_Imports.razor | Directives for every component in its folder and below | Typically @using lines and @layout. The name starts with an underscore, so it is never a component. |
Index.cshtml with @page | A Razor Page | Routable by file location or by the route template after @page. A Index.cshtml.cs page model usually sits beside it and is named by @model. |
Index.cshtml without @page | An MVC view | Found by controller and action name (Views/Home/Index.cshtml) or by name from return View("Name"). |
_Layout.cshtml | A layout view | Holds the page frame with @RenderBody() and @RenderSection(...). Named by Layout = "..." in a view or in _ViewStart.cshtml. |
_ViewStart.cshtml | Code that runs before each view in its folder and below | Usually just @{ Layout = "_Layout"; }. |
_ViewImports.cshtml | Directives for every view in its folder and below | @using, @addTagHelper, @namespace, @inject, @model type of a base page, @inherits. |
_Partial.cshtml, Shared/*.cshtml | Partial views, view component views, editor and display templates | Rendered by <partial name="...">, Html.PartialAsync or a view component. |
Page.vbhtml, _PageStart.vbhtml | Visual Basic views and the code that runs before them | See Visual Basic Razor. |
Import files
An import file holds only directives (and, in _ViewStart, code). The compiler looks for the file with that name in the folder of the view, then in each parent folder up to the project root, and applies them outermost first, so the innermost file and the view itself have the last word. Singly-occurring directives such as @namespace are overridden by the nearer file; repeatable ones such as @using and @inject accumulate.
@using System.Net.Http
@using Microsoft.AspNetCore.Components.Routing
@using static Microsoft.AspNetCore.Components.Web.RenderMode
@layout MainLayout
_Imports.razor for a Blazor app.@using MyApp
@using MyApp.Models
@namespace MyApp.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
_ViewImports.cshtml for Razor Pages.With @namespace in an import file, the namespace of each file is that value plus the folder path below the import file: with @namespace Hello.World in Pages/_ViewImports.cshtml, the page Pages/MorePages/Page.cshtml is in Hello.World.MorePages. The same holds for components and _Imports.razor.
Text encoding and line endings
A Razor file is text, normally UTF-8 with or without a byte order mark (Visual Studio writes one; the templates carry it). The scanner treats \n, \r\n and a lone \r as line ends in markup and in code, and the byte order mark as nothing. Line endings are kept in the output of a view, so a file's line endings reach the browser; Razor does not normalise them.
How the file is read
The document is markup at the start. The parser walks it left to right in two modes: markup (HTML tokens: text, tags, attributes, comments, @) and code (C# tokens, entered by an @ and left when the construct ends). Each construct that starts with @ decides for itself where it ends; the next page gives those rules exactly. Directives that take a block (@code, @functions, @section) are the only ones that nest braces of their own.
<h1>@title</h1> @* markup, then an implicit expression, then markup *@
@if (items.Any()) @* code: the keyword, a parenthesised condition, a block *@
{
<ul> @* the block holds markup again *@
@foreach (var i in items) { <li>@i</li> }
</ul>
}
@ or by a tag at the start of a statement.