Debug ASP.NET Core apps

This article describes how to debug Blazor apps, including debugging Blazor WebAssembly apps with browser developer tools or an integrated development environment (IDE).

Prerequisites

This section explains the prerequisites for debugging.

Browser prerequisites

Ensure that firewalls or proxies don't block communication with the debug proxy (NodeJS process). For more information, see the Firewall configuration section.

IDE prerequisites

The latest version of Visual Studio or Visual Studio Code is required.

Visual Studio Code prerequisites

Visual Studio Code requires the C# Dev Kit for Visual Studio Code (Getting Started with C# in VS Code). In the Visual Studio Code Extensions Marketplace, filter the extension list with "c# dev kit" to locate the extension:

Installing the C# Dev Kit automatically installs the following additional extensions:

• .NET Install Tool
• C#
• IntelliCode for C# Dev Kit

If you encounter warnings or errors, you can open an issue (microsoft/vscode-dotnettools GitHub repository) describing the problem.

App configuration prerequisites

The guidance in this subsection applies to client-side debugging.

Open the Properties/launchSettings.json file of the startup project. Confirm the presence of the following inspectUri property in each launch profile of the file's profiles node. If the following property isn't present, add it to each profile:

"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"

The inspectUri property:

• Enables the IDE to detect that the app is a Blazor app.
• Instructs the script debugging infrastructure to connect to the browser through Blazor's debugging proxy.

The placeholder values for the WebSocket protocol (wsProtocol), host (url.hostname), port (url.port), and inspector URI on the launched browser (browserInspectUri) are provided by the framework.

Packages

Standalone Blazor WebAssembly: Microsoft.AspNetCore.Components.WebAssembly.DevServer: Development server for use when building Blazor apps. Calls UseWebAssemblyDebugging internally to add middleware for debugging Blazor WebAssembly apps inside Chromium developer tools.

Debug a Blazor WebAssembly app in an IDE

<DebuggerSupport>true</DebuggerSupport>
<CopyOutputSymbolsToPublishDirectory>true</CopyOutputSymbolsToPublishDirectory>

Attach to an existing Visual Studio Code debugging session

To attach to a running Blazor app, open the .vscode/launch.json file and replace the {URL} placeholder with the URL where the app is running:

{
  "name": "Attach and Debug",
  "type": "blazorwasm",
  "request": "attach",
  "url": "{URL}"
}

Visual Studio Code launch options

The launch configuration options in the following table are supported for the blazorwasm debug type (.vscode/launch.json).

Debug Blazor WebAssembly with Google Chrome or Microsoft Edge

The guidance in this section applies debugging Blazor WebAssembly apps in:

• Google Chrome running on Windows or macOS.
• Microsoft Edge running on Windows.

1. Run the app in a command shell with dotnet watch (or dotnet run).

2. Launch a browser and navigate to the app's URL.

3. Start remote debugging by pressing:

   • Shift+Alt+d on Windows.
   • Shift+⌘+d on macOS.

   The browser must be running with remote debugging enabled, which isn't the default. If remote debugging is disabled, an Unable to find debuggable browser tab error page is rendered with instructions for launching the browser with the debugging port open. Follow the instructions for your browser.

   After following the instructions to enable remote debugging, the app opens in a new browser window. Start remote debugging by pressing the HotKey combination in the new browser window:

   • Shift+Alt+d on Windows.
   • Shift+⌘+d on macOS.

   A new window developer tools browser tab opens showing a ghosted image of the app.

   Note

   If you followed the instructions to open a new browser tab with remote debugging enabled, you can close the original browser window, leaving the second window open with the first tab running the app and the second tab running the debugger.

4. After a moment, the Sources tab shows a list of the app's .NET assemblies and pages.

5. Open the file:// node. In component code (.razor files) and C# code files (.cs), breakpoints that you set are hit when code executes in the app's browser tab (the initial tab opened after starting remote debugging). After a breakpoint is hit, single-step (F10) through the code or resume (F8) code execution normally in the debugging tab.

For Chromium-based browser debugging, 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).

Break on unhandled exceptions

The debugger doesn't break on unhandled exceptions because Blazor catches exceptions that are unhandled by developer code.

To break on unhandled exceptions:

• Open the debugger's exception settings (Debug > Windows > Exception Settings) in Visual Studio.
• Set the following JavaScript Exceptions settings:
  • All Exceptions
  • Uncaught Exceptions

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.

Firewall configuration

If a firewall blocks communication with the debug proxy, create a firewall exception rule that permits communication between the browser and the NodeJS process.

For Windows Firewall configuration guidance, see Create an Inbound Program or Service Rule. For more information, see Windows Defender Firewall with Advanced Security and related articles in the Windows Firewall documentation set.

Troubleshoot

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

• Remove breakpoints:
  • Google Chrome: In the Debugger tab, open the developer tools in your browser. In the console, execute localStorage.clear() to remove any breakpoints.
  • Microsoft Edge: In the Application tab, open Local storage. Right-click the site and select Clear.
• Confirm that you've installed and trusted the ASP.NET Core HTTPS development certificate. For more information, see Enforce HTTPS in ASP.NET Core.
• Visual Studio requires the Enable JavaScript debugging for ASP.NET (Chrome and Edge) option in Tools > Options > Debugging > General. This is the default setting for Visual Studio. If debugging isn't working, confirm that the option is selected.
• If your environment uses an HTTP proxy, make sure that localhost is included in the proxy bypass settings. This can be done by setting the NO_PROXY environment variable in either:
  • The launchSettings.json file for the project.
  • At the user or system environment variables level for it to apply to all apps. When using an environment variable, restart Visual Studio for the change to take effect.
• Ensure that firewalls or proxies don't block communication with the debug proxy (NodeJS process). For more information, see the Firewall configuration section.

Breakpoints in OnInitialized{Async} not hit

The Blazor framework's debugging proxy doesn't launch instantly on app startup, so breakpoints in the OnInitialized{Async} lifecycle methods might not be hit. We recommend adding a delay at the start of the method body to give the debug proxy some time to launch before the breakpoint is hit. You can include the delay based on an if compiler directive to ensure that the delay isn't present for a release build of the app.

OnInitialized:

protected override void OnInitialized()
{
#if DEBUG
    Thread.Sleep(10000);
#endif

    ...
}

OnInitializedAsync:

protected override async Task OnInitializedAsync()
{
#if DEBUG
    await Task.Delay(10000);
#endif

    ...
}

Visual Studio (Windows) timeout

If Visual Studio throws an exception that the debug adapter failed to launch mentioning that the timeout was reached, you can adjust the timeout with a Registry setting:

VsRegEdit.exe set "<VSInstallFolder>" HKCU JSDebugger\Options\Debugging "BlazorTimeoutInMilliseconds" dword {TIMEOUT}

The {TIMEOUT} placeholder in the preceding command is in milliseconds. For example, one minute is assigned as 60000.