Debug ASP.NET Core Blazor

Daniel Roth

Important

Blazor WebAssembly in preview

Blazor Server is supported in ASP.NET Core 3.0. Blazor WebAssembly is in preview.

Early support exists for debugging Blazor WebAssembly 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.

Prerequisites

Debugging requires either of the following browsers:

Procedure

  1. Run a Blazor WebAssembly app in Debug configuration. Pass the --configuration Debug option to the dotnet run command: dotnet run --configuration Debug.
  2. Access the app in the browser.
  3. Place the keyboard focus on the app, not the developer tools panel. The developer tools panel can be closed when debugging is initiated.
  4. Select the following Blazor-specific keyboard shortcut:
    • Shift+Alt+D on Windows/Linux
    • Shift+Cmd+D on macOS
  5. Follow the steps listed on the screen to restart the browser with remote debugging enabled.
  6. Select the following Blazor-specific keyboard shortcut once again to start the debug session:
    • 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.