Razor enables you to start with static HTML (or any textual
content) and then make it dynamic by adding server code to it. One of the
core design goals behind Razor is to make this coding process fluid, and to enable
you to quickly integrate server code into your HTML markup with a minimum of
keystrokes.
To see a quick example of this let’s create a simple “hello
world” sample that outputs a message like so:
Building it with .ASPX Code Nuggets
If we were to build the above “hello world” sample using
ASP.NET’s existing .ASPX markup syntax, we might write it using <%= %>
blocks to indicate “code nuggets” within our HTML markup like so:
One observation to make about this “hello world” sample is
that each code nugget block requires 5 characters (<%= %>) to denote the
start and stop of the code sequence. Some of these characters (in
particular the % key – which is center top on most keyboards) aren’t the
easiest to touch-type.
Building it with Razor Syntax
You denote the start of a code block with Razor using a @
character. Unlike <% %> code nuggets, Razor does not require you to
explicitly close the code-block:
The Razor parser has semantic knowledge of C#/VB code used
within code-blocks – which is why we didn’t need to explicitly close the code
blocks above. Razor was able to identify the above statements as
self-contained code blocks, and implicitly closed them for us.
Even in this trivial “hello world” example we’ve managed to
save ourselves 12 keystrokes over what we had to type before. The @
character is also easier to reach on the keyboard than the % character which
makes it faster and more fluid to type.
Loops and Nested HTML Sample
Let’s look at another simple scenario where we want to list
some products (and the price of each product beside it):
Building it with .ASPX Code Nuggets
If we were to implement this using ASP.NET’s existing .ASPX
markup syntax, we might write the below code to dynamically generate a
<ul> list with <li> items for each product inside it:
Building it with Razor Syntax
Below is how to generate the equivalent output using Razor:
Notice above how we started a “foreach” loop using the @
symbol, and then contained a line of HTML content with code blocks within
it. Because the Razor parser understands the C# semantics in our code
block, it was able to determine that the <li> content should be contained
within the foreach and treated like content that should be looped. It
also recognized that the trailing } terminated the foreach statement.
Razor was also smart enough to identify the @p.Name and
@p.Price statements within the <li> element as server code – and execute
them each time through the loop. Notice how Razor was smart enough to
automatically close the @p.Name and @p.Price code blocks by inferring how the
HTML and code is being used together.
The ability to code like this without having to add lots of
open/close markers throughout your templates ends up making the whole coding
process really fluid and fast.
If-Blocks and Multi-line Statements
Below are a few examples of other common scenarios:
If Statements
Like our foreach example above, you can embed content within
if statements (or any other C# or VB language construct), without having to be
explicit about the code block’s begin/end. For example:
Multi-line Statements
You can denote multiple lines of code by wrapping it within
a @{ code } block like so:
Notice above how variables can span multiple server code
blocks – the “message” variable defined within the multi-line @{ } block, for
example, is also being used within the @message code block. This is
conceptually the same as the <% %> and <%= %> syntax within .aspx
markup files.
Multi-Token Statements
The @( ) syntax enables a code block to have multiple
tokens. For example, we could re-write the above code to concatenate a string
and the number together within a @( code ) block:
Integrating Content and Code
The Razor parser has a lot of language smarts built-into it
– enabling you to rely on it to do the heavily lifting, as opposed to you
having to explicitly do it yourself.
Does it break with email addresses and other usages of @ in
HTML?
Razor’s language parser is clever enough in most cases to
infer whether a @ character within a template is being used for code or static
content. For example, below I’m using a @ character as part of an email
address:
When parsing a file, Razor examines the content
on the right-hand side of any @ character and attempts to determine whether it
is C# code (if it is a CSHTML file) or VB code (if it is a VBHTML file) or
whether it is just static content. The above code will output the
following HTML (where the email address is output as static content and the
@DateTime.Now is evaluated as code:
In cases where the content is valid as code as well (and you
want to treat it as content), you can explicitly escape out @ characters by
typing @@.
Identifying Nested Content
When nesting HTML content within an if/else, foreach or
other block statement, you should look to wrap the inner content within an HTML
or XML element to better identify that it is the beginning of a content block.
For example, below I’ve wrapped a multi-line content block
(which includes a code-nugget) with a <span> element:
This will render the below content to the client – note that
it includes the <span> tag:
You can optionally wrap nested content with a <text>
block for cases where you have content that you want to render to the client
without a wrapping tag:
The above code will render the below content to the client –
note that it does not include any wrapping tag:
HTML Encoding
By default content emitted using a @ block is automatically
HTML encoded to better protect against XSS attack scenarios.