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 for ASP.NET Core 3.1.

Early support exists for debugging Blazor WebAssembly using the browser dev tools in Chromium-based browsers (Chrome/Edge). Work is in progress to:

  • Fully enable debugging in Visual Studio.
  • Enable debugging in Visual Studio Code.

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

Warning

Debugging support in Visual Studio is at an early stage of development. F5 debugging isn't currently supported.

  1. Run a Blazor WebAssembly app in Debug configuration without debugging (Ctrl+F5 instead of F5).

  2. Open the Debug properties of the app (last entry in the Debug menu) and copy the HTTP App URL. Browse to the HTTP address (not the HTTPS address) of the app using a Chromium-based browser (Edge Beta or Chrome).

  3. Place the keyboard focus on the app in the browser window, not the developer tools panel. It's best to keep the developer tools panel closed for this procedure. After debugging has started, you can re-open the developer tools panel.

  4. Select the following Blazor-specific keyboard shortcut:

    • Shift+Alt+D on Windows
    • Shift+Cmd+D on macOS

    If you receive the Unable to find debuggable browser tab, see Enable remote debugging.

    After enabling remote debugging:

    1. A new browser window opens. Close the prior window.

    2. Place the keyboard focus on the app in the browser window.

    3. Select the Blazor-specific keyboard shortcut in the new browser window: Shift+Alt+D on Windows or Shift+Cmd+D on macOS.

    4. The DevTools tab opens in the browser. Reselect the app's tab in the browser window.

    To attach the app to Visual Studio, see the Attach to process in Visual Studio section.

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).

Attach to process in Visual Studio

Attaching to the app's process in Visual Studio is a temporary debugging scenario for Blazor WebAssembly while F5 debugging is in development.

To attach the running app's process to Visual Studio:

  1. In Visual Studio, select Debug > Attach to Process.
  2. For the Connection type, select Chrome devtools protocol websocket (no authentication).
  3. For the Connection target, paste in the HTTP address (not the HTTPS address) of the app.
  4. Select Refresh to refresh the entries under Available processes.
  5. Select the browser process to debug and select Attach.
  6. In the Select Code Type dialog, select the code type for the specific browser you're attaching to (Edge or Chrome) and then select OK.

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.

Troubleshoot

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.