1. Introduction to WebAssembly and Blazor

The First Browser War

Newer versions were released rapidly, and browsers started to add new features such as <blink> and <marquee> elements. This was the beginning of the first browser war, giving people (especially designers) headaches because some developers were building pages with blinking marquee controls . But developers were also getting sore heads because of incompatibilities between browsers. The first browser war was about having more HTML capabilities than the competition.

But all of this is now behind us with the introduction of HTML5 and modern browsers like Google Chrome, Microsoft Edge, Firefox, Safari, and Opera. HTML5 not only defines a series of standard HTML elements but also rules on how these should render, making it a lot easier to build a website that looks the same in all modern browsers. Then, in 1995, Brendan Eich wrote a little programming language known as ECMAScript (initially called LiveScript) in ten days (What!?). It was quickly dubbed JavaScript because its syntax was very similar to Java. I will be using the name JavaScript here because that is what most people call it.

JavaScript and Java are not related. Java and JavaScript have as much in common as ham and hamster (I don’t know who formulated this first, but I love this phrasing).

Little did Mr. Eich know how this language would impact the modern Web and even desktop application development. In 1995, Jesse James Garrett wrote a white paper called Ajax (Asynchronous JavaScript and XML), describing a set of technologies where JavaScript is used to load data from the server and that data is used to update the browser’s HTML. This avoids full page reloads and allows for client-side web applications, which are applications written in JavaScript that run completely in the browser. One of the first companies to apply Ajax was Microsoft when they built Outlook Web Access (OWA). OWA is a web application almost identical to the Outlook desktop application proving the power of Ajax. Soon other Ajax applications started to appear, with Google Maps stuck in my memory as one of the other keystone applications. Google Maps would download maps asynchronously and with some simple mouse interactions allowed you to zoom and pan the map. Before Google Maps, the server would do the map rendering and a browser displayed the map like any other image by downloading a bitmap from a server.

Building an Ajax website was a major undertaking that only big companies like Microsoft and Google could afford. This soon changed with the introduction of JavaScript libraries like jQuery and knockout.js (knockout was also written by Steve Sanderson, the author of Blazor!). Today, we build rich web apps with Angular, React, and Vue.js. All of them are using JavaScript or higher-level languages like TypeScript which gets transpiled into JavaScript.

Transpiling will take one language and convert it into another language. This is very popular with TypeScript which gives you a modern high-level typed language. You need JavaScript to run it in a browser, so TypeScript gets “transpiled” into JavaScript.

The Second Browser War

This brings us back to JavaScript and the second browser war. JavaScript performance is paramount in modern browsers. Chrome, Edge, Firefox, Safari, and Opera are all competing with one another, trying to convince users that their browser is the fastest with cool-sounding names for their JavaScript engine like V8 and Chakra. These engines use the latest optimization tricks like Just-In-Time (JIT) compilation where JavaScript gets converted into native code as illustrated in Figure 1-1.

This process takes a lot of effort because JavaScript needs to be downloaded into the browser, where it gets parsed, then compiled into bytecode, and then Just-In-Time converted into native code. So how can we make this process even faster?

The second browser war is all about JavaScript performance.

Which Browsers Support WebAssembly?

WebAssembly is supported by all major browsers: Chrome, Edge, Safari, Opera, and Firefox, including their mobile versions. You can verify support yourself by visiting https://caniuse.com/?search=WASM as shown in Figure 1-5.

As WebAssembly will become more and more important, we will see other browsers follow suit, but don’t expect Internet Explorer to support WASM.

WebAssembly and Mono

Mono is an open source implementation of the .NET CLI specification, meaning that Mono is a platform for running .NET assemblies. Mono is used in Xamarin (now called Multi-platform App UI, or MAUI for short) for building mobile applications that run on the Windows, Android, and iOS mobile operating systems. You can also use it to build applications for macOS, Linux, Tizen, and others. Mono also allows you to run .NET on Linux (its original purpose) and is written in C++. This last part is important because we saw that you can compile C++ to WebAssembly. So, what happened is that the Mono team decided to try to compile Mono to WebAssembly, which they did successfully. There are two approaches. One is where you take your .NET code and you compile it together with the Mono runtime into one big WASM application. However, this approach takes a lot of time because you need to take several steps to compile everything into WASM, not so practical for day-to-day development. The other approach takes the Mono runtime and compiles it into WASM, and this runs in the browser where it will execute .NET Intermediate Language just like normal .NET does. The big advantage is that you can simply run .NET assemblies without having to compile them first into WASM.

This is the approach currently taken by Blazor. In the beginning, Blazor used the Mono runtime, but they have now built their own .NET Core runtime for WebAssembly. But Blazor is not the only one taking this approach. For example, there is the Ooui project which allows you to run Xamarin.Forms applications in the browser. The disadvantage of this is that it needs to download a lot of .NET assemblies . This can be solved by using tree shaking algorithms which remove all unused code from assemblies. We will look at this in Chapter 15.

How Does It Work?

Let’s start with a simple razor file in Listing 1-1 which you can find when you create a new Blazor project (which we will do further on in this chapter, no need to type anything yet).

This file gets compiled into a .NET class (you’ll find out how later in this book) which is then executed by the Blazor engine. The result of this execution is a tree-like structure called the render tree . The render tree is then sent to JavaScript which updates the DOM to reflect the render tree (creating, updating, and removing HTML elements and attributes). Listing 1-1 will result in h1, p (with the contents set to the value of currentCount), and button HTML elements. When you interact with the page, for example, when you click the button, this will trigger the button’s click event which will invoke the IncrementCount method from Listing 1-1. The render tree is then regenerated, and any changes are sent again to JavaScript which will update the DOM. This process is illustrated in Figure 1-6.

This model is very flexible. It allows you to build Progressive Web Apps, and your app can be embedded in Electron desktop applications of which Visual Studio Code is a prime example.

Blazor Server

At the August 7, 2018, ASP.NET community standup (www.youtube.com/watch?v=7Eh_l7jEcCo), Daniel Roth introduced a new execution model for Blazor now called Blazor Server. In this model, your Blazor site is running on the server resulting in a way smaller download for the browser.

We just saw that Blazor WebAssembly builds a render tree using the .NET runtime running in the browser which then gets sent to JavaScript to update the DOM. With Blazor Server, the render tree is built on the server using regular .NET and then gets serialized to the browser using SignalR (we will look at SignalR in a later chapter). JavaScript in the browser then deserializes the render tree to update the DOM. Pretty similar to the Blazor WebAssembly model. When you interact with the site, events get serialized back to the server which then executes the .NET code, updating the render tree, and the changes get serialized back to the browser. I’ve illustrated this process in Figure 1-7. The big difference is that there is no need to send the .NET runtime and your Blazor assemblies to the browser. And the programming model stays the same! You can switch Blazor Server-side and Blazor WebAssembly with just a couple of small changes to your code.

Pros and Cons of the Blazor Server

Installing Blazor Prerequisites

Working with Blazor requires you to install some prerequisites, so in this section, you will install what is needed to get going.

Blazor runs on top of .NET , optionally providing the web server for your project which will serve the client files that run in the browser and run any server-side APIs that your Blazor project needs. .NET (previously known as .NET Core) is Microsoft’s cross-platform solution for working with .NET on Windows, Linux, and OSX.

You can find the installation files at www.microsoft.com/net/download. Look for the latest version of the .NET SDK (you’ll need at least version 6.0). Follow the installation instructions and install it on your machine, using Windows, OSX, or Linux.

Output should indicate that you installed the correct version. The version number should be at least 6.0.

Should the command’s output show an older version, you will need to download and install a more recent version of .NET SDK. These can run side by side so you will not break other .NET projects doing this.

Using Visual Studio

For people using Windows, Visual Studio (from now on, I will refer to Visual Studio as VS) is one of the integrated development environments (IDE) we will use throughout this book. If you are using OSX or Linux, you can use Visual Studio Code, and OSX users might prefer Visual Studio for Mac. With any one, you can edit your code, compile it, and run it all from the same application. And the code samples are also the same.

If you want to use Visual Studio, download the latest version of Visual Studio from www.visualstudio.com/downloads/. The Community Edition is free and should allow you to do everything done in this book.

Run the installer and make sure that you install the ASP.NET and web development role as shown in Figure 1-8.

After installation, run Visual Studio from the Start menu. Then open the Help menu and select About Microsoft Visual Studio. The About Microsoft Visual Studio dialog window should specify at least version 17.0.0 as illustrated in Figure 1-9.

Using Visual Studio Code

Visual Studio Code (VSC) is a free, modern, cross-platform development environment with an integrated editor, git source control, and debugger. The environment has a huge range of extensions available allowing you to use all kinds of languages and tools directly from VSC. So, if you don’t have access to (because you’re running a non-Windows operating system or you don’t want to use) Visual Studio, use VSC.

Install VSC from www.visualstudio.com/. Install using the defaults.

After installation, you should install a couple of extensions for Code, especially the C# extension. Start Code, and at the left side, select the extensions tab as shown in Figure 1-10.

You can search for extensions, so start with C# which is the first extension from Figure 1-11. This extension will give you IntelliSense and debugging for the C# programming language and .NET assemblies. You will probably get a newer version listed, so take the latest.

Click Install.

Understanding the Blazor Templates for VS/Code

Throughout this book, we will create several different Blazor projects. With .NET Core, we can use the command-line interface (CLI) to create all kinds of projects, including Blazor WebAssembly and Blazor Server.

With Blazor projects, you have a couple of choices. You can create a standalone Blazor project (using the blazorwasm template) that does not need server-side code. This kind of project known as Blazor WebAssembly has the advantage that you can simply deploy it to any web server which will function as a file server, allowing browsers to download your site just like any other site. We will look at deployment in a later chapter.

Or you can create a hosted project (adding the --hosted option) with client, server, and shared code. This kind of Blazor WebAssembly project will require you to host it where there is .NET Core support because you will execute code on the server as well, for example, to retrieve data from a database.

The third option is to run all Blazor code on the server (using the blazorserver template). In this case, the browser will use a SignalR connection to receive UI updates from the server and to send user interaction back to the server for processing.

In this book, we will use the second option (Blazor WebAssembly hosted on ASP.NET MVC Core) most of the time, but the concepts you will learn in this book are the same for all three options. You can even develop for Blazor WebAssembly and Blazor Server at the same time! Why? Because debugging support for Blazor WebAssembly is limited, so you develop with Blazor Server using all debugger features you know and love. But you can test everything with Blazor WebAssembly ensuring you can run everything in the browser later. This is the way I like to work. However, to pull this off, you need some experience with Blazor first, so keep reading.

Generating the Project with Dotnet CLI

This should build without any errors.

Open your browser on this address (here https://localhost:5001), and you are ready to play!

Generating Your Project with Visual Studio

Start Visual Studio and select Create a new project.

Type Blazor in the search box, and select the Blazor WebAssembly App project template as illustrated in Figure 1-12.

Click Next.

Name your project MyFirstBlazor, choose the location where the project should be generated, and click Next.

On the next screen, you can select the framework to use. Choose the latest version (at the time of writing, that is .NET 6.0), leave Authentication type set to None, check the ASP.NET Core hosted checkbox, and click Create. An example is shown in Figure 1-13.

Wait for Visual Studio to complete. Then build and run your solution by pressing F5. After a little while, the browser will open and display the Blazor application.

Running Blazor with Visual Studio Code

Or you can open VSC and then select File ➤ Open Folder….

When Code has loaded everything (be patient), it will pop a question as in Figure 1-14. Answer Yes. This will add a folder called .vscode with configuration files adding support for building and running the project from Code. If you already have a .vscode folder (because you copied an existing project, for example), you will not get this question.

Thanks to this integration with Visual Studio Code, you can simply press F5 to build and run your project.

The Server Project

Web applications are a bunch of files that get downloaded by the browser from a server. It is the server’s job to provide the files to the browser upon request. There is a whole range of existing servers to choose from, for example, IIS on Windows or Apache on Linux. ASP.NET Core has a built-in server known as Kestrel that you generated with the --hosted option, which you can then run on Windows, Linux, or OSX. This is the preferred option to use during development.

Would you like to see a detailed error page when the server has an uncaught exception? The UseDeveloperExceptionPage method which installs some error handling middleware takes care of that. Of course, you don’t need that in production (you should handle all exceptions correctly <grin>), so this middleware is only used when running in a development environment. How does the server know if you are running in development or release? The if statement you see here checks an environment variable called ASPNETCORE_ENVIRONMENT , and if the environment variable is set to Development, it knows you are running in development mode.

The Blazor bootstrap process requires a bunch of special files, especially dotnet.wasm (dotnet.wasm is the .NET runtime compiled as WebAssembly). This is served by the Blazor middleware, which is installed by the UseBlazorFrameworkFiles instruction. Later in this chapter, you will see why.

Look at the end of Listing 1-2. Here is another important middleware installed. The MapFallbackToFile("index.html") will return the index.html file which takes care of loading everything your Blazor application needs.

Using a Shared Project

The FetchData component downloads weather information from the server. These kinds of requests will be handled by the MVC middleware (MapControllers). We will discuss this in more detail in Chapter 6.

Understanding the Client Blazor Project

After this, there is another div; this is used to display errors in case your Blazor application has an uncaught exception.

This script will install Blazor by downloading dotnet.wasm. A little further we will look at this in more detail.

Listing 1-6. The index.html File

Layout Components

This component contains a div HTML element with two nested divs. The first nested div with class sidebar contains a single Blazor component: NavMenu. This is where your navigation menu gets defined. The sidebar will display a menu, allowing you to navigate between Home, Counter, and Fetch data. We will look in more detail at navigation and routing in Chapter 9.

The next nested div with class main has two parts. The first is the About link you see on every page. The second part contains the @Body; this is where the selected page will be shown. For example, when you click the Counter link in the navigation menu, the @Body will be replaced with the Counter component.

This is all for now, but the rest of the book will explain each part as we go along.

Debugging with Visual Studio

Now run your application in VS with the debugger by pressing F5. Be patient while your Blazor site starts to run (in Edge or Chrome!). Now you can put a breakpoint in your code, for example, on the IncrementCount method of the Counter component as in Figure 1-18, line 17. Simply click in the gray area left to your code (also known as the gutter) and a red dot will appear, indicating that the debugger will stop at this code.

Go back to your Blazor application and click the Counter’s Click Me button. The debugger should stop on the IncrementCount method. You can now examine the content of simple variables in the Locals window, like in Figure 1-19.

Debugging with Visual Studio Code

Start VSC. Ensure you have the Microsoft.AspNetCore.Razor.VSCode.BlazorWasmDebuggingExtension debugging extensions installed as in Figure 1-20.

You will also have to ensure that the JavaScript Preview Debugger has been enabled (by the time you are reading this, it might no longer be a preview feature). You can find this setting in VSC Settings like in Figure 1-21.

Open the folder containing the solution file. If it is the first time you open this folder with VSC, be patient, after a while, Figure 1-14 will pop up. Answer Yes. Also ensure Listing 1-11 is set up correctly like Visual Studio (this is actually independent of your IDE).

Now run your application in VSC with the debugger by pressing F5. Be patient while your Blazor site starts to run (in Chrome!). Now you can put a breakpoint in your code, for example, on the IncrementCount method of the Counter component as in Figure 1-22, line 16. Simply click in the area left to your code (also known as the gutter) and a red dot will appear, indicating that the debugger will stop at this code.

Go back to your Blazor application and click the Counter’s Click Me button. The debugger should stop on the IncrementCount method. You can now examine the content of simple variables in the Locals window, like in Figure 1-23.

Hot Reload with .NET CLI

As soon as you make the change, the browser will update itself, keeping the current count!

Save. Clicking the Increment button will not add 3 to the counter.

If you want to restart again, go back to the command line and press Ctrl-Shift-R.

Hot Reload with Visual Studio

At the time of writing this chapter, hot reload does not work yet for Blazor WebAssembly application with Visual Studio. But, by the time you are reading this, it should work.

An Apology

Who invented the null pointer? Tony Hoare did, and he apologized in 2009 and denoted this as his billion-dollar mistake (www.infoq.com/presentations/Null-References-The-Billion-Dollar-Mistake-Tony-Hoare/):

I call it my billion-dollar mistake. It was the invention of the null reference in 1965. At that time, I was designing the first comprehensive type system for references in an object oriented language (ALGOL W). My goal was to ensure that all use of references should be absolutely safe, with checking performed automatically by the compiler. But I couldn't resist the temptation to put in a null reference, simply because it was so easy to implement. This has led to innumerable errors, vulnerabilities, and system crashes, which have probably caused a billion dollars of pain and damage in the last forty years.

Many object-oriented programming languages still use the null pointer , and C# is no exception. Some languages even treated null differently. For example, in Objective-C, when a pointer is null, the compiler would not invoke a method on it. And it would do this silently! Of course, you would not get a NullReferenceException, but it did skip an important piece of functionality.

Using Null in C#

Of course, this would break every existing C# application out there, so we need to enable this in our project properties. You can do this in Visual Studio using your project properties as shown in Figure 1-30.

This causes the compiler to set a nullable flag for every field, property, and method that is of (or returns) a reference type. You can inspect this flag in VS by hovering over it as shown in Figure 1-31.

The compiler then uses that flag to issue warnings if you would attempt to use a nullable reference type, for example, by getting the length of the string. Figure 1-32 will display a warning because the canBeNull reference can be null.

However, if we nest this in a condition as in Figure 1-33 where we check against null, the compiler will no longer issue a warning.

So the whole idea of nullable reference types is to make the compiler do the analysis and to issue a warning when we can have a possible null being used which would result in a NullReferenceException.

Using References

However, this does not mimic real life. There is another technique we can use.

The Null-Forgiving Operator

Sometimes you just know that a nullable reference is not null, and you want to tell the compiler about this. For this, we can use the null-forgiving operator by appending the nullable reference with an exclamation mark as in Figure 1-34. This sets the nullable flag to false, and the compiler is happy.

This is exactly the technique we will use to create Blazor components that have reference properties that we cannot initialize using a constructor.

Nullable Reference Types and .NET Libraries

Microsoft has gone through a lot of effort to make all their libraries support nullable reference types. I want you to realize that this is all compiler meta-data, so you can use the new libraries supporting nullable reference types with older projects; the compiler will simply ignore this meta-data. You can also use libraries that do not support this meta-data, but you will need to use the null-forgiving operator with a lot of methods. But do yourself a favor – get to use nullable reference types and your code will be shipped with a lot less bugs! You can learn more at https://docs.microsoft.com/en-us/dotnet/csharp/nullable-references.