Debug ASP.NET Core Blazor WebAssembly
This article describes how to debug Blazor WebAssembly with browser developer tools and an integrated development environment (IDE).
Blazor WebAssembly apps can be debugged using the browser developer tools in Chromium-based browsers (Edge/Chrome). You can also debug your app using the following IDEs:
- Visual Studio
- Visual Studio for Mac
- Visual Studio Code
Available scenarios include:
- Set and remove breakpoints.
- Run the app with debugging support in IDEs.
- Single-step through the code.
- Resume code execution with a keyboard shortcut in IDEs.
- In the Locals window, observe the values of local variables.
- See the call stack, including call chains between JavaScript and .NET.
For now, you can't:
- Break on unhandled exceptions.
- Hit breakpoints during app startup before the debug proxy is running. This includes breakpoints in
Program.cs
and breakpoints in theOnInitialized{Async}
lifecycle methods of components that are loaded by the first page requested from the app. - Debug in non-local scenarios (for example, Windows Subsystem for Linux (WSL) or Visual Studio Codespaces).
- Automatically rebuild the backend Server app of a hosted Blazor WebAssembly solution during debugging, for example by running the app with
dotnet watch run
.
Prerequisites
Debugging requires either of the following browsers:
- Google Chrome (version 70 or later) (default)
- Microsoft Edge (version 80 or later)
Ensure that firewalls or proxies don't block communication with the debug proxy (NodeJS
process). For more information, see the Firewall configuration section.
Visual Studio Code users require the following extensions:
- C# for Visual Studio Code Extension
- Blazor WASM Debugging Extension (when using the C# for Visual Studio Code Extension version 1.23.9 or later)
After opening a project in VS Code, you may receive a notification that additional setup is required to enable debugging. If requested, install the required extensions from the Visual Studio Marketplace. To inspect the installed extensions, open View > Extensions from the menu bar or select the Extensions icon in the Activity sidebar.
Visual Studio for Mac requires version 8.8 (build 1532) or later:
Install the latest release of Visual Studio for Mac by selecting the Download Visual Studio for Mac button at Microsoft: Visual Studio for Mac.
Note
Apple Safari on macOS isn't currently supported.
Packages
Standalone Blazor WebAssembly:
Microsoft.AspNetCore.Components.WebAssembly.DevServer
: Development server for use when building Blazor apps. Calls WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging internally to add middleware for debugging Blazor WebAssembly apps inside Chromium developer tools.
Hosted Blazor WebAssembly:
- Client project:
Microsoft.AspNetCore.Components.WebAssembly.DevServer
: Development server for use when building Blazor apps. Calls WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging internally to add middleware for debugging Blazor WebAssembly apps inside Chromium developer tools. - Server project:
Microsoft.AspNetCore.Components.WebAssembly.Server
: References an internal package (Microsoft.NETCore.BrowserDebugHost.Transport
) for assemblies that share the browser debug host.
Note
For guidance on adding packages to .NET apps, see the articles under Install and manage packages at Package consumption workflow (NuGet documentation). Confirm correct package versions at NuGet.org.
Debug a standalone Blazor WebAssembly app
To enable debugging for an existing Blazor WebAssembly app, update the launchSettings.json
file in the startup project to include the following inspectUri
property in each launch profile:
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"
Once updated, the launchSettings.json
file should look similar to the following example:
{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iisExpress": {
"applicationUrl": "http://localhost:50454",
"sslPort": 44399
}
},
"profiles": {
"IIS Express": {
"commandName": "IISExpress",
"launchBrowser": true,
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"BlazorApp1.Server": {
"commandName": "Project",
"launchBrowser": true,
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
"applicationUrl": "https://localhost:5001;http://localhost:5000",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
The inspectUri
property:
- Enables the IDE to detect that the app is a Blazor WebAssembly 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.
To debug a Blazor WebAssembly app in Visual Studio:
Create a new hosted Blazor WebAssembly solution.
With the Server project selected in Solution Explorer, press F5 to run the app in the debugger.
Note
When debugging with a Chromium-based browser, such as Google Chrome or Microsoft Edge, a new browser window might open with a separate profile for the debugging session instead of opening a tab in an existing browser window with the user's profile. If debugging with the user's profile is a requirement, adopt one of the following approaches:
- Close all open browser instances before pressing F5 to start debugging.
- Configure Visual Studio to launch the browser with the user's profile. For more information on this approach, see Blazor WASM Debugging in VS launches Edge with a separate user data directory (dotnet/aspnetcore #20915).
Note
Start Without Debugging [Ctrl+F5 (Windows) or ⌘+F5 (macOS)] isn't supported. When the app is run in Debug configuration, debugging overhead always results in a small performance reduction.
In the Client app, set a breakpoint on the
currentCount++;
line inPages/Counter.razor
.In the browser, navigate to
Counter
page and select the Click me button to hit the breakpoint.In Visual Studio, inspect the value of the
currentCount
field in the Locals window.Press F5 to continue execution.
While debugging a Blazor WebAssembly app, you can also debug server code:
- Set a breakpoint in the
Pages/FetchData.razor
page in OnInitializedAsync. - Set a breakpoint in the
WeatherForecastController
in theGet
action method. - Browse to the
Fetch Data
page to hit the first breakpoint in theFetchData
component just before it issues an HTTP request to the server. - Press F5 to continue execution and then hit the breakpoint on the server in the
WeatherForecastController
. - Press F5 again to let execution continue and see the weather forecast table rendered in the browser.
Note
Breakpoints are not hit during app startup before the debug proxy is running. This includes breakpoints in Program.cs
and breakpoints in the OnInitialized{Async}
lifecycle methods of components that are loaded by the first page requested from the app.
If the app is hosted at a different app base path than /
, update the following properties in Properties/launchSettings.json
to reflect the app's base path:
applicationUrl
:"iisSettings": { ... "iisExpress": { "applicationUrl": "http://localhost:{INSECURE PORT}/{APP BASE PATH}/", "sslPort": {SECURE PORT} } },
inspectUri
of each profile:"profiles": { ... "{PROFILE 1, 2, ... N}": { ... "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/{APP BASE PATH}/_framework/debug/ws-proxy?browser={browserInspectUri}", ... } }
The placeholders in the preceding settings:
{INSECURE PORT}
: The insecure port. A random value is provided by default, but a custom port is permitted.{APP BASE PATH}
: The app's base path.{SECURE PORT}
: The secure port. A random value is provided by default, but a custom port is permitted.{PROFILE 1, 2, ... N}
: Launch settings profiles. Usually, an app specifies more than one profile by default (for example, a profile for IIS Express and a project profile, which is used by Kestrel server).
In the following examples, the app is hosted at /OAT
with an app base path configured in wwwroot/index.html
as <base href="/OAT/">
:
"applicationUrl": "http://localhost:{INSECURE PORT}/OAT/",
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/OAT/_framework/debug/ws-proxy?browser={browserInspectUri}",
For information on using a custom app base path for Blazor WebAssembly apps, see Host and deploy ASP.NET Core Blazor.
Debug in the browser
The guidance in this section applies to Google Chrome and Microsoft Edge running on Windows.
Run a Debug build of the app in the Development environment.
Launch a browser and navigate to the app's URL.
In the browser, attempt to commence remote debugging by pressing Shift+Alt+d.
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, which opens a new browser window. Close the previous browser window.
Once the browser is running with remote debugging enabled, the debugging keyboard shortcut in the previous step opens a new debugger tab.
After a moment, the Sources tab shows a list of the app's .NET assemblies within the
file://
node.In component code (
.razor
files) and C# code files (.cs
), breakpoints that you set are hit when 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.
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.
Warning
Modification of a firewall configuration must be made with care to avoid creating security vulnerabilities. Carefully apply security guidance, follow best security practices, and respect warnings issued by the firewall's manufacturer.
Permitting open communication with the NodeJS
process:
- Opens up the Node server to any connection, depending on the firewall's capabilities and configuration.
- Might be risky depending on your network.
- Is only recommended on developer machines.
If possible, only allow open communication with the NodeJS
process on trusted or private networks.
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:
- In the Debugger tab, open the developer tools in your browser. In the console, execute
localStorage.clear()
to remove any breakpoints. - 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, Edge and IE) 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 theNO_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.
- The
- 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 takes a short time to launch, 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.
protected override void OnInitialized()
{
#if DEBUG
Thread.Sleep(10000);
#endif
...
}
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
.
Blazor WebAssembly apps can be debugged using the browser developer tools in Chromium-based browsers (Edge/Chrome). You can also debug your app using the following IDEs:
- Visual Studio
- Visual Studio for Mac
- Visual Studio Code
Available scenarios include:
- Set and remove breakpoints.
- Run the app with debugging support in IDEs.
- Single-step through the code.
- Resume code execution with a keyboard shortcut in IDEs.
- In the Locals window, observe the values of local variables.
- See the call stack, including call chains between JavaScript and .NET.
For now, you can't:
- Break on unhandled exceptions.
- Hit breakpoints during app startup before the debug proxy is running. This includes breakpoints in
Program.cs
and breakpoints in theOnInitialized{Async}
lifecycle methods of components that are loaded by the first page requested from the app. - Debug in non-local scenarios (for example, Windows Subsystem for Linux (WSL) or Visual Studio Codespaces).
- Automatically rebuild the backend Server app of a hosted Blazor WebAssembly solution during debugging, for example by running the app with
dotnet watch run
.
Prerequisites
Debugging requires either of the following browsers:
- Google Chrome (version 70 or later) (default)
- Microsoft Edge (version 80 or later)
Ensure that firewalls or proxies don't block communication with the debug proxy (NodeJS
process). For more information, see the Firewall configuration section.
Visual Studio Code users require the following extensions:
- C# for Visual Studio Code Extension
- Blazor WASM Debugging Extension (when using the C# for Visual Studio Code Extension version 1.23.9 or later)
After opening a project in VS Code, you may receive a notification that additional setup is required to enable debugging. If requested, install the required extensions from the Visual Studio Marketplace. To inspect the installed extensions, open View > Extensions from the menu bar or select the Extensions icon in the Activity sidebar.
Visual Studio for Mac requires version 8.8 (build 1532) or later:
Install the latest release of Visual Studio for Mac by selecting the Download Visual Studio for Mac button at Microsoft: Visual Studio for Mac.
Note
Apple Safari on macOS isn't currently supported.
Packages
Standalone Blazor WebAssembly:
Microsoft.AspNetCore.Components.WebAssembly.DevServer
: Development server for use when building Blazor apps. Calls WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging internally to add middleware for debugging Blazor WebAssembly apps inside Chromium developer tools.
Hosted Blazor WebAssembly:
- Client project:
Microsoft.AspNetCore.Components.WebAssembly.DevServer
: Development server for use when building Blazor apps. Calls WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging internally to add middleware for debugging Blazor WebAssembly apps inside Chromium developer tools. - Server project:
Microsoft.AspNetCore.Components.WebAssembly.Server
: References an internal package (Microsoft.NETCore.BrowserDebugHost.Transport
) for assemblies that share the browser debug host.
Note
For guidance on adding packages to .NET apps, see the articles under Install and manage packages at Package consumption workflow (NuGet documentation). Confirm correct package versions at NuGet.org.
Debug a standalone Blazor WebAssembly app
To enable debugging for an existing Blazor WebAssembly app, update the launchSettings.json
file in the startup project to include the following inspectUri
property in each launch profile:
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"
Once updated, the launchSettings.json
file should look similar to the following example:
{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iisExpress": {
"applicationUrl": "http://localhost:50454",
"sslPort": 44399
}
},
"profiles": {
"IIS Express": {
"commandName": "IISExpress",
"launchBrowser": true,
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"BlazorApp1.Server": {
"commandName": "Project",
"launchBrowser": true,
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
"applicationUrl": "https://localhost:5001;http://localhost:5000",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
The inspectUri
property:
- Enables the IDE to detect that the app is a Blazor WebAssembly 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.
To debug a Blazor WebAssembly app in Visual Studio:
Create a new hosted Blazor WebAssembly solution.
With the Server project selected in Solution Explorer, press F5 to run the app in the debugger.
Note
When debugging with a Chromium-based browser, such as Google Chrome or Microsoft Edge, a new browser window might open with a separate profile for the debugging session instead of opening a tab in an existing browser window with the user's profile. If debugging with the user's profile is a requirement, adopt one of the following approaches:
- Close all open browser instances before pressing F5 to start debugging.
- Configure Visual Studio to launch the browser with the user's profile. For more information on this approach, see Blazor WASM Debugging in VS launches Edge with a separate user data directory (dotnet/aspnetcore #20915).
Note
Start Without Debugging [Ctrl+F5 (Windows) or ⌘+F5 (macOS)] isn't supported. When the app is run in Debug configuration, debugging overhead always results in a small performance reduction.
In the Client app, set a breakpoint on the
currentCount++;
line inPages/Counter.razor
.In the browser, navigate to
Counter
page and select the Click me button to hit the breakpoint.In Visual Studio, inspect the value of the
currentCount
field in the Locals window.Press F5 to continue execution.
While debugging a Blazor WebAssembly app, you can also debug server code:
- Set a breakpoint in the
Pages/FetchData.razor
page in OnInitializedAsync. - Set a breakpoint in the
WeatherForecastController
in theGet
action method. - Browse to the
Fetch Data
page to hit the first breakpoint in theFetchData
component just before it issues an HTTP request to the server. - Press F5 to continue execution and then hit the breakpoint on the server in the
WeatherForecastController
. - Press F5 again to let execution continue and see the weather forecast table rendered in the browser.
Note
Breakpoints are not hit during app startup before the debug proxy is running. This includes breakpoints in Program.cs
and breakpoints in the OnInitialized{Async}
lifecycle methods of components that are loaded by the first page requested from the app.
If the app is hosted at a different app base path than /
, update the following properties in Properties/launchSettings.json
to reflect the app's base path:
applicationUrl
:"iisSettings": { ... "iisExpress": { "applicationUrl": "http://localhost:{INSECURE PORT}/{APP BASE PATH}/", "sslPort": {SECURE PORT} } },
inspectUri
of each profile:"profiles": { ... "{PROFILE 1, 2, ... N}": { ... "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/{APP BASE PATH}/_framework/debug/ws-proxy?browser={browserInspectUri}", ... } }
The placeholders in the preceding settings:
{INSECURE PORT}
: The insecure port. A random value is provided by default, but a custom port is permitted.{APP BASE PATH}
: The app's base path.{SECURE PORT}
: The secure port. A random value is provided by default, but a custom port is permitted.{PROFILE 1, 2, ... N}
: Launch settings profiles. Usually, an app specifies more than one profile by default (for example, a profile for IIS Express and a project profile, which is used by Kestrel server).
In the following examples, the app is hosted at /OAT
with an app base path configured in wwwroot/index.html
as <base href="/OAT/">
:
"applicationUrl": "http://localhost:{INSECURE PORT}/OAT/",
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/OAT/_framework/debug/ws-proxy?browser={browserInspectUri}",
For information on using a custom app base path for Blazor WebAssembly apps, see Host and deploy ASP.NET Core Blazor.
Debug in the browser
The guidance in this section applies to Google Chrome and Microsoft Edge running on Windows.
Run a Debug build of the app in the Development environment.
Launch a browser and navigate to the app's URL (for example,
https://localhost:7268
).In the browser, attempt to commence remote debugging by pressing Shift+Alt+d.
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, which opens a new browser window. Close the previous browser window.
Once the browser is running with remote debugging enabled, the debugging keyboard shortcut in the previous step opens a new debugger tab.
After a moment, the Sources tab shows a list of the app's .NET assemblies within the
file://
node.In component code (
.razor
files) and C# code files (.cs
), breakpoints that you set are hit when 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.
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.
Warning
Modification of a firewall configuration must be made with care to avoid creating security vulnerabilities. Carefully apply security guidance, follow best security practices, and respect warnings issued by the firewall's manufacturer.
Permitting open communication with the NodeJS
process:
- Opens up the Node server to any connection, depending on the firewall's capabilities and configuration.
- Might be risky depending on your network.
- Is only recommended on developer machines.
If possible, only allow open communication with the NodeJS
process on trusted or private networks.
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:
- In the Debugger tab, open the developer tools in your browser. In the console, execute
localStorage.clear()
to remove any breakpoints. - 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, Edge and IE) 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 theNO_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.
- The
- 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 takes a short time to launch, 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.
protected override void OnInitialized()
{
#if DEBUG
Thread.Sleep(10000);
#endif
...
}
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
.
Blazor WebAssembly apps can be debugged using the browser developer tools in Chromium-based browsers (Edge/Chrome). You can also debug your app using the following IDEs:
- Visual Studio
- Visual Studio for Mac
- Visual Studio Code
Available scenarios include:
- Set and remove breakpoints.
- Run the app with debugging support in IDEs.
- Single-step through the code.
- Resume code execution with a keyboard shortcut in IDEs.
- In the Locals window, observe the values of local variables.
- See the call stack, including call chains between JavaScript and .NET.
For now, you can't:
- Break on unhandled exceptions.
- Hit breakpoints during app startup before the debug proxy is running. This includes breakpoints in
Program.cs
and breakpoints in theOnInitialized{Async}
lifecycle methods of components that are loaded by the first page requested from the app. - Debug in non-local scenarios (for example, Windows Subsystem for Linux (WSL) or Visual Studio Codespaces).
- Automatically rebuild the backend Server app of a hosted Blazor WebAssembly solution during debugging, for example by running the app with
dotnet watch run
.
Prerequisites
Debugging requires either of the following browsers:
- Google Chrome (version 70 or later) (default)
- Microsoft Edge (version 80 or later)
Ensure that firewalls or proxies don't block communication with the debug proxy (NodeJS
process). For more information, see the Firewall configuration section.
Visual Studio Code users require the following extensions:
- C# for Visual Studio Code Extension
- Blazor WASM Debugging Extension (when using the C# for Visual Studio Code Extension version 1.23.9 or later)
After opening a project in VS Code, you may receive a notification that additional setup is required to enable debugging. If requested, install the required extensions from the Visual Studio Marketplace. To inspect the installed extensions, open View > Extensions from the menu bar or select the Extensions icon in the Activity sidebar.
Visual Studio for Mac requires version 8.8 (build 1532) or later:
Install the latest release of Visual Studio for Mac by selecting the Download Visual Studio for Mac button at Microsoft: Visual Studio for Mac.
Note
Apple Safari on macOS isn't currently supported.
Packages
Standalone Blazor WebAssembly:
Microsoft.AspNetCore.Components.WebAssembly.DevServer
: Development server for use when building Blazor apps. Calls WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging internally to add middleware for debugging Blazor WebAssembly apps inside Chromium developer tools.
Hosted Blazor WebAssembly:
- Client project:
Microsoft.AspNetCore.Components.WebAssembly.DevServer
: Development server for use when building Blazor apps. Calls WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging internally to add middleware for debugging Blazor WebAssembly apps inside Chromium developer tools. - Server project:
Microsoft.AspNetCore.Components.WebAssembly.Server
: References an internal package (Microsoft.NETCore.BrowserDebugHost.Transport
) for assemblies that share the browser debug host.
Note
For guidance on adding packages to .NET apps, see the articles under Install and manage packages at Package consumption workflow (NuGet documentation). Confirm correct package versions at NuGet.org.
Debug a standalone Blazor WebAssembly app
To enable debugging for an existing Blazor WebAssembly app, update the launchSettings.json
file in the startup project to include the following inspectUri
property in each launch profile:
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"
Once updated, the launchSettings.json
file should look similar to the following example:
{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iisExpress": {
"applicationUrl": "http://localhost:50454",
"sslPort": 44399
}
},
"profiles": {
"IIS Express": {
"commandName": "IISExpress",
"launchBrowser": true,
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"BlazorApp1.Server": {
"commandName": "Project",
"launchBrowser": true,
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
"applicationUrl": "https://localhost:5001;http://localhost:5000",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
The inspectUri
property:
- Enables the IDE to detect that the app is a Blazor WebAssembly 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.
To debug a Blazor WebAssembly app in Visual Studio:
Create a new hosted Blazor WebAssembly solution.
With the Server project selected in Solution Explorer, press F5 to run the app in the debugger.
Note
When debugging with a Chromium-based browser, such as Google Chrome or Microsoft Edge, a new browser window might open with a separate profile for the debugging session instead of opening a tab in an existing browser window with the user's profile. If debugging with the user's profile is a requirement, adopt one of the following approaches:
- Close all open browser instances before pressing F5 to start debugging.
- Configure Visual Studio to launch the browser with the user's profile. For more information on this approach, see Blazor WASM Debugging in VS launches Edge with a separate user data directory (dotnet/aspnetcore #20915).
Note
Start Without Debugging [Ctrl+F5 (Windows) or ⌘+F5 (macOS)] isn't supported. When the app is run in Debug configuration, debugging overhead always results in a small performance reduction.
In the Client app, set a breakpoint on the
currentCount++;
line inPages/Counter.razor
.In the browser, navigate to
Counter
page and select the Click me button to hit the breakpoint.In Visual Studio, inspect the value of the
currentCount
field in the Locals window.Press F5 to continue execution.
While debugging a Blazor WebAssembly app, you can also debug server code:
- Set a breakpoint in the
Pages/FetchData.razor
page in OnInitializedAsync. - Set a breakpoint in the
WeatherForecastController
in theGet
action method. - Browse to the
Fetch Data
page to hit the first breakpoint in theFetchData
component just before it issues an HTTP request to the server. - Press F5 to continue execution and then hit the breakpoint on the server in the
WeatherForecastController
. - Press F5 again to let execution continue and see the weather forecast table rendered in the browser.
Note
Breakpoints are not hit during app startup before the debug proxy is running. This includes breakpoints in Program.cs
and breakpoints in the OnInitialized{Async}
lifecycle methods of components that are loaded by the first page requested from the app.
If the app is hosted at a different app base path than /
, update the following properties in Properties/launchSettings.json
to reflect the app's base path:
applicationUrl
:"iisSettings": { ... "iisExpress": { "applicationUrl": "http://localhost:{INSECURE PORT}/{APP BASE PATH}/", "sslPort": {SECURE PORT} } },
inspectUri
of each profile:"profiles": { ... "{PROFILE 1, 2, ... N}": { ... "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/{APP BASE PATH}/_framework/debug/ws-proxy?browser={browserInspectUri}", ... } }
The placeholders in the preceding settings:
{INSECURE PORT}
: The insecure port. A random value is provided by default, but a custom port is permitted.{APP BASE PATH}
: The app's base path.{SECURE PORT}
: The secure port. A random value is provided by default, but a custom port is permitted.{PROFILE 1, 2, ... N}
: Launch settings profiles. Usually, an app specifies more than one profile by default (for example, a profile for IIS Express and a project profile, which is used by Kestrel server).
In the following examples, the app is hosted at /OAT
with an app base path configured in wwwroot/index.html
as <base href="/OAT/">
:
"applicationUrl": "http://localhost:{INSECURE PORT}/OAT/",
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/OAT/_framework/debug/ws-proxy?browser={browserInspectUri}",
For information on using a custom app base path for Blazor WebAssembly apps, see Host and deploy ASP.NET Core Blazor.
Debug in the browser
The guidance in this section applies to Google Chrome and Microsoft Edge running on Windows.
Run a Debug build of the app in the Development environment.
Launch a browser and navigate to the app's URL (for example,
https://localhost:5001
).In the browser, attempt to commence remote debugging by pressing Shift+Alt+d.
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, which opens a new browser window. Close the previous browser window.
Once the browser is running with remote debugging enabled, the debugging keyboard shortcut in the previous step opens a new debugger tab.
After a moment, the Sources tab shows a list of the app's .NET assemblies within the
file://
node.In component code (
.razor
files) and C# code files (.cs
), breakpoints that you set are hit when 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.
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.
Warning
Modification of a firewall configuration must be made with care to avoid creating security vulnerabilities. Carefully apply security guidance, follow best security practices, and respect warnings issued by the firewall's manufacturer.
Permitting open communication with the NodeJS
process:
- Opens up the Node server to any connection, depending on the firewall's capabilities and configuration.
- Might be risky depending on your network.
- Is only recommended on developer machines.
If possible, only allow open communication with the NodeJS
process on trusted or private networks.
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:
- In the Debugger tab, open the developer tools in your browser. In the console, execute
localStorage.clear()
to remove any breakpoints. - 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, Edge and IE) 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 theNO_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.
- The
- 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 takes a short time to launch, 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.
protected override void OnInitialized()
{
#if DEBUG
Thread.Sleep(10000);
#endif
...
}
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
.
Blazor WebAssembly apps can be debugged using the browser developer tools in Chromium-based browsers (Edge/Chrome). You can also debug your app using the following IDEs:
- Visual Studio
- Visual Studio for Mac
- Visual Studio Code
Available scenarios include:
- Set and remove breakpoints.
- Run the app with debugging support in IDEs.
- Single-step through the code.
- Resume code execution with a keyboard shortcut in IDEs.
- In the Locals window, observe the values of local variables.
- See the call stack, including call chains between JavaScript and .NET.
For now, you can't:
- Break on unhandled exceptions.
- Hit breakpoints during app startup before the debug proxy is running. This includes breakpoints in
Program.cs
and breakpoints in theOnInitialized{Async}
lifecycle methods of components that are loaded by the first page requested from the app. - Debug in non-local scenarios (for example, Windows Subsystem for Linux (WSL) or Visual Studio Codespaces).
- Automatically rebuild the backend Server app of a hosted Blazor WebAssembly solution during debugging, for example by running the app with
dotnet watch run
.
Prerequisites
Debugging requires either of the following browsers:
- Google Chrome (version 70 or later) (default)
- Microsoft Edge (version 80 or later)
Ensure that firewalls or proxies don't block communication with the debug proxy (NodeJS
process). For more information, see the Firewall configuration section.
Visual Studio Code users require the following extensions:
- C# for Visual Studio Code Extension
- Blazor WASM Debugging Extension (when using the C# for Visual Studio Code Extension version 1.23.9 or later)
After opening a project in VS Code, you may receive a notification that additional setup is required to enable debugging. If requested, install the required extensions from the Visual Studio Marketplace. To inspect the installed extensions, open View > Extensions from the menu bar or select the Extensions icon in the Activity sidebar.
Visual Studio for Mac requires version 8.8 (build 1532) or later:
Install the latest release of Visual Studio for Mac by selecting the Download Visual Studio for Mac button at Microsoft: Visual Studio for Mac.
Note
Apple Safari on macOS isn't currently supported.
Packages
Standalone Blazor WebAssembly:
Microsoft.AspNetCore.Components.WebAssembly.DevServer
: Development server for use when building Blazor apps. Calls WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging internally to add middleware for debugging Blazor WebAssembly apps inside Chromium developer tools.
Hosted Blazor WebAssembly:
- Client project:
Microsoft.AspNetCore.Components.WebAssembly.DevServer
: Development server for use when building Blazor apps. Calls WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging internally to add middleware for debugging Blazor WebAssembly apps inside Chromium developer tools. - Server project:
Microsoft.AspNetCore.Components.WebAssembly.Server
: References an internal package (Microsoft.NETCore.BrowserDebugHost.Transport
) for assemblies that share the browser debug host.
Note
For guidance on adding packages to .NET apps, see the articles under Install and manage packages at Package consumption workflow (NuGet documentation). Confirm correct package versions at NuGet.org.
Debug a standalone Blazor WebAssembly app
To enable debugging for an existing Blazor WebAssembly app, update the launchSettings.json
file in the startup project to include the following inspectUri
property in each launch profile:
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"
Once updated, the launchSettings.json
file should look similar to the following example:
{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iisExpress": {
"applicationUrl": "http://localhost:50454",
"sslPort": 44399
}
},
"profiles": {
"IIS Express": {
"commandName": "IISExpress",
"launchBrowser": true,
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"BlazorApp1.Server": {
"commandName": "Project",
"launchBrowser": true,
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
"applicationUrl": "https://localhost:5001;http://localhost:5000",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
The inspectUri
property:
- Enables the IDE to detect that the app is a Blazor WebAssembly 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.
To debug a Blazor WebAssembly app in Visual Studio:
Create a new hosted Blazor WebAssembly solution.
With the Server project selected in Solution Explorer, press F5 to run the app in the debugger.
Note
When debugging with a Chromium-based browser, such as Google Chrome or Microsoft Edge, a new browser window might open with a separate profile for the debugging session instead of opening a tab in an existing browser window with the user's profile. If debugging with the user's profile is a requirement, adopt one of the following approaches:
- Close all open browser instances before pressing F5 to start debugging.
- Configure Visual Studio to launch the browser with the user's profile. For more information on this approach, see Blazor WASM Debugging in VS launches Edge with a separate user data directory (dotnet/aspnetcore #20915).
Note
Start Without Debugging [Ctrl+F5 (Windows) or ⌘+F5 (macOS)] isn't supported. When the app is run in Debug configuration, debugging overhead always results in a small performance reduction.
In the Client app, set a breakpoint on the
currentCount++;
line inPages/Counter.razor
.In the browser, navigate to
Counter
page and select the Click me button to hit the breakpoint.In Visual Studio, inspect the value of the
currentCount
field in the Locals window.Press F5 to continue execution.
While debugging a Blazor WebAssembly app, you can also debug server code:
- Set a breakpoint in the
Pages/FetchData.razor
page in OnInitializedAsync. - Set a breakpoint in the
WeatherForecastController
in theGet
action method. - Browse to the
Fetch Data
page to hit the first breakpoint in theFetchData
component just before it issues an HTTP request to the server. - Press F5 to continue execution and then hit the breakpoint on the server in the
WeatherForecastController
. - Press F5 again to let execution continue and see the weather forecast table rendered in the browser.
Note
Breakpoints are not hit during app startup before the debug proxy is running. This includes breakpoints in Program.cs
and breakpoints in the OnInitialized{Async}
lifecycle methods of components that are loaded by the first page requested from the app.
If the app is hosted at a different app base path than /
, update the following properties in Properties/launchSettings.json
to reflect the app's base path:
applicationUrl
:"iisSettings": { ... "iisExpress": { "applicationUrl": "http://localhost:{INSECURE PORT}/{APP BASE PATH}/", "sslPort": {SECURE PORT} } },
inspectUri
of each profile:"profiles": { ... "{PROFILE 1, 2, ... N}": { ... "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/{APP BASE PATH}/_framework/debug/ws-proxy?browser={browserInspectUri}", ... } }
The placeholders in the preceding settings:
{INSECURE PORT}
: The insecure port. A random value is provided by default, but a custom port is permitted.{APP BASE PATH}
: The app's base path.{SECURE PORT}
: The secure port. A random value is provided by default, but a custom port is permitted.{PROFILE 1, 2, ... N}
: Launch settings profiles. Usually, an app specifies more than one profile by default (for example, a profile for IIS Express and a project profile, which is used by Kestrel server).
In the following examples, the app is hosted at /OAT
with an app base path configured in wwwroot/index.html
as <base href="/OAT/">
:
"applicationUrl": "http://localhost:{INSECURE PORT}/OAT/",
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/OAT/_framework/debug/ws-proxy?browser={browserInspectUri}",
For information on using a custom app base path for Blazor WebAssembly apps, see Host and deploy ASP.NET Core Blazor.
Debug in the browser
The guidance in this section applies to Google Chrome and Microsoft Edge running on Windows.
Run a Debug build of the app in the Development environment.
Launch a browser and navigate to the app's URL (for example,
https://localhost:5001
).In the browser, attempt to commence remote debugging by pressing Shift+Alt+d.
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, which opens a new browser window. Close the previous browser window.
Once the browser is running with remote debugging enabled, the debugging keyboard shortcut in the previous step opens a new debugger tab.
After a moment, the Sources tab shows a list of the app's .NET assemblies within the
file://
node.In component code (
.razor
files) and C# code files (.cs
), breakpoints that you set are hit when 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.
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.
Warning
Modification of a firewall configuration must be made with care to avoid creating security vulnerabilities. Carefully apply security guidance, follow best security practices, and respect warnings issued by the firewall's manufacturer.
Permitting open communication with the NodeJS
process:
- Opens up the Node server to any connection, depending on the firewall's capabilities and configuration.
- Might be risky depending on your network.
- Is only recommended on developer machines.
If possible, only allow open communication with the NodeJS
process on trusted or private networks.
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:
- In the Debugger tab, open the developer tools in your browser. In the console, execute
localStorage.clear()
to remove any breakpoints. - 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, Edge and IE) 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 theNO_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.
- The
- 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 takes a short time to launch, 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.
protected override void OnInitialized()
{
#if DEBUG
Thread.Sleep(10000);
#endif
...
}
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
.
Feedback
Submit and view feedback for