What are WebPages and Razor – how do we (ASP.NET developers) use them to build Web Applications.  This is the subject of this series of articles.  In part 1 I described how you can use WebMatrix to build a simple site using the new CSHTML file type, and in part 2 I introduced the new Razor syntax and how it compares with the syntax used in ASP.NET WebForms.  In this article I will dive deeper into the new Syntax.

The @ Operator

In the previous article I focused on the @ operator and how it used by the Razor parser to switch from markup (HTML) to code (C# or VB.NET).

Razor understands C# (and VB.NET) syntax so it is able to support the various language constructs.  Figures 1-3 show 3 simple C# constructs and how they would work in Razor.

Figure 1 – Inline Expressions

Figure 2 – Single Statement Blocks

Figure 3 – Multiple Statement Blocks

Note that when using single or multiple statement blocks that the C# “{}” braces are used to surround the code.

Once you are inside a block of C# code then anything that is valid C# is allowed to be used such as for loops, while statements and if else statements.

As mentioned in the previous article the Razor parser is smart and as long as the intention is clear can detect when switching back to markup, so the code in Figure 4 is valid.  As the code in line 25 ends with a “;” and the code which starts line 26 is not valid C# the parser automatically switches back to markup and recognizes the <p> tag.

Figure 4 – Automatic detection of markup

The @: Operator and <text></text> Tag

If it cannot be made clear that the intention is to switch back to markup then there are two ways you can indicate that the following text should be considered markup, – the @: Operator and the <text> tag.

The @: Operator can be used in code to indicate that the rest of the line is text or markup. (see Figure 5)

Figure 5 – Using the @: Operator

In this example, the @: operator forces Razor to switch back to markup mode.  Without the @: operator the Razor parser assumes this is C# (although not valid), because it knows it is not a valid markup tag.

The <text></text> tag is a pseudo markup tag that identifies everything between the opening and closing elements as text.  It is most useful when the content stretches over more than one line. (see Figure 6)

Figure 6 – Using the <text></text> Tag

Note that once inside the pseudo-markup the @ operator still switches into code – the <text> element is treated the same as any markup tag – it is just ignored as real markup.

Comments - The @* and *@ Operators

Although Razor has a limited syntax, just like any other syntax it may be necessary to place comments in Razor code.  If we are in markup then the standard <!-- --> syntax is used to add comments to markup which are not rendered in the browser.  If we are in code then the standard //  or /* */ syntax is used to add comments to the C# code, which is ignored by the C# compiler. 

In addition Razor provides its own comments which are ignored by the Razor parser.

Figure 7 – Razor comments

That’s it – that’s all you need to know to write your own Razor code.  of course you need to understand HTML markup and a programming language supported by Razor (currently C# and VB.NET), but that is beyond the scope of this article.

What are WebPages and Razor – how do we (ASP.NET developers) use them to build Web Applications.  This is the subject of this new series of articles.  In part 1 I described how you can use WebMatrix to build a simple site using the new CSHTML file type.

Why Razor?

So why do we need a new syntax and parser for ASP.NET?  We already have the ability to combine markup and code in ASP.NET Web Forms (ASPX and ASCX pages). 

Lets look at some traditional ASP.NET code, where we are rendering a table of squares, using a mixture of HTML markup and C# code (Figure 1).

Figure 1 – Traditional ASP.NET

The problem with the traditional ASP.NET parser used in WebForms is that it is not very smart as it requires explicit delimiters – the pair of “bumble-bees” <% %>, so called because of their default syntax highlighting in Visual Studio - to switch back and forth from HTML markup to C# code.

We compare this with the same code using the new Razor syntax (Figure 2).

Figure 2 – Razor code

Notice that in Figure 1 there are 8 delimiters in the traditional ASP.NET syntax – 4 to start code and 4 to return to HTML, while the same code in the Razor syntax (Figure 2) only requires 3 delimiters (the @ symbol). 

The Razor parser is much smarter.  It knows and understands the language (C# or VB), and makes smart decisions about what is markup and what is code.  Also the delimiter used is a single character, which makes the combined markup and code cleaner and more readable, and more readable code is easier to understand.

How does it work?

So what makes the Razor parser smarter?  We will use the example in Figure 2 to highlight how it works.

In line 8 of the example code the first “@” symbol is used to indicate the beginning of C# code. At that point the parser now knows that the following code is C# and as it understands the C# language it knows that at the beginning of the next line the <tr> is not valid C# so it switches back to HTML.

In lines 10 and 11 again the parser detects the “@” symbol and switches to C#.  It understands the concept of C# statements so when it encounters the closing </td> element it knows that – 1) the < is not valid C# and – 2) the preceding C# statement is valid so it switches back to HTML.

Finally, there is the closing “}” in line 11.  At first glance, it appears that we omitted the “@” symbol so the parser knows that the “}” symbol represents C#, but the Razor parser is expecting a “}” at some point, as it detected the opening “{“ on line 8, so as soon as it encounters the “}” it knows to automatically switch back to "C# and close the for statement block.

Razor is a new combination of code (C# or VB.NET) and markup (HTML) that provides cleaner, more readable code.  In the next article in this series we will look in more depth at the Razor syntax.

In a recent series of posts I described how the new WebMatrix suite of Web components from Microsoft fit in with DotNetNuke (DNN).  But what are WebPages and Razor – and how do we (ASP.NET developers) use them to build Web Applications. 

In this series of articles I will dive deeper into these new technologies.  We will start at the very beginning – Creating your first Website using WebMatrix.

Create Your First WebMatrix Website

I will assume that WebMatrix is installed – if not, you can refer to one of my earlier posts to see how to go about downloading and installing it from the Web Application Gallery.

To create your first Website using WebMatrix, launch WebMatrix and select “Site From Template” from the splash screen.

You will then be presented with a page which provides a number of different site templates (the list of templates included may vary – this list is from the WebMatrix Beta 2).  Choose the “Empty Site” template – and call the site “Hello World”.

You will then be presented with the following view in Web Matrix of your new empty site.

Of course as the site has no content you cannot browse to it yet, so we will create a page in our site, by selecting the Files option (highlighted), which shows the files in our site.

As we created an “Empty Site”, not surprisingly there are no files, so select the New option (highlighted), or click the “Add a file to your site” link in WebMatrix’s content pane.  You will then be presented with a “Gallery” of new file types which can be created.

By default the “CSHTML” file type is selected – accept that option and call the new Web Page “HelloWorld.cshtml”.

That’s it – you have created your new “ASP.NET WebPage” based Website.  I added the HTML in between the body tags, so we can actually see something when we browse to the page.  You can view the page in your browser by clicking on the Run button.  WebMatrix allows you to run the page in a single browser – or you can view the page in all of the browsers installed on your system.

You must make sure that the page you wish to view in the browser is the selected page in the site -   WebMatrix will always attempt to load the select page.

Note that the url in the Browser is "http://localhost:29263/HelloWorld.cshtml”.  This is because we are using IISExpress as our webserver, one of the components that is included in the WebMatrix product suite.

While this article demonstrated how to create a site – the site is not very interesting yet as it just contains static content, and you could have done that with a plain old HTML page. 

The CSHTML file type is a new type of file as it allows you to mix markup (HTML) with code C#.  For those of you who prefer Visual Basic as your language there is also a VBHTML file type which allows you to use Visual Basic for the code part.

In the next article in this series, I will introduce the Razor parser and Razor syntax, and we will create our first Razor WebPage.