Debug ASP.NET Core Blazor

Daniel Roth

Early support exists for debugging Blazor client-side apps running on WebAssembly in Chrome.

Debugger capabilities are limited. Available scenarios include:

  • Set and remove breakpoints.
  • Single-step (F10) through the code or resume (F8) code execution.
  • In the Locals display, observe the values of any local variables of type int, string, and bool.
  • See the call stack, including call chains that go from JavaScript into .NET and from .NET to JavaScript.

You can't:

  • Observe the values of any locals that aren't an int, string, or bool.
  • Observe the values of any class properties or fields.
  • Hover over variables to see their values.
  • Evaluate expressions in the console.
  • Step across async calls.
  • Perform most other ordinary debugging scenarios.

Development of further debugging scenarios is an on-going focus of the engineering team.

Procedure

To debug a Blazor client-side app in Chrome:

  • Build a Blazor app in Debug configuration (the default for unpublished apps).
  • Run the Blazor app in Chrome (version 70 or later).
  • With the keyboard focus on the app (not in the developer tools panel, which you should probably close for a less confusing debugging experience), select the following Blazor-specific keyboard shortcut:
    • Shift+Alt+D on Windows/Linux
    • Shift+Cmd+D on macOS

Enable remote debugging

If remote debugging is disabled, an Unable to find debuggable browser tab error page is generated by Chrome. The error page contains instructions for running Chrome with the debugging port open so that the Blazor debugging proxy can connect to the app. Close all Chrome instances and restart Chrome as instructed.

Debug the app

Once Chrome is running with remote debugging enabled, the debugging keyboard shortcut opens a new debugger tab. After a moment, the Sources tab shows a list of the .NET assemblies in the app. Expand each assembly and find the .cs/.razor source files available for debugging. Set breakpoints, switch back to the app's tab, and the breakpoints are hit when the code executes. After a breakpoint is hit, single-step (F10) through the code or resume (F8) code execution normally.

Blazor provides a debugging proxy that implements the Chrome DevTools Protocol and augments the protocol with .NET-specific information. When debugging keyboard shortcut is pressed, Blazor points the Chrome DevTools at the proxy. The proxy connects to the browser window you're seeking to debug (hence the need to enable remote debugging).

Browser source maps

Browser source maps allow the browser to map compiled files back to their original source files and are commonly used for client-side debugging. However, Blazor doesn't currently map C# directly to JavaScript/WASM. Instead, Blazor does IL interpretation within the browser, so source maps aren't relevant.

Troubleshooting tip

If you're running into errors, the following tip may help:

In the Debugger tab, open the developer tools in your browser. In the console, execute localStorage.clear() to remove any breakpoints.