调试 ASP.NET Core Blazor WebAssembly

相关文章推荐

豪爽的海龟 · 当今开源大语言模型一览，每个AI ...· 7 月前 ·

豪气的机器人 · el-checkbox出现的传值问题以及ch ...· 1 年前 ·

俊逸的炒饭 · 无反射边界条件_百度百科· 1 年前 ·

此信息与预发布产品相关，相应产品在商业发布之前可能会进行重大修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

对于当前版本，请参阅本文的 .NET 7 版本。

本文介绍如何使用浏览器开发人员工具和集成开发环境 (IDE) 调试 Blazor WebAssembly。

可以使用基于 Chromium 的浏览器 (Microsoft Edge/Chrome) 和 Firefox 中的浏览器开发人员工具调试 Blazor WebAssembly 应用。还可以使用以下 IDE 调试应用：

Visual Studio

Visual Studio Code

可用方案包括：

设置和删除断点。

在 IDE 中运行具有调试支持的应用。

单步执行代码。

在 IDE 中使用键盘快捷方式恢复代码执行。

在“局部变量”窗口中，观察局部变量的值。

请参阅调用堆栈，包括 JavaScript 和 .NET 之间的调用链。

使用符号服务器进行调试，由 Visual Studio 首选项配置。

目前，无法执行以下操作：

出现未经处理的异常时中断。

于应用启动期间在调试代理运行之前命中断点。这包括 Program.cs 中的断点和组件的 OnInitialized{Async} 生命周期方法中的断点，其中这些组件由请求自应用的第一页加载。

在非本地方案中调试（例如，适用于 Linux 的 Windows 子系统 (WSL) 或 Visual Studio Codespaces ）。

从 Visual Studio 在 Firefox 中进行调试。

可以使用基于 Chromium 的浏览器 (Microsoft Edge/Chrome) 中的浏览器开发人员工具调试 Blazor WebAssembly 应用。还可以使用以下 IDE 调试应用：

Visual Studio

Visual Studio Code

可用方案包括：

设置和删除断点。

在 IDE 中运行具有调试支持的应用。

单步执行代码。

在 IDE 中使用键盘快捷方式恢复代码执行。

在“局部变量”窗口中，观察局部变量的值。

请参阅调用堆栈，包括 JavaScript 和 .NET 之间的调用链。

目前，无法执行以下操作：

出现未经处理的异常时中断。

于应用启动期间在调试代理运行之前命中断点。这包括


    Program.cs

中的断点和组件的


     OnInitialized{Async}

生命周期方法中的断点，其中这些组件由请求自应用的第一页加载。

在非本地方案中调试（例如，适用于 Linux 的 Windows 子系统 (WSL) 或 Visual Studio Codespaces ）。

使用符号服务器进行调试。

调试需要以下浏览器的最新版本：

Google Chrome

Microsoft Edge

Firefox

调试需要以下浏览器的最新版本：

Google Chrome（默认）

Microsoft Edge

确保防火墙或代理不会阻止与调试代理（ NodeJS 进程）之间的通信。有关详细信息，请参阅防火墙配置部分。

Visual Studio Code 用户需要适用于 Visual Studio Code 的 C# 扩展。

Visual Studio Code 用户需要以下扩展：

适用于 Visual Studio Code 的 C# 扩展

Blazor WASM 调试扩展（使用适用于 Visual Studio Code 的 C# 扩展版本 1.23.9 或更高版本时）

在 VS Code 中打开项目后可能会收到通知，告诉你需要进行其他设置才能启用调试。如果收到请求，请从 Visual Studio Marketplace 安装所需扩展。若要检查是否已安装此扩展，请在菜单栏中依次打开“视图”>“扩展”，或选择“活动”边栏中的“扩展”图标。

当前不支持 macOS 上的 Apple Safari。

独立 Blazor WebAssembly： Microsoft.AspNetCore.Components.WebAssembly.DevServer ：生成 Blazor 应用时要使用的开发服务器。在内部调用 WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging 来添加中间件以在 Chromium 开发人员工具中调试 Blazor WebAssembly 应用。

调试独立的 Blazor WebAssembly 应用

若要为现有 Blazor WebAssembly 应用启用调试，请更新启动项目中的 launchSettings.json 文件，使每个启动配置文件包含以下 inspectUri 属性：

"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"
更新后，launchSettings.json 文件应类似于以下示例：
    "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"
inspectUri 属性具有以下作用：
使 IDE 能够检测到该应用为 Blazor WebAssembly 应用。
指示脚本调试基础结构通过 Blazor 的调试代理连接到浏览器。
已启动的浏览器 (browserInspectUri) 上 WebSocket 协议 (wsProtocol)、主机 (url.hostname)、端口 (url.port) 和检查器 URI 的占位符值由框架提供。
Visual Studio
有关在 .vscode 文件夹中配置 VS Code 资产的信息，请参阅用于 ASP.NET Core Blazor 的工具中的 Linux 操作系统指南。
要在 Visual Studio 中调试 Blazor WebAssembly 应用，请按以下步骤执行：
在 VS Code 中打开独立 Blazor WebAssembly 应用。
可能会收到通知，告诉你需要进行其他设置才能启用调试：
需要进行其他设置才能调试 Blazor WebAssembly 应用程序。
如果收到通知，请执行以下操作：
确认是否已安装最新的适用于 Visual Studio Code 的 C# 扩展。 若要检查是否已安装此扩展，请在菜单栏中依次打开“视图”>“扩展”，或选择“活动”边栏中的“扩展”图标。
使用适用于 Visual Studio Code 的 C# 扩展版本 1.23.9 或更高版本时，请确认安装了最新的 Blazor WASM 调试扩展。 若要检查是否已安装此扩展，请在菜单栏中依次打开“视图”>“扩展”，或选择“活动”边栏中的“扩展”图标。
重载窗口。
请创建一个具有以下配置的 .vscode/launch.json 文件。 将 {PORT} 占位符替换为 Properties/launchSettings.json 中配置的端口：
  "name": "Launch and Debug",
  "type": "blazorwasm",
  "request": "launch",
  "url": "http://localhost:{PORT}"
如果应用位于工作区根目录的子文件夹中，请将当前工作目录 (cwd) 属性与应用的路径一起包含在内。 在以下属性值中，将 {PATH} 占位符替换为应用的路径：
"cwd": "${workspaceFolder}/{PATH}"
在以下示例中，应用位于名为 blazorwasm 的子文件夹中：
"cwd": "${workspaceFolder}/blazorwasm"
使用 F5 键盘快捷方式或菜单命令启动调试。
不支持“启动时不调试” [Ctrl+F5 (Windows) 或 ⌘+F5 (macOS )]。 当应用以调试配置运行时，调试开销始终会导致性能的小幅下降。
此时会启动独立应用，并打开调试浏览器。
在 Client 应用中，在 Pages/Counter.razor 中的 currentCount++; 行上设置断点。
在浏览器中，导航到 Counter 页，然后选择“单击此处”按钮以命中断点。
在运行调试代理之前，在应用启动期间不会命中断点。 这包括 Program.cs 中的断点和组件的 OnInitialized{Async} 生命周期方法中的断点，其中这些组件由请求自应用的第一页加载。
附加到现有的调试会话
若要附加到正在运行的 Blazor 应用，请创建一个具有以下配置的 .vscode/launch.json 文件。 将 {URL} 占位符替换为运行应用的 URL：
  "name": "Attach and Debug",
  "type": "blazorwasm",
  "request": "attach",
  "url": "{URL}"
只有独立应用才支持附加到调试会话。 若要使用完整堆栈调试，必须从 VS Code 启动应用。
启动配置选项
blazorwasm 调试类型 (.vscode/launch.json) 支持以下启动配置选项。
片刻后，“源”选项卡显示 file:// 节点中应用的 .NET 程序集的列表。
在组件代码（.razor 文件）和 C# 代码文件 (.cs) 中，当代码执行时将命中你设置的断点。 命中断点后，正常单步执行代码 (F10) 或恢复代码执行 (F8)。
Blazor 提供调试代理，该代理实现 Chrome DevTools Protocol，并使用特定于 .NET 的信息扩展该协议。 按下调试键盘快捷方式后，Blazor 会将 Chrome 开发者工具指向代理。 代理连接到要调试的浏览器窗口（因此需要启用远程调试）。
使用 Firefox 进行调试
使用 Firefox 调试 Blazor WebAssembly 应用需要配置浏览器以进行远程调试，并通过 .NET WebAssembly 调试代理使用浏览器开发人员工具连接到浏览器。
目前不支持从 Visual Studio 在 Firefox 中进行调试。
若要在开发期间调试 Blazor WebAssembly 应用，请执行以下操作：
在 Firefox 中打开 Blazor WebAssembly 应用。
打开 Firefox Web 开发人员工具并转到 Console 选项卡。
当 Blazor WebAssembly 应用处于焦点时，键入调试命令 SHIFT+ALT+D。
按照控制台输出中的说明配置 Firefox 进行 Blazor WebAssembly 调试：
在 Firefox 中打开 about:config。
启用 devtools.debugger.remote-enabled。
启用 devtools.chrome.enabled。
禁用 devtools.debugger.prompt-connection。
通过在命令行界面中运行以下命令，关闭所有 Firefox 实例并重新打开启用了远程调试的 Firefox：firefox --start-debugger-server 6000 -new-tab about:debugging。
在新的 Firefox 实例中，使 about:debugging 选项卡保持打开状态，并在新的浏览器选项卡中打开 Blazor WebAssembly 应用。
键入 SHIFT+Alt 打开 Firefox Web 开发人员工具并连接到 Firefox 浏览器实例。
在 Debugger 选项卡中，在 file:// 节点下打开要调试的应用源文件，并设置断点。 例如，在 Counter 组件 (Counter.razor) 的 IncrementCount 方法中设置断点。
导航到 Counter 组件页 (/counter) 并选择计数器按钮以命中断点。
浏览器源映射
浏览器源映射允许浏览器将编译后的文件映射回其原始源文件，并且通常用于客户端调试。 但是，Blazor 当前不直接将 C# 映射到 JavaScript/WASM。 相反，Blazor 在浏览器中进行 IL 解释，因此源映射不相关。
防火墙配置
如果防火墙阻止与调试代理之间的通信，则创建允许浏览器与 NodeJS 进程之间进行通信的防火墙例外规则。
必须谨慎修改防火墙配置，以避免造成安全漏洞。 仔细应用安全指南、遵循最佳安全实践，并遵守防火墙制造商发出的警告。
允许与 NodeJS 进程之间的开放式通信：
根据防火墙的功能和配置，打开节点服务器的任何连接。
可能会因网络而有风险。
仅建议在开发人员计算机上使用。
如果可能，只允许与受信任的网络或专用网络上的 NodeJS 进程之间的开放式通信。
有关 Windows 防火墙配置指南，请参阅创建入站程序或服务规则。 有关详细信息，请参阅 Windows 防火墙文档集中的具有高级安全性的 Windows Defender 防火墙和相关文章。
如果遇到错误，以下提示可能有所帮助：
在“调试程序”选项卡中，在浏览器中打开开发人员工具。 在控制台中，执行 localStorage.clear() 以删除所有断点。
确认你已安装并信任 ASP.NET Core HTTPS 开发证书。 有关详细信息，请参阅在 ASP.NET Core 中强制使用 HTTPS。
Visual Studio 要求在“工具”>“选项”>“调试”>“常规”中选择“对 ASP.NET 启用 JavaScript 调试(Chrome、Edge 和 IE)”选项。 这是 Visual Studio 的默认设置。 如果调试不起作用，请确认已选中该选项。
如果你的环境使用 HTTP 代理，请确保在代理绕过设置中包含 localhost。 这可以通过在以下二者之一中设置 NO_PROXY 环境变量来实现：
项目的 launchSettings.json 文件。
在将其应用于所有应用时所在的用户或系统环境变量级别。 使用环境变量时，请重新启动 Visual Studio 以使更改生效。
确保防火墙或代理不会阻止与调试代理（NodeJS 进程）之间的通信。 有关详细信息，请参阅防火墙配置部分。
OnInitialized{Async} 中的未命中断点
Blazor 框架的调试代理需要一小段时间才能启动，因此 OnInitialized{Async} 生命周期方法中的断点可能不会命中。 建议在方法主体开头添加延迟，以便在命中断点之前，为调试代理指定一段时间来启动。 你可以根据 if 编译器指令包括延迟，以确保应用的发布版本不存在延迟。
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) 超时
如果 Visual Studio 引发了调试适配器启动因已达到超时而失败的异常，可使用注册表设置调整超时：
VsRegEdit.exe set "<VSInstallFolder>" HKCU JSDebugger\Options\Debugging "BlazorTimeoutInMilliseconds" dword {TIMEOUT}
前述命令中的 {TIMEOUT} 占位符以毫秒为单位。 例如， 1 分钟指定为 60000。