Razor Syntax: The Bridge Between HTML and C#

Razor is a powerful markup syntax that allows developers to embed server-based code (C#) into web pages. Its greatest strength lies in its fluidity; unlike other languages that require heavy context switching, Razor allows you to weave C# logic directly into your HTML markup seamlessly. The Razor parser is smart enough to detect where the code ends and the HTML begins, leveraging your existing knowledge of both languages.

1. The @ Symbol: Starting the Transition

The magic character in Razor is @. It signals the transition from static HTML to dynamic C# code. This can be done through dedicated code blocks or inline expressions.

Razor Code Blocks

Code blocks allow you to write standard C# code within your .razor file. While the @code block is used for the component's main logic (properties, methods), you can also use inline blocks @{ ... } to execute logic directly within the render tree.

Example:

Instead of just rendering a name, let's create a dynamic message based on the time of day directly inside the HTML structure:

Razor CSHTML

You can even define local functions inside these blocks to keep your markup clean:

2. Implicit Razor Expressions

Implicit expressions are the most common way to print values. You simply start with @ and access a property or variable. The parser identifies the end of the expression automatically (usually by a space or an HTML tag).

Example:

Displaying product details inside a card:

Note: You cannot use generics (like List<string>) or spaces inside an implicit expression.

3. Explicit Razor Expressions

Sometimes, the Razor parser needs help understanding where the code stops, especially when doing calculations or when the code touches static text. Explicit expressions wrap the code in parentheses: @(...).

Example 1: Calculations

Instead of just printing a date, let's print the year 10 years from now:

Example 2: Concatenation

If you want to attach a unit of measurement directly to a number without a space:

Example 3: Generics

To call a generic method, explicit expressions are mandatory to prevent the brackets < > from being confused with HTML tags:

4. Expression Encoding (HTML Safety)

By default, Razor protects you from Cross-Site Scripting (XSS) attacks. If a string contains HTML tags, Razor will encode them, displaying the tags as text rather than rendering them.

Example:

Browser Output: <h1>Critical Error!</h1> (You will literally see the <h1> text).

To force the browser to render the string as actual HTML, you must cast it to MarkupString:

Use this with caution and only with trusted data sources.

5. Directives: Controlling the Component

Directives are special keywords starting with @ that alter how the component is compiled or behaves.

Common Directive Examples

Routing with Parameters:

Implementing an Interface:

If your component needs to clean up resources, you implement IAsyncDisposable:

Generic Components:

Creating a list component that can accept any type of item (TItem):