The at sign in markup
In markup, the character @ is a transition: it ends the HTML and starts a Razor construct. The parser decides in this order, looking only at the characters around it.
@*starts a Razor comment that runs to*@.@@is an escaped at sign: the output is one@, and nothing after it is code.- The email rule. If the character before the
@is a letter or a digit (in the same run of text, with no space, tag character or quote between) and the character after it is a letter or a digit, the@is ordinary text. SoSupport@contoso.comanda1@b2are text;(@x),mail @youandx-@yare code. This applies in text, in attribute names and in attribute values alike. Where it gets in the way (Age@(joe.Age)is code only because(is not a letter;Age@joe.Ageis text), write an explicit expression or put a space or tag before the@. - Otherwise the character after the
@decides:
| After the @ | The construct |
|---|---|
{ | A code block, to the matching }. |
( | An explicit expression, to the matching ). |
a letter or _ (or another Unicode identifier start) | A word. It is a directive if the file kind has a directive of that exact spelling (case-sensitive); a control-flow keyword (if for foreach while do switch try lock using, and await) starts a statement; helper and class are errors; anything else starts an implicit expression. |
| end of the file | An error: "End-of-file was found after the @ character". |
| a space or a line break | An error: a space or line break was encountered after the @ character. |
any other character (#, !, :, < ...) | An error: the character is not valid at the start of a code block. (Inside a code block, @: and @< are valid: see Code blocks and control flow.) |
The keywords of C# that are not in the control-flow list are not special: @this.Title and @typeof(X) are implicit expressions that start with a keyword word. The Razor words are escaped like C# keywords: write @(functions) to use the name functions as an expression, and @(@case) for a C# keyword (the first @ for Razor, the second for C#).
Implicit expressions
An implicit expression is @ and a name followed by whatever of the following continues it. It writes the value, HTML-encoded. The parser reads the first identifier, then repeats these steps, stopping at the first character that fits none of them:
| Next characters | What happens |
|---|---|
( or [ | The whole parenthesised or bracketed group is taken, to the matching closing character, and the steps repeat. Inside the group anything C# goes: strings, characters, comments, nested groups, and Razor templates @<tag>. Spaces and new lines are allowed inside. If no matching closer is found, the parser goes back to before the group, reports a missing closing character, and takes everything up to the next < as the expression. |
. followed by an identifier or keyword | The dot and the member are taken and the steps repeat. A dot that is not followed by a name is left out: @Model.Name. writes the value then a full stop. (Inside a code block, a trailing dot is kept.) |
?. and ?[ | The null-conditional operators continue the chain; ?. must be followed by a name. |
!., !?, ![, !( | The C# null-forgiving operator continues the chain. A ! that is not followed by one of these is text: Hello @Person! writes an exclamation mark. |
| anything else | The expression ends. In particular a space, < (so a generic type argument list ends it: @Foo<int>() is the expression Foo followed by the markup <int>()), ;, ,, ", +, = and a new line all end it. |
<p>@Model.Items[0].Name.ToUpper()</p> <!-- one expression -->
<p>@Model.Count items</p> <!-- ends at the space -->
<p>@a.B(1, "x)").C@D</p> <!-- the call is one group; @D after C is a new expression -->
<p>@list?.First()?.Name</p> <!-- null-conditional chain -->
<p>Total: @total.</p> <!-- the full stop is text -->
@await
@await is the one implicit expression that may contain spaces right after the keyword: @await Html.PartialAsync("x"). The word await is taken, then spaces and tabs, then the expression follows the rules above. @await foreach (...) starts an asynchronous foreach statement instead.
Explicit expressions
@( starts an explicit expression: everything up to the matching ) is C#, whatever it holds. Only the round brackets are counted; strings, characters, comments and templates inside are skipped over as the C# lexer would. It is the way to write an expression with spaces, a generic call, an operator, or a value glued to text:
<p>Last week: @(DateTime.Now - TimeSpan.FromDays(7))</p>
<p>Age@(joe.Age)</p>
<p>@(GenericMethod<int>())</p>
<p>@(cond ? "yes" : "no")</p>
If the closing parenthesis is missing, the parser reports that the explicit expression block is missing it and takes the rest of the line as the expression. An explicit expression is also what a Razor keyword needs when used as a name (@(model) in a view).
How a value is written
A string value is HTML-encoded; a value that is an IHtmlContent is written as it is; any other value is converted with ToString and encoded. In a component the value goes to the render tree as text. @Html.Raw(s) writes s unencoded. In an attribute value, a value of null or false removes the attribute (conditional attributes: see Comments, escaping and whitespace), and true writes the attribute with its own name as its value.
Markup in an attribute
In an attribute value, in quotes or not, @ follows the same rules, including the email rule. In a view, an @ where an attribute name could begin is code (<input @(ok ? "checked" : "") />) and @@ there is an escaped at sign in the name. In a component an @ at the start of an attribute name begins a directive attribute instead.