The “Obvious” of WASM Debugging
While coding with Blazor WASM, it’s easy to get lulled into a false sense of comfort. After all, it’s all C# and .NET, right? Well, not exactly. It’s easy to gloss over that while our code runs on a version of .NET, it’s not the one we know and love. It’s different. From the official documentation:
Blazor WebAssembly (WASM) apps run client-side in the browser on a WebAssembly-based .NET runtime.
And it’s also reflected in the graphic used on the page, with clear iconography indicating your new Blazor WASM app running in the browser.
Well, where does the debugging happen if your app runs standalone in the client? If you answered “on the client!”, then you’d be correct. All WASM code debugging occurs in the client and is typically proxied to your IDE of choice. That means your tools need a constant connection between your integrated development environment and the client app. Being in the client also means we’re not using traditional .NET debuggers but instead relying on the debuggers found in Chrome dev-tools. Keep that in mind.
Let’s investigate how and where this connection can go wrong and help you debug your Blazor WASM standalone apps.
Chromium Web Browsers Are Required
Currently, Blazor WASM debugging only works with Chromium-based browsers.
- Google Chrome (version 70 or later)
- Microsoft Edge (version 80 or later).
These browsers have the necessary developer tools to connect and communicate with your development environment. Sorry, Firefox and Safari users. You’ll need Chrome installed.
Missing Launch Settings Fields
Most ASP.NET Core projects will come with a
launchSettings.json file. Here we can tell the
dotnet process how to run our web host application. However, for Blazor WASM hosts, we need a few more settings than we initially had with a vanilla ASP.NET Core app.
You’ll need an additional
inspectUri field and an optional
dotnetRunMessages field. The
inspectUri field is the endpoint to which the Chromium-based browser will connect via WebSocket. Without this field, no proxy-based debugging is possible.
Missing NuGet Packages
There are two locations where you need to ensure you have NuGet packages installed correctly in your Blazor WASM solution: The client and the server.
The Blazor WASM client project requires you to install two NuGet packages:
DevServer package includes the
BlazorDebugProxy required to connect the client and IDE. Without this package, you aren’t debugging anything.
The Blazor WASM host, also need the following package of
Microsoft.AspNetCore.Components.WebAssembly.Server, which includes the necessary middleware to host your Blazor application.
Misconfiguration of Blazor Middleware
You’ll need several pieces of middleware to get debugging working, specifically the
UseWebAssemblyDebugging method call. In addition, the order of middleware registrations requires to be accurately registered. I’ve included a correct sample below from the default templates.
var app = builder.Build();
// Configure the HTTP request pipeline.
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
Running the Correct Run Configuration
Global.Json and .NET 6
As of writing this post, some of your IDEs only have support for .NET 6 debugging. If you have any preview versions of .NET installed, you may want to set your
global.json file to lock the SDK version to the .NET 6 band.
Restart the Chrome Instance, No The Other One
So when debugging Blazor WASM apps, your IDE might start a brand-new instance of Chrome with different settings. Check your taskbar and dock for multiple instances of Chrome. Locate the one your IDE started and quit and retry the debugging process.
It’s common to see messages saying: “Blazor Wasm Debugging: lockfile exists, connecting to already running browser”. The message means you have the debugging instance of Chrome still running from previous attempts.
Shut it down and try again.
I hope to give you some suggestions for getting your Blazor WASM client debugging with your favorite IDEs.