NashTech Insights

Introduction to Blazor WebAssembly

Tien Nguyen
Tien Nguyen
Table of Contents

In previous article, you already know what is Blazor, Blazor WebAssembly and Blazor Server. Today, we’re going to dive a little bit deeper into Blazor WebAssembly.

Project structure

Let’s start by using Visual Studio to create a new Blazor WebAssembly project. Few options are available:

  • ASP.NET Core Hosted: create a fully solution (client layer, api layer, shared code) with 3 projects: Blazor.Client, Blazor.Server, Blazor.Shared.
  • Progressive Web Application: simply include the service-worker.js file for offline support.
Create Blazor WebAssembly in Visual Studio

Let’s take a look at the project structure, there are a few key files.

  • index.html: the root page of the app implemented as an HTML page. There’s a <div id=”app”>…</div>, where the root App component is rendered. It is recommended to include additional javascript or CSS files here.
  • service-worker.js: offline support, which helps your browser cache all of the dll, javascript, css, and other files.
  • Pages folder: contains the routable components/pages that make up the Blazor app.
  • App.razor: root component of the app. There’s Router component in this file, it intercepts browser navigation and renders the page that matches the requested address. You can configure the Not Found (404) page here as well.
  • Program.cs: the app’s entry point that sets up the WebAssembly host. Define the root component specify the div DOM element with an id of app (<div id=”app”>…</div> in wwwroot/index.html).
Blazor WebAssembly project structure

Run Blazor WebAssembly app on browser

Open Chrome’s dev tools and select the Network tab when your browser requests the app for the first time. Many files are downloaded, the size of a blank project is about 25.5 MB. You can see some CSS, javascript, and picture files, just as with any other type of web application. The only differences are a .wasm file and some .dll files.

  • dotnet.wasm: this is the dotnet runtime running in a browser’s virtual machine. This enables dll to run in the browser.
  • BlazorWA.dll: same name as your project. This file will include all of your code.
  • All other dll files: .NET’s built-in libraries or 3rd parties included in your project.

The next time, the app is light and faster because the browser has previously cached all of the file.

Blazor WebAssembly view in browser dev tools

Blazor Startup

You can see that the initial request made to a Blazor app is a static HTML file (same as angular or react). You might question how the C# code begins to execute? There’s javascript file blazor.webassembly.js included in the index.html. This will setup a window.Blazor object within the JavaScript engine, make sure that all the necessary files are ready (dll, wasm). Then, a javascript function Blazor.start() begins to execute, which triggers your initial C# code (for example, in the Progam.cs file) to run.

Both Blazor WebAssembly and Blazor Server use the same approach to this. You may simply handle the startup process manually, more details can be found here.

Blazor WebAssembly run in a sandbox

.NET code executed via WebAssembly in the browser runs in the browser’s JavaScript sandbox with the protections that the sandbox provides against malicious actions on the client machine.

WebAssembly code is not allowed to escape the confines of its sandbox. It can access the full functionality of the browser (DOM, file, network, …) via JavaScript.

Progressive Web App (PWA)

Blazor WebAssembly app support offline when it uses the https protocol after its first loading. Of course, a network connection is necessary in order to use an API and get data. Depending on the scenario, it is simple to handle your app both online and offline. For example, when the network is available, you can load/sync data and put it in the browser’s database (indexeddb).

Additionally, you can make a desktop icon by clicking the icon to the right of the address bar. The address bar disappears when the app is launched from that icon, making it appear like a native app. It runs by a chrome engine behind the scenes.

Progressive Web App (PWA) - install app
Progressive Web App (PWA) - run app from an icon

You typically run across this problem when running a Blazor WebAssembly app: you change the code, but the changes are not reflected in the app. You attempt a hard reload, empty cache, however, this does not work. It’s because the service worker isn’t automatically updating to the latest code. You need to open Chrome’s dev tools and select the Application tab, there are 2 options:

  • Click “skipWaiting” under “Service Workers” section: update app to new version only, not delete any cookies/localstorage/indexeddb.
  • Click “Clear site data” under “Storage” section: clean up your app and get the latest version.

However, a typical user is unaware of any updates and dev tools. My future article will be addressing how to handle this circumstance. For instance, we may ask that users update to latest version or stick with the current version.

Update service worker


As a result of all of your app’s code being downloaded to the browser. Knowing how simple it is to decompile a dll file, you should avoid including any sensitive data in your code. You may try using JetBrains’ dotPeek, for instance. To manage and access secure resources as indicated in this article, you should have an API layer.

Materials used in this article

  • .NET 7
  • Visual Studio 2022 (64-bit) – Version 17.5.5

Tien Nguyen

Tien Nguyen

Technical Lead at NashTech VN

Leave a Comment

Your email address will not be published. Required fields are marked *

Suggested Article

%d bloggers like this: