---
title: razor syntax reference for ASP.NET Core
author: rick-anderson
description: Learn about Razor markup syntax for embedding server-based code into webpages.
ms.author: riande
ms.date: 02/12/2020
no-loc: [appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR]
uid: mvc/views/razor
---
# Razor syntax reference for ASP.NET Core
By [Rick Anderson](https://twitter.com/RickAndMSFT), [Taylor Mullen](https://twitter.com/ntaylormullen), and [Dan Vicarel](https://github.com/Rabadash8820)
Razor is a markup syntax for embedding server-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 components](xref:blazor/components/index) files (*.razor*).
## Rendering HTML
The default Razor language is HTML. Rendering HTML from Razor markup is no different than rendering HTML from an HTML file. HTML markup in *.cshtml* Razor files is rendered by the server unchanged.
## 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](#razor-reserved-keywords), it transitions into Razor-specific markup. Otherwise, it transitions into plain C#.
To escape an `@` symbol in Razor markup, use a second `@` symbol:
```cshtml
@@Username
```
The code is rendered in HTML with a single `@` symbol:
```html
@Username
```
HTML attributes and content containing email addresses don't treat the `@` symbol as a transition character. The email addresses in the following example are untouched by Razor parsing:
```cshtml
Support@contoso.com
```
## Implicit Razor expressions
Implicit Razor expressions start with `@` followed by C# code:
```cshtml
@DateTime.Now
@DateTime.IsLeapYear(2016)
```
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:
```cshtml
@await DoSomething("hello", "world")
```
Implicit expressions **cannot** contain C# generics, as the characters inside the brackets (`<>`) are interpreted as an HTML tag. The following code is **not** valid:
```cshtml
@GenericMethod()
```
The preceding code generates a compiler error similar to one of the following:
* The "int" element wasn't closed. All elements must be either self-closing or have a matching end tag.
* Cannot convert method group 'GenericMethod' to non-delegate type 'object'. Did you intend to invoke the method?`
Generic method calls must be wrapped in an [explicit Razor expression](#explicit-razor-expressions) or a [Razor code block](#razor-code-blocks).
## Explicit Razor expressions
Explicit Razor expressions consist of an `@` symbol with balanced parenthesis. To render last week's time, the following Razor markup is used:
```cshtml
Last week this time: @(DateTime.Now - TimeSpan.FromDays(7))
```
Any content within the `@()` parenthesis is evaluated and rendered to the output.
Implicit expressions, described in the previous section, generally can't contain spaces. In the following code, one week isn't subtracted from the current time:
[!code-cshtml[](razor/sample/Views/Home/Contact.cshtml?range=17)]
The code renders the following HTML:
```html
Last week: 7/7/2016 4:39:52 PM - TimeSpan.FromDays(7)
```
Explicit expressions can be used to concatenate text with an expression result:
```cshtml
@{
var joe = new Person("Joe", 33);
}
Age@(joe.Age)
```
Without the explicit expression, `Age@joe.Age
` is treated as an email address, and `Age@joe.Age
` is rendered. When written as an explicit expression, `Age33
` is rendered.
Explicit expressions can be used to render output from generic methods in *.cshtml* files. The following markup shows how to correct the error shown earlier caused by the brackets of a C# generic. The code is written as an explicit expression:
```cshtml
@(GenericMethod())
```
## Expression encoding
C# expressions that evaluate to a string are HTML encoded. C# expressions that evaluate to `IHtmlContent` are rendered directly through `IHtmlContent.WriteTo`. C# expressions that don't evaluate to `IHtmlContent` are converted to a string by `ToString` and encoded before they're rendered.
```cshtml
@("Hello World")
```
The code renders the following HTML:
```html
<span>Hello World</span>
```
The HTML is shown in the browser as:
```html
Hello World
```
`HtmlHelper.Raw` output isn't encoded but rendered as HTML markup.
> [!WARNING]
> Using `HtmlHelper.Raw` on unsanitized user input is a security risk. User input might contain malicious JavaScript or other exploits. Sanitizing user input is difficult. Avoid using `HtmlHelper.Raw` with user input.
```cshtml
@Html.Raw("Hello World")
```
The code renders the following HTML:
```html
Hello World
```
## 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 and are defined in order:
```cshtml
@{
var quote = "The future depends on what you do today. - Mahatma Gandhi";
}
@quote
@{
quote = "Hate cannot drive out hate, only love can do that. - Martin Luther King, Jr.";
}
@quote
```
The code renders the following HTML:
```html
The future depends on what you do today. - Mahatma Gandhi
Hate cannot drive out hate, only love can do that. - Martin Luther King, Jr.
```
::: moniker range=">= aspnetcore-3.0"
In code blocks, declare [local functions](/dotnet/csharp/programming-guide/classes-and-structs/local-functions) with markup to serve as templating methods:
```cshtml
@{
void RenderName(string name)
{
Name: @name
}
RenderName("Mahatma Gandhi");
RenderName("Martin Luther King, Jr.");
}
```
The code renders the following HTML:
```html
Name: Mahatma Gandhi
Name: Martin Luther King, Jr.
```
::: moniker-end
### Implicit transitions
The default language in a code block is C#, but the Razor Page can transition back to HTML:
```cshtml
@{
var inCSharp = true;
Now in HTML, was in C# @inCSharp
}
```
### Explicit delimited transition
To define a subsection of a code block that should render HTML, surround the characters for rendering with the Razor `` tag:
```cshtml
@for (var i = 0; i < people.Length; i++)
{
var person = people[i];
Name: @person.Name
}
```
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 `` tag is useful to control whitespace when rendering content:
* Only the content between the `` tag is rendered.
* No whitespace before or after the `` tag appears in the HTML output.
### Explicit line transition
To render the rest of an entire line as HTML inside a code block, use `@:` syntax:
```cshtml
@for (var i = 0; i < people.Length; i++)
{
var person = people[i];
@:Name: @person.Name
}
```
Without the `@:` in the code, a Razor runtime error is generated.
Extra `@` characters in a Razor file can cause compiler errors at statements later in the block. These compiler errors can be difficult to understand because the actual error occurs before the reported error. This error is common after combining multiple implicit/explicit expressions into a single code block.
## Control structures
Control structures are an extension of code blocks. All aspects of code blocks (transitioning to markup, inline C#) also apply to the following structures:
### Conditionals `@if, else if, else, and @switch`
`@if` controls when code runs:
```cshtml
@if (value % 2 == 0)
{
The value was even.
}
```
`else` and `else if` don't require the `@` symbol:
```cshtml
@if (value % 2 == 0)
{
The value was even.
}
else if (value >= 1337)
{
The value is large.
}
else
{
The value is odd and small.
}
```
The following markup shows how to use a switch statement:
```cshtml
@switch (value)
{
case 1:
The value is 1!
break;
case 1337:
Your number is 1337!
break;
default:
Your number wasn't 1 or 1337.
break;
}
```
### Looping `@for, @foreach, @while, and @do while`
Templated HTML can be rendered with looping control statements. To render a list of people:
```cshtml
@{
var people = new Person[]
{
new Person("Weston", 33),
new Person("Johnathon", 41),
...
};
}
```
The following looping statements are supported:
`@for`
```cshtml
@for (var i = 0; i < people.Length; i++)
{
var person = people[i];
Name: @person.Name
Age: @person.Age
}
```
`@foreach`
```cshtml
@foreach (var person in people)
{
Name: @person.Name
Age: @person.Age
}
```
`@while`
```cshtml
@{ var i = 0; }
@while (i < people.Length)
{
var person = people[i];
Name: @person.Name
Age: @person.Age
i++;
}
```
`@do while`
```cshtml
@{ var i = 0; }
@do
{
var person = people[i];
Name: @person.Name
Age: @person.Age
i++;
} while (i < people.Length);
```
### Compound `@using`
In C#, a `using` statement is used to ensure an object is disposed. In Razor, the same mechanism is used to create HTML Helpers that contain additional content. In the following code, HTML Helpers render a `