Comparing Razor to its predecessors

There is a long list of technologies that precede Razor, representing a sort of a flavor-of-the-year march toward where the technology sits today. It starts with classic Active Server Pages (ASP), moves through various incarnations of that technology, through Model-View-Controller (MVC), to Razor today. If you’ve been a developer for long, the subtle but continuing changes in technology could drive you a bit nuts. In fact, when you go online to various tutorial sites such as W3Schools (https://www.w3schools.com/asp/default.ASP), even they have a hard time condensing the technology and making it easier to understand. When you start looking at ASP.NET tutorials (https://www.tutorialspoint.com/asp.net/asp.net_first_example.htm), you begin to see bits and pieces of what eventually became Razor. For example, both use the @page directive (look at the top of Index.cshtml in your project to see this directive), but Razor uses it in a slightly different manner, which is the source of much of the confusion out there about Razor.

The comparison you see most often is between MVC and Razor. Microsoft currently recommends using Razor to reduce complexity (https://docs.microsoft.com/dotnet/architecture/porting-existing-aspnet-apps/comparing-razor-pages-aspnet-mvc). Note that there is an MVC-like approach in Razor, except that Microsoft uses different terms for the various components because using different terms makes technology look new and shiny. So, the MVC action is now a handler, the MVC ViewModel is now a PageModel, and the view is now a Razor Page. When working in MVC, these elements appear in three different locations and you need to modify them individually, which makes MVC error prone because people forget to do things unless they have a string tied around their finger. When working with Razor, the handler and PageModel appear in a single file, while the view appears in a separate file, all under the Pages folder in the project. Here are some other differences between MVC and Razor:

• Simpler pages: A Razor page does have some connectivity to other files, but it's very close to a Web Forms setup in that you have the nonshared content in a single .cshtml file with a code-behind file.
• Focus: Many developers view Razor as the optimal solution for HTML views. They see MVC as an optimal solution for a Representational State Transfer (REST) API or a Service-Oriented Architecture (SOA). The technology you choose depends on the sort of website you want to create. Razor is typically the simple solution for simple problems.
• Less code: In comparing similar coding examples between Razor and MVC, you often find that the Razor code is a little shorter (not much) and a little simpler. However, little differences tend to pile up when you’re working on a website of any size and complexity.

One of the issues that will cause most developers woe is the fact that Visual Studio doesn’t come with a designer for Razor pages. In Book 5, Chapter 2 you see a process for working with XAML to create WPF applications. To create an application, you drag and drop components onto the canvas. Book 5, Chapter 5 shows the same process for UWP applications. Unfortunately, when working with ASP.NET Core, you’re left to write code manually. The only website development that Visual Studio 2022 offers with a designer is the older Web Forms templates, which require a special setup, as described in the “Gaining access to the Web Forms templates” sidebar.

Considering the actual file layout

A Razor website uses a number of files that may seem a little daunting at first, but they make sense after you take them apart rather than attempt to view them as a whole. Here is the list of files for the website in the order in which they’re typically used to create the presentation:

• Program.cs: Contains the Main() method and application startup code. This code includes the creation of a IHostBuilder object, webBuilder, which actually starts the website using the Startup class found in Startup.cs.
• Startup.cs: Defines the website's underlying configuration. This is where the application adds Razor pages to the site and determines how those pages will interact. The “Developing a Basic Web App” section of Chapter 1 of this minibook shows you some of what goes on in the Startup class, such as adding UseEndpoints() calls and substituting calls to app.UseDefaultFiles(); and app.UseStaticFiles(); to support the use of static HTML files on a site. The calls made within this class determine the characteristics of the website interactions.
• _ViewImports.cshtml: Specifies the application imports, Razor page namespace, and helpers used to render the Razor pages (@addTagHelper). You can read more about tag helpers at https://docs.microsoft.com/aspnet/core/mvc/views/tag-helpers/intro.
• _ViewStart.cshtml: Declares which layout page to use for a website. The use of this file eliminates the need to declare the layout page in every content page for the website, reducing potential errors. You can use this feature to change the entire feel of a website with a single coding change.
• _ValidationScriptsPartial.cshtml: Contains pointers to the scripts used to validate the Razor page content. You see older websites that have the scripts actually included in this file. Newer versions of ASP.NET core pages include references to external files to use for validation purposes, which makes maintaining the setup easier.
• _Layout.cshtml: Determines the overall appearance of the Razor pages. Consequently, when you open this file, you see what appears to be an entire HTML page with special inclusions for specific page content, such as @ViewData["Title"], which determines the page title. This is also where you find common page elements, such as the navbar used to move between pages. However, this file doesn't contain any actual content — it’s simply the layout used to contain the specific page layout.
• index.cshtml: Defines the first content page for a website. In all cases, the content appears within a layout specified by the layout document, which is usually _Layout.cshtml.
• index.cshtml.cs: Contains the code-behind for the associated content page. The code-behind performs tasks such as handling user-interface events and performing some types of dynamic page setups. Razor pages are based on the PageModel class (https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.mvc.razorpages.pagemodel).

You see other content pages provided with the project that include Privacy.cshtml and Error.cshtml. These additional content pages work the same as index.cshtml, but they're called upon as needed. There is a link from the home page to Privacy.cshtml. The Error.cshtml file is called upon only when there is an error.

Understanding the syntax rules for C#

A Razor page is a combination of elements that include both HTML and code. How you combine the elements depends on what you plan to do. However, all your code will begin with an at sign (@). For example, if you want to add a date to the default Index.cshtml page, you might use the following code shown in bold:

<div class="text-center">
<h1 class="display-4">Welcome</h1>
<p>It's @DateTime.Now.ToLongDateString()</p>
<p>Learn about <a href="https://docs.microsoft.com/aspnet/core">
building Web apps with ASP.NET Core
</a>.</p>
</div>

Notice that this paragraph uses a combination of an HTML tag, <p>, plain text, and a call to @DateTime.Now.ToLongDateString(). The date will change every time someone loads the page. After that, however, it remains static. A lot of content falls into this category, and you should use this technique whenever possible to make things simple. The output of this call comes in the following form:

It's Friday, October 15, 2021

Of course, you can create changing content and perform all sorts of other tasks. All the entries for performing code-related tasks on a page begin with @. If you actually need to show the @ sign on a page, you use @@ instead. In that case, Razor views the @@ as an @ and doesn't process the text that comes afterward as code.

There are some special rules for working with code on a Razor page, but the code appears as a form of C# and uses C# syntax rules. You could just as easily get the long date in your C# console application using DateTime.Now.ToLongDateString() as you can when working with Razor. So, it’s important not to overthink how to do things.

Working with some Razor basics

Many sources online (such as https://docs.microsoft.com/aspnet/core/razor-pages/) show lots of ways to write code in Razor, but few of them look at simple tasks, which can mean that they can be quite hard to comprehend. To avoid frustration, you need something easier. The following sections look at two basic tasks that you might perform on any web page.

Starting simply by using if

The “Creating Variables” section, earlier in this chapter, discusses how to create variables in Razor. You can use these variables in all sorts of ways, but one of the most common methods is to modify the page appearance to meet specific conditions. The following @if statement uses the isView1 variable created earlier to change the appearance of the page:

@if(isView1)
{
<p>Using View1</p>
}
else
{
<p>Not Using View1</p>
}

Notice that this looks about the same as any other if statement in C#. However, the output is different. In this case, you see that the selection of a particular logical path results in HTML output rather than the execution of code. Also note that the else clause of the if statement lacks the @ sign.

Sleeping at the switch

Razor supports switches, which can save you considerable time typing. Say you create an int named ViewNumber like this:

@{
int ViewNumber;
if (Model.changingString == "This is the changing string.")
ViewNumber = 0;
else if (Model.changingString == "The string has changed.")
ViewNumber = 1;
else
ViewNumber = 2;
}

The if statement appears normal in this case because it appears within an @ block. The code places a value in ViewNumber that corresponds to the current text in changingString. You can use a switch to process ViewNumber, like this:

@switch(ViewNumber)
{
case 0:
<p>Using Original View</p>
break;
case 1:
<p>Using View 1</p>
break;
case 2:
<p>Using View 2</p>
break;
default:
<p>Unrecognized View</p>
break;
}

Except for the @ sign and the use of HTML tags, the switch statement in this example could appear in any C# file. All the same rules apply as when working with C#, so you don't have to do anything weird except remember that @ sign and the fact that you can do something interesting with the HTML.

Creating an array

An array in Razor can take any form that you use in C#. Of course, you need to create it within an @ block or use an existing array of values. Here's an example of creating an array for use within the example:

@{
string[] Colors =
{ "Red", "Orange", "Yellow", "Green", "Blue", "Violet" };
}

As you can see, there is nothing weird here. The same techniques you use to create a C# array normally apply here as well.

Performing tasks a specific number of times using for

The Colors array created in the previous section provides a perfect way to test for loop processing in Razor. The following code uses the Colors array as a source and displays each of the colors in turn:

<h3>Colors</h3>
<ul class="text-left">
@for (var i = 0; i < Colors.Length; i++)
{
<li>Color @i is @Colors[i]</li>
}
</ul>

As with the previous examples, you need to use the @ sign before you create the for loop. In addition, this example shows how you might process a source array so that it appears correctly onscreen. Remember that you can use all the same techniques as you normally use with a for loop to process data in C#.

Processing an unknown number of times using foreach and while

The essential difference between a for loop and both foreach and while is that the former processes data a known number of times, while the latter process data an unknown number of times until they're finished. In many cases, the choice of looping mechanism comes down to style and preference. Some developers like one form and other developers like another form. Here is the same output provided in the previous example using a foreach statement.

<h3>Colors Using Foreach</h3>
@{
int counter = 0;
}
<ul class="text-left">
@foreach (string item in Colors)
{
<li>Color @counter is @item</li>
counter++;
}
</ul>

The example begins by declaring an int variable, counter, to keep track of the color number. It then uses the @foreach loop to process the Colors array. The differences you should notice in this version of the example are the technique used to produce the output and the fact that the example freely mixes HTML and C# code.