Three kinds of comment
| Comment | Where | What happens |
|---|---|---|
@* ... *@ | Anywhere: markup, code blocks, inside groups in an expression, in the attribute area of a tag, between a directive and its block. | The Razor comment. It is removed before anything else is looked at: the text inside is not parsed, so it may hold @{, unbalanced tags or C# comments. It does not nest; the first *@ ends it. If *@ never comes the comment runs to the end of the file and the parser reports it ("End of file was reached before the end of the block comment"). |
<!-- ... --> | Markup | An HTML comment, sent to the browser. Razor code inside it still runs: <!-- @DateTime.Now --> writes the time. Use a Razor comment to hide code. |
// and /* */ | Code blocks, expressions | C# comments: the text is skipped when looking for braces and parentheses. Not sent to the browser. |
@*
@{ var hidden = 1; }
<!-- not output, not parsed -->
*@
<!-- @DateTime.Now is evaluated even here -->
@{
// a C# comment
/* and another */
}
Escaping
| To write | Write |
|---|---|
a literal @ | @@ (in markup, in an attribute value, and at the start of an attribute name) |
| an email address | Nothing: name@host.com is text because of the email rule; use @@ to be safe |
| a Razor word as a name | @(functions), @(model) |
| a C# keyword that Razor handles as a name | @(@case): the first @ escapes Razor, the second C# |
CSS at-rules in a <style> element | @@media (...) { }, since @media would start code |
a < that is not a tag | < (HTML), or put a space after it in markup text |
a literal @ in C# code | Inside strings and comments it needs no escape; @identifier is a verbatim identifier, and @@ in code is accepted as one |
| a tag that is a tag helper, as plain HTML | the opt-out character on both tags: <!span>...</!span> |
JavaScript in <script> is markup text for the parser, with two consequences: @ still starts code in it (so var id = @Model.Id; works, and a literal at sign must be @@), and < does not start a tag, so if (a < b) and a string that contains </div> are fine. The script ends at the first </script. A script whose type attribute is exactly text/html is read as ordinary markup instead.
Attributes
An attribute value, in double or single quotes or unquoted, is markup text in which @ starts code. An unquoted value ends at white space, >, < or />; a quoted one at the closing quote (it can span lines). A value may mix text and code: class="btn @size @(active ? "on" : "")".
Conditional attributes
When the whole value of an attribute is one expression (or text and expressions), the attribute is written only if there is something to write. A null or false value removes the attribute; true writes the attribute with its own name; an empty string writes attr=""; any other value is written. data- attributes are exempt: they are written even when null or false (data-active="False").
<div class="@false">False</div>
<div class="@("")">Empty</div>
<input type="checkbox" checked="@true" />
<input type="checkbox" checked="@null" />
<div data-id="@null" data-active="@false"></div>
White space and new lines
Markup keeps its white space and new lines exactly as written. The rules below say where Razor itself removes white space around its own constructs, so that the output has no stray blank lines. They are the behaviour of the parser, not of the browser.
- Directive lines. A directive and the white space before it on its line, and its new line, are not written.
- Code blocks. After the closing
}of a top-level@{ ... }or control-flow statement, white space and one new line that follow on the same line are not written. - Markup in code. A markup block started by a tag owns the white space before it and, after its end tag, the trailing white space and one new line. The
<text>tag is special: its own tags write nothing, and the white space around them is code, so nothing is added. @:lines. The line is markup including its new line; the indent before@:is code.- Between
@ifandelse. White space between}andelsebelongs to the statement (it is skipped when anelsefollows) and to the markup otherwise. - Components. By default, white space is removed: at the start and the end inside an element, at the start and end inside a
RenderFragmentparameter (such as child content passed to another component), and before and after a code block such as@ifor@foreach.@preservewhitespace truekeeps it.