Understanding the Blazor Server Advantages

The biggest attraction of Blazor is that it is based on Razor Pages written in C#. This means you can increase efficiency and responsiveness without having to learn a new framework, such as Angular or React, and a new language, such as TypeScript or JavaScript. Blazor is nicely integrated into the rest of ASP.NET Core and is built on features described in earlier chapters, which makes it easy to use (especially when compared to a framework like Angular, which has a dizzyingly steep learning curve).

Understanding the Blazor Server Disadvantages

Blazor requires a modern browser to establish and maintain its persistent HTTP connection. And, because of this connection, applications that use Blazor stop working if the connection is lost, which makes them unsuitable for offline use, where connectivity cannot be relied on or where connections are slow. These issues are addressed by Blazor WebAssembly, described in Chapter 36, but, as I explain, this has its own set of limitations.

Choosing Between Blazor Server and Angular/React/Vue.js

Decisions between Blazor and one of the JavaScript frameworks should be driven by the development team’s experience and the users’ expected connectivity. If you have no JavaScript expertise and have not used one of the JavaScript frameworks, then you should use Blazor, but only if you can rely on good connectivity and modern browsers. This makes Blazor a good choice for line-of-business applications, for example, where the browser demographic and network quality can be determined in advance.

If you have JavaScript experience and you are writing a public-facing application, then you should use one of the JavaScript frameworks because you won’t be able to make assumptions about browsers or network quality. (It doesn’t matter which framework you choose—I have written books about Angular, React, and View, and they are all excellent. My advice for choosing a framework is to create a simple app in each of them and pick the one whose development model appeals to you the most.)

If you are writing a public-facing application and you don’t have JavaScript experience, then you have two choices. The safest option is to stick to the ASP.NET Core features described in earlier chapters and accept the inefficiencies this can bring. This isn’t a terrible choice to make, and you can still produce top-quality applications. A more demanding choice is to learn TypeScript or JavaScript and one Angular, React, or Vue.js—but don’t underestimate the amount of time it takes to master JavaScript or the complexity of these frameworks.

Configuring ASP.NET Core for Blazor Server

The “hub” in the MapBlazorHub method relates to SignalR, which is the part of ASP.NET Core that handles the persistent HTTP request. I don’t describe SignalR in this book because it is rarely used directly, but it can be useful if you need ongoing communication between clients and the server. See https://docs.microsoft.com/en-gb/aspnet/core/signalr for details. For this book—and most ASP.NET Core applications—it is enough to know that SignalR is used to manage the connections that Blazor relies on.

Creating a Razor Component

This @foreach expression generates option elements for each value in the Cities sequence and is identical to the equivalent expression in the controller view and Razor Page created in Chapter 32.

This Blazor attribute creates a data binding between the value of the select element and the SelectedCity property defined in the @code section.

I describe data bindings in more detail in the “Working with Data Bindings” section, but for now, it is enough to know that the value of the SelectedCity will be updated when the user changes the value of the select element.

Using a Razor Component

Razor components are delivered to the browser as part of a Razor Page or a controller view. Listing 33-8 shows how to use a Razor Component in a controller view.

@model PeopleListViewModel

<h4 class="bg-primary text-white text-center p-2">People</h4>

<component type="typeof(Advanced.Blazor.PeopleList)" render-mode="Server" />

Listing 33-8.

Using a Razor Component in the Index.cshtml File in the Views/Home Folder

Razor Components are applied using the component element, for which there is a tag helper. The component element is configured using the type and render-mode attributes. The type attribute is used to specify the Razor Component. Razor Components are compiled into classes just like controller views and Razor Pages. The PeopleList component is defined in the Blazor folder in the Advanced project, so the type will be Advanced.Blazor.PeopleList, like this:

...

<component type="typeof(Advanced.Blazor.PeopleList)" render-mode="Server" />

...

The render-mode attribute is used to select how content is produced by the component, using a value from the RenderMode enum, described in Table 33-3.

Table 33-3.

The RenderMode Values

Name	Description
Static	The Razor Component renders its view section as static HTML with no client-side support.
Server	The HTML document is sent to the browser with a placeholder for the component. The HTML displayed by the component is sent to the browser over the persistent HTTP connection and displayed to the user.
ServerPrerendered	The view section of the component is included in the HTML and displayed to the user immediately. The HTML content is sent again over the persistent HTTP connection.

For most applications, the Server option is a good choice. The ServerPrerendered includes a static rendition of the Razor Component’s view section in the HTML document sent to the browser. This acts as placeholder content so that the user isn’t presented with an empty browser window while the JavaScript code is loaded and executed. Once the persistent HTTP connection has been established, the placeholder content is deleted and replaced with a dynamic version sent by Blazor. The idea of showing static content to the user is a good one, but it can be confusing because the HTML elements are not wired up to the server-side part of the application, and any interaction from the user either doesn’t work or will be discarded once the live content arrives.

To see Blazor in action, restart ASP.NET Core and use a browser to request http://localhost:5000/controllers. No form submission is required when using Blazor because the data binding will respond as soon as the select element’s value is changed, as shown in Figure 33-4.

When you use the select element, the value you choose is sent over the persistent HTTP connection to the ASP.NET Core server, which updates the Razor Component’s SelectedCity property and rerenders the HTML content. A set of updates is sent to the JavaScript code, which updates the table.

Razor Components can also be used in Razor Pages. Add a Razor Page named Blazor.cshtml to the Pages folder and add the content shown in Listing 33-9.

@page "/pages/blazor"

<script type="text/javascript">

    window.addEventListener("DOMContentLoaded", () => {

        document.getElementById("markElems").addEventListener("click", () => {

            document.querySelectorAll("td:first-child")

                .forEach(elem => {

                    elem.innerText = `M:${elem.innerText}`

                    elem.classList.add("border", "border-dark");

                });

        });

    });

</script>

<h4 class="bg-primary text-white text-center p-2">Blazor People</h4>

<button id="markElems" class="btn btn-outline-primary mb-2">Mark Elements</button>

<component type="typeof(Advanced.Blazor.PeopleList)" render-mode="Server" />

Listing 33-9.

The Contents of the Blazor.cshtml File in the Pages Folder

The Razor Page in Listing 33-9 contains additional JavaScript code that helps demonstrate that only changes are sent, instead of an entirely new HTML table. Restart ASP.NET Core and request http://localhost:5000/pages/blazor. Click the Mark Elements button, and the cells in the ID column will be changed to display different content and a border. Now use the select element to pick a different city, and you will see that the elements in the table are modified without being deleted, as shown in Figure 33-5.

UNDERSTANDING BLAZOR CONNECTION MESSAGES

When you stop ASP.NET Core, you will see an error message in the browser window, which indicates the connection to the server has been lost and prevents the user from interacting with the displayed component. Blazor will attempt to reconnect and pick up where it left off when the disconnection is caused by temporary network issues, but it won’t be able to do so when the server has been stopped or restarted because the context data for the connection has been lost; you will have to explicitly request a new URL.

There is a default reload link in the connection message, but that goes to the default URL for the website, which isn’t useful for this book where I direct you to specific URLs to see the effect of examples. See Chapter 34 for details of how to configure the connection messages.

Understanding Blazor Events and Data Bindings

The value assigned to the attribute is the name of the method that will be invoked when the event is triggered. The method can define an optional parameter that is either an instance of the EventArgs class or a class derived from EventArgs that provides additional information about the event.

The Blazor JavaScript code receives the event when it is triggered and forwards it to the server over the persistent HTTP connection. The handler method is invoked, and the state of the component is updated. Any changes to the content produced by the component’s view section will be sent back to the JavaScript code, which will update the content displayed by the browser.

Listing 33-11 changes the type attribute of the component element and removes the custom JavaScript and the button element I used to mark elements in the previous example. Restart ASP.NET Core and request http://localhost:5000/pages/blazor to see the new component. Click the Increment button, and the click event will be received by the Blazor JavaScript code and sent to the server for processing by the IncrementCounter method, as shown in Figure 33-6.

Handling Events from Multiple Elements

To avoid code duplication, elements from multiple elements can be received by a single handler method, as shown in Listing 33-12.

<div class="m-2 p-2 border">

    <button class="btn btn-primary" @onclick="@(e => IncrementCounter(e, 0))">

        Increment Counter #1

    </button>

    <span class="p-2">Counter Value: @Counter[0]</span>

</div>

<div class="m-2 p-2 border">

    <button class="btn btn-primary" @onclick="@(e => IncrementCounter(e, 1))">

        Increment Counter #2

    </button>

    <span class="p-2">Counter Value: @Counter[1]</span>

</div>

@code {

    public int[] Counter { get; set; } = new int[] { 1, 1 };

    public void IncrementCounter(MouseEventArgs e, int index) {

        Counter[index]++;

    }

}

Listing 33-12.

Handling Events in the Events.razor File in the Blazor Folder

Blazor event attributes can be used with lambda functions that receive the EventArgs object and invoke a handler method with additional arguments. In this example, I have added an index parameter to the IncrementCounter method, which is used to determine which counter value should be updated. The value for the argument is defined in the @onclick attribute, like this:

...

<button class="btn btn-primary" @onclick="@(e => IncrementCounter(e, 0))">

...

This technique can also be used when elements are generated programmatically, as shown in Listing 33-13. In this example, I use an @for expression to generate elements and use the loop variable as the argument to the handler method. I have also removed the EventArgs parameter from the handler method, which isn’t being used.

AVOIDING THE HANDLER METHOD NAME PITFALL

The most common mistake when specifying an event handler method is to include parentheses, like this:

...

<button class="btn btn-primary" @onclick="IncrementCounter()">

...

The error message this produces will depend on the event handler method. You may see a warning telling you a formal parameter is missing or that void cannot be converted to an EventCallback. When specifying a handler method, you must specify just the event name, like this:

...

<button class="btn btn-primary" @onclick="IncrementCounter">

...

You can specify the method name as a Razor expression, like this:

...

<button class="btn btn-primary" @onclick="@IncrementCounter">

...

Some developers find this easier to parse, but the result is the same. A different set of rules applies when using a lambda function, which must be defined within a Razor expression, like this:

...

<button class="btn btn-primary" @onclick="@( ... )">

...

Within the Razor expression, the lambda function is defined as it would be in a C# class, which means defining the parameters, followed by the “goes to” arrow, followed by the function body, like this:

...

<button class="btn btn-primary" @onclick="@((e) => HandleEvent(e, local))">

...

If you don’t need to use the EventArgs object, then you can omit the parameter from the lambda function, like this:

...

<button class="btn btn-primary" @onclick="@(() => IncrementCounter(local))">

...

You will quickly become used to these rules as you start to work with Blazor, even if they seem inconsistent at first.

@for (int i = 0; i < ElementCount; i++) {

    int local = i;

    <div class="m-2 p-2 border">

        <button class="btn btn-primary" @onclick="@(() => IncrementCounter(local))">

            Increment Counter #@(i + 1)

        </button>

        <span class="p-2">Counter Value: @GetCounter(i)</span>

    </div>

}

@code {

    public int ElementCount { get; set; } = 4;

    public Dictionary<int, int> Counters { get; } = new Dictionary<int, int>();

    public int GetCounter(int index) =>

        Counters.ContainsKey(index) ? Counters[index] : 0;

    public void IncrementCounter(int index)  =>

        Counters[index] = GetCounter(index) + 1;

}

Listing 33-13.

Generating Elements in the Events.razor File in the Blazor Folder

The important point to understand about event handlers is that the @onclick lambda function isn’t evaluated until the server receives the click event from the browser. This means care must be taken not to use the loop variable i as the argument to the IncrementCounter method because it will always be the final value produced by the loop, which would be 4 in this case. Instead, you must capture the loop variable in a local variable, like this:

...

int local = i;

...

The local variable is then used as the argument to the event handler method in the attribute, like this:

...

<button class="btn btn-primary" @onclick="@(() => IncrementCounter(local))">

...

The local variable fixes the value for the lambda function for each of the generated elements. Restart ASP.NET Core and use a browser to request http://localhost:5000/pages/blazor, which will produce the response shown in Figure 33-7. The click events produced by all the button elements are handled by the same method, but the argument provided by the lambda function ensures that the correct counter is updated.

Processing Events Without a Handler Method

Simple event handling can be done directly in a lambda function, without using a handler method, as shown in Listing 33-14.

@for (int i = 0; i < ElementCount; i++) {

    int local = i;

    <div class="m-2 p-2 border">

        <button class="btn btn-primary" @onclick="@(() => IncrementCounter(local))">

            Increment Counter #@(i + 1)

        </button>

        <button class="btn btn-info" @onclick="@(() => Counters.Remove(local))">

                Reset

        </button>

        <span class="p-2">Counter Value: @GetCounter(i)</span>

    </div>

}

@code {

    public int ElementCount { get; set; } = 4;

    public Dictionary<int, int> Counters { get; } = new Dictionary<int, int>();

    public int GetCounter(int index) =>

        Counters.ContainsKey(index) ? Counters[index] : 0;

    public void IncrementCounter(int index)  =>

        Counters[index] = GetCounter(index) + 1;

}

Listing 33-14.

Handling Events in the Events.razor File in the Blazor Folder

Complex handlers should be defined as methods, but this approach is more concise for simple handlers. Restart ASP.NET Core and request http://localhost:5000/pages/blazor. The Reset buttons remove values from the Counters collection without relying on a method in the @code section of the component, as shown in Figure 33-8.

Preventing Default Events and Event Propagation

Blazor provides two attributes that alter the default behavior of events in the browser, as described in Table 33-5. These attributes, where the name of the event is followed by a colon and then a keyword, are known as parameters.

Table 33-5.

The Event Configuration Parameters

Name	Description
@on{event}:preventDefault	This parameter determines whether the default event for an element is triggered.
@on{event}:stopPropagation	This parameter determines whether an event is propagated to its ancestor elements.

Listing 33-15 demonstrates what these parameters do and why they are useful.

<form action="/pages/blazor" method="get">

    @for (int i = 0; i < ElementCount; i++) {

        int local = i;

        <div class="m-2 p-2 border">

            <button class="btn btn-primary"

                @onclick="@(() => IncrementCounter(local))"

                @onclick:preventDefault="EnableEventParams">

                    Increment Counter #@(i + 1)

            </button>

            <button class="btn btn-info" @onclick="@(() => Counters.Remove(local))">

                    Reset

            </button>

            <span class="p-2">Counter Value: @GetCounter(i)</span>

        </div>

    }

</form>

<div class="m-2" @onclick="@(() => IncrementCounter(1))">

    <button class="btn btn-primary" @onclick="@(() => IncrementCounter(0))"

            @onclick:stopPropagation="EnableEventParams">Propagation Test</button>

</div>

<div class="form-check m-2">

    <input class="form-check-input" type="checkbox"

           @onchange="@(() => EnableEventParams = !EnableEventParams)" />

    <label class="form-check-label">Enable Event Parameters</label>

</div>

@code {

    public int ElementCount { get; set; } = 4;

    public Dictionary<int, int> Counters { get; } = new Dictionary<int, int>();

    public int GetCounter(int index) =>

        Counters.ContainsKey(index) ? Counters[index] : 0;

    public void IncrementCounter(int index)  =>

        Counters[index] = GetCounter(index) + 1;

    public bool EnableEventParams { get; set; } = false;

}

Listing 33-15.

Overriding Event Defaults in the Events.razor File in the Blazor Folder

This example creates two situations in which the default behavior of events in the browser can cause problems. The first is caused by adding a form element. By default, button elements contained in a form will submit that form when they are clicked, even when the @onclick attribute is present. This means that whenever one of the Increment Counter buttons is clicked, the browser will send the form data to the ASP.NET Core server, which will respond with the contents of the Blazor.cshtml Razor Page.

The second problem is demonstrated by an element whose parent also defines an event handler, like this:

...

<div class="m-2" @onclick="@(() => IncrementCounter(1))">

    <button class="btn btn-primary" @onclick="@(() => IncrementCounter(0))"

...

Events go through a well-defined lifecycle in the browser, which includes being passed up the chain of ancestor elements. In the example, this means clicking the button will cause two counters to be updated, once by the @onclick handler for the button element and once by the @onclick handler for the enclosing div element.

To see these problems, restart ASP.NET Core and request http://localhost:5000/pages/blazor. Click an Increment Counter button; you will see that the form is submitted and the page is essentially reloaded. Click the Propagation Test button, and you will see that two counters are updated. Figure 33-9 shows both problems.

The checkbox in Listing 33-15 toggles the property that applies the parameters described in Table 33-5, with the effect that the form isn’t submitted and only the handler on the button element receives the event. To see the effect, check the checkbox and then click an Increment Counter button and the Propagation Test buttons, which produces the result shown in Figure 33-10.

Working with Data Bindings

The @onchange attribute registers the UpdateCity method as a handler for the change event from the input element. The events are described using the ChangeEventArgs class, which provides a Value property. Each time a change event is received, the City property is updated with the contents of the input element.

To see both parts of the relationship defined by the binding in Listing 33-16, restart ASP.NET Core, navigate to http://localhost:5000/pages/blazor, and edit the content of the input element. The change event is triggered only when the input element loses the focus, so once you have finished editing, press the Tab key or click outside of the input element; you will see the value you entered displayed through the Razor expression in the div element, as shown on the left of Figure 33-11. Click one of the buttons, and the City property will be changed to Paris or Chicago, and the selected value will be displayed by both the div element and the input element, as shown on the right of the figure.

The @bind attribute is used to specify the property that will be updated when the change event is triggered and that will update the value attribute when it changes. The effect in Listing 33-18 is the same as Listing 33-16 but expressed more concisely and without the need for a handler method or a lambda function to update the property.

Changing the Binding Event

By default, the change event is used in bindings, which provides reasonable responsiveness for the user without requiring too many updates from the server. The event used in a binding can be changed by using the attributes described in Table 33-6.

Table 33-6.

The Binding Attributes for Specifying an Event

Attribute	Description
@bind-value	This attribute is used to select the property for the data binding.
@bind-value:event	This attribute is used to select the event for the data binding.

These attributes are used instead of @bind, as shown in Listing 33-19, but can be used only with events that are represented with the ChangeEventArgs class. This means that only the onchange and oninput events can be used, at least in the current release.

<div class="form-group">

    <label>City:</label>

    <input class="form-control" @bind-value="City" @bind-value:event="oninput"  />

</div>

<div class="p-2 mb-2">City Value: @City</div>

<button class="btn btn-primary" @onclick="@(() => City = "Paris")">Paris</button>

<button class="btn btn-primary" @onclick="@(() => City = "Chicago")">Chicago</button>

@code {

    public string City { get; set; } = "London";

}

Listing 33-19.

Specifying an Event for a Binding in the Bindings.razor File in the Blazor Folder

This combination of attributes creates a binding for the City property that is updated when the oninput event is triggered, which happens after every keystroke, rather than only when the input element loses the focus. To see the effect, restart ASP.NET Core, navigate to http://localhost:5000/pages/blazor, and start typing into the input element. The City property will be updated after every keystroke, as shown in Figure 33-12.

Creating DateTime Bindings

Blazor has special support for creating bindings for DateTime properties, allowing them to be expressed using a specific culture or a format string. This feature is applied using the parameters described in Table 33-7.

Table 33-7.

The DateTime Parameters

Name	Description
@bind:culture	This attribute is used to select a CultureInfo object that will be used to format the DateTime value.
@bind:format	This attribute is used to specify a data formatting string that will be used to format the DateTime value.

Tip

If you have used the @bind-value and @bind-value:event attributes to select an event, then you must use the @bind-value:culture and @bind-value:format parameters instead.

Listing 33-20 shows the use of these attributes with a DateTime property.

Note

The formatting strings used in these examples are described at https://docs.microsoft.com/en-us/dotnet/api/system.datetime?view=netcore-3.1.

@using System.Globalization

<div class="form-group">

    <label>City:</label>

    <input class="form-control" @bind-value="City" @bind-value:event="oninput"  />

</div>

<div class="p-2 mb-2">City Value: @City</div>

<button class="btn btn-primary" @onclick="@(() => City = "Paris")">Paris</button>

<button class="btn btn-primary" @onclick="@(() => City = "Chicago")">Chicago</button>

<div class="form-group mt-2">

    <label>Time:</label>

    <input class="form-control my-1" @bind="Time" @bind:culture="Culture"

        @bind:format="MMM-dd" />

    <input class="form-control my-1" @bind="Time" @bind:culture="Culture" />

    <input class="form-control" type="date" @bind="Time" />

</div>

<div class="p-2 mb-2">Time Value: @Time</div>

<div class="form-group">

    <label>Culture:</label>

    <select class="form-control" @bind="Culture">

        <option value="@CultureInfo.GetCultureInfo("en-us")">en-US</option>

        <option value="@CultureInfo.GetCultureInfo("en-gb")">en-GB</option>

        <option value="@CultureInfo.GetCultureInfo("fr-fr")">fr-FR</option>

    </select>

</div>

@code {

    public string City { get; set; } = "London";

    public DateTime Time { get; set; } = DateTime.Parse("2050/01/20 09:50");

    public CultureInfo Culture { get; set; } = CultureInfo.GetCultureInfo("en-us");

}

Listing 33-20.

Using a DateTime Property in the Bindings.razor File in the Blazor Folder

There are three input elements that are used to display the same DataTime value, two of which have been configured using the attributes from Table 33-7. The first element has been configured with a culture and a format string, like this:

...

<input class="form-control my-1" @bind="Time" @bind:culture="Culture"

        @bind:format="MMM-dd" />

...

The DateTime property is displayed using the culture picked in the select element and with a format string that displays an abbreviated month name and the numeric date. The second input element specifies just a culture, which means the default formatting string will be used.

...

<input class="form-control my-1" @bind="Time" @bind:culture="Culture" />

...

To see how dates are displayed, restart ASP.NET Core, request http://localhost:5000/pages/blazor, and use the select element to pick different culture settings. The settings available represent English as it is used in the United States, English as it used in the United Kingdom, and French as it is used in France. Figure 33-13 shows the formatting each produces.

The initial locale in this example is en-US. When you switch to en-GB, the order in which the month and date appear changes. When you switch to en-FR, the abbreviated month name changes.

LETTING THE BROWSER FORMAT DATES

Notice that the value displayed by the third input element in Listing 33-20 doesn’t change, regardless of the locale you choose. This input element has neither of the attributes described in Table 33-7 but does have its type attribute set to date, like this:

...

<input class="form-control" type="date" @bind="Time" />

...

You should not specify a culture or a format string when setting the type attribute to date, datetime-local, month, or time, because Blazor will automatically format date values into a culture-neutral format that the browser translates into the user’s locale. Figure 33-11 shows how the date is formatted in the en-US locale but the user will see the date expressed in their local convention.

Using a Code-Behind Class

The @code section of a Razor Component can be defined in a separate class file, known as a code-behind class or code-behind file. Code-behind classes for Razor Components are defined as partial classes with the same name as the component they provide code for.

Restart ASP.NET Core and request http://localhost:5000/pages/blazor, and you will see the response shown in Figure 33-14.

Defining a Razor Component Class

Restart ASP.NET Core and request http://localhost:5000/pages/blazor to see the content produced by the class-based Razor Component. When you click the button, the sort direction of the names in the list is changed, as shown in Figure 33-15.