Razor syntax overview

What is Razor?

• Razor is a markup syntax for embedding .NET based code into webpages.

• The Razor syntax consists of Razor markup, C# and HTML.

• Files containing Razor generally have a .cshtml file extension.

• Razor is also found in Razor component files, with an extension of .razor

• Razor syntax is similar to the templating engines of various JavaScript single-page application (SPA) frameworks, such as Angular, React, VueJs, and Svelte.

Razor syntax consists of Razor markup, C# and HTML

Razor syntax

• Razor supports C# and uses the @ symbol to transition from HTML to C#.

• Razor evaluates C# expressions and renders them in the HTML output.

• When an @ symbol is followed by a Razor reserved keyword, it transitions into Razor-specific markup.

To escape an @ symbol in Razor markup, use a second @ symbol as shown below:

<p>@@Username</p>

The code is rendered in HTML with a single @ symbol:

<p>@Username</p>

uses the @ symbol to transition from HTML to C#

HTML attributes and content containing email addresses don't treat the @ symbol as a transition character

Implicit Razor expressions

Implicit Razor expressions start with @ followed by C# code:

<p>@DateTime.Now</p>
<p>@DateTime.IsLeapYear(2016)</p>

With the exception of the C# await keyword, implicit expressions must not contain spaces. If the C# statement has a clear ending, spaces can be intermingled:

<p>@await DoSomething("hello", "world")</p>

implicit expressions must not contain spaces.

Explicit Razor expressions

Explicit Razor expressions consist of an @ symbol with balanced parenthesis. To render last weeks' time, the following Razor markup is used:

<p>Last week this time: @(DateTime.Now - TimeSpan.FromDays(7))</p>

Any content within the @()parenthesis is evaluated and rendered to the output.

Why we need paranthesis?

Razor expressions generally can't contain spaces. In the following code, one week is not subtracted from the current time!

<p>Last week: @DateTime.Now - TimeSpan.FromDays(7)</p>

The code renders the following HTML:

<p>Last week: 7/7/2016 4:39:52 PM - TimeSpan.FromDays(7)</p>

Hence, we need parenthesis to enclose the complete c# expression in such cases.

Raw HTML

HtmlHelper.Raw output isn't encoded but rendered as HTML markup.

@Html.Raw("<span>Hello World</span>")

The code renders the following HTML:

<span>Hello World</span>

Razor code blocks

Razor code blocks start with @ and are enclosed by {}. Unlike expressions, C# code inside code blocks isn't rendered.

Code blocks and expressions in a view share the same scope!

@{
    var quote = "The future depends on what you do today. - Mahatma Gandhi";
}

<p>@quote</p>

@{
    quote = "Hate cannot drive out hate, only love can do that. - Martin Luther King";
}

<p>@quote</p>

The code renders the following HTML:

<p>The future depends on what you do today. - Mahatma Gandhi</p>
<p>Hate cannot drive out hate, only love can do that. - Martin Luther King, Jr.</p>

Implicit transitions

The default language in a code block is C#, but the Razor Page can transition back to HTML:

@{
    var inCSharp = true;
    <p>Now in HTML, was in C# @inCSharp</p>
}

Explicit delimited transition

To define a subsection of a code block that should render HTML, surround the characters for rendering with the Razor <text> tag:

@for (var i = 0; i < people.Length; i++)
{
    var person = people[i];
    <text>Name: @person.Name</text>
}

Use this approach to render HTML that isn't surrounded by an HTML tag. Without an HTML or Razor tag, a Razor runtime error occurs.

The <text>tag is useful to control whitespace when rendering content:

• Only the content between the <text> tag is rendered.

• No whitespace before or after the <text> tag appears in the HTML output