调试 ASP.NET Core Blazor WebAssembly

引用自：https://docs.microsoft.com/zh-cn/aspnet/core/blazor/debug?cid=kerryherger&tabs=visual-studio&view=aspnetcore-3.1

可以使用基于 Chromium 的浏览器 (Edge/Chrome) 中的浏览器开发工具调试 Blazor WebAssembly 应用。还可以使用以下集成开发环境 (IDE) 调试应用（注意：是要Edge/Chrome）：

Visual Studio
Visual Studio for Mac
Visual Studio Code

可用方案包括：

设置和删除断点。
在 IDE 中运行具有调试支持的应用。
单步执行代码。
在 IDE 中使用键盘快捷方式恢复代码执行。
在“局部变量”窗口中，观察局部变量的值。
请参阅调用堆栈，包括 JavaScript 和 .NET 之间的调用链。

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

出现未经处理的异常时中断。
于应用启动期间在调试代理运行之前命中断点。这包括 Program.Main (Program.cs) 中的断点和组件的 OnInitialized{Async} 方法中的断点，其中这些组件由请求自应用的第一页加载。

先决条件

调试需要使用以下浏览器之一：

Google Chrome（版本 70 或更高版本）（默认）
Microsoft Edge（版本 80 或更高版本）

Visual Studio for Mac 需要版本 8.8（内部版本 1532）或更高版本：

选择 Microsoft：Visual Studio for Mac 页面上的“下载 Visual Studio for Mac”按钮，安装最新版本的 Visual Studio for Mac。
从 Visual Studio 中选择预览通道。有关详细信息，请参阅安装 Visual Studio for Mac 的预览版本。

备注

当前不支持 macOS 上的 Apple Safari。

启用调试

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

JSON

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

更新后，launchSettings.json 文件应类似于以下示例：

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 中调试 Blazor WebAssembly 应用，请按以下步骤执行：

创建新的 ASP.NET Core 托管 Blazor WebAssembly 应用。
按 F5 在调试器中运行应用。

备注

不支持“启动时不调试”(Ctrl+F5)。当应用以调试配置运行时，调试开销始终会导致性能的小幅下降。
在客户端应用中，在 Pages/Counter.razor 中的 currentCount++; 行上设置断点。
在浏览器中，导航到 Counter 页，然后选择“单击此处”按钮以命中断点。
在 Visual Studio 中，检查“局部变量”窗口中 currentCount 字段的值。
按 F5 继续执行。

调试 Blazor WebAssembly 应用时，还可以调试服务器代码：

在 OnInitializedAsync 的“Pages/FetchData.razor”页中设置断点。
在 Get 操作方法的 WeatherForecastController 中设置一个断点。
浏览到 Fetch Data 页，在 FetchData 组件中的首个断点向服务器发出 HTTP 请求前命中该断点。
按 F5 以继续执行，然后在服务器上命中 WeatherForecastController 中的断点。
再次按 F5 以继续执行，并查看浏览器中呈现的天气预报表。

备注

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

如果应用托管在不同于 / 的应用程序基路径上，请更新 Properties/launchSettings.json 中的以下属性，以反映应用程序的基路径：

applicationUrl:

JSON

"iisSettings": {
  ...
  "iisExpress": {
    "applicationUrl": "http://localhost:{INSECURE PORT}/{APP BASE PATH}/",
    "sslPort": {SECURE PORT}
  }
},

每个配置文件的 inspectUri：

JSON

"profiles": {
  ...
  "{PROFILE 1, 2, ... N}": {
    ...
    "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/{APP BASE PATH}/_framework/debug/ws-proxy?browser={browserInspectUri}",
    ...
  }
}

前面设置中的占位符：

{INSECURE PORT}：不安全的端口。默认情况下提供随机值，但允许使用自定义端口。
{APP BASE PATH}：应用程序的基路径。
{SECURE PORT}：安全的端口。默认情况下提供随机值，但允许使用自定义端口。
{PROFILE 1, 2, ... N}：启动设置配置文件。通常，应用会默认指定多个配置文件（例如，IIS Express 的配置文件和 Kestrel 服务器使用的项目配置文件）。

在下面的示例中，应用托管在 /OAT 上，并在 wwwroot/index.html 中将应用程序基路径配置为 <base href="/OAT/">：

JSON

"applicationUrl": "http://localhost:{INSECURE PORT}/OAT/",

JSON

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

有关将自定义应用基路径用于 Blazor WebAssembly 应用的信息，请参阅托管和部署 ASP.NET Core Blazor。

在浏览器中调试

本部分中的指南适用于在 Windows 上运行的 Google Chrome 和 Microsoft Edge。

在开发环境中运行该应用的调试版本。
启动浏览器并导航到应用程序的 URL（例如 https://localhost:5001）。
在浏览器中，尝试通过按 Shift+Alt+d 启动远程调试。

浏览器必须在已启用远程调试的情况下运行，而这并不是默认设置。如果远程调试处于禁用状态，将呈现“无法找到可调试的浏览器选项卡”错误页，并且其中包含关于在调试端口打开的情况下启动浏览器的说明。按照适用于你的浏览器的说明操作，接下来将打开一个新的浏览器窗口。关闭上一个浏览器窗口。

在启用远程调试的情况下运行浏览器后，按上一步中的调试键盘快捷方式会打开新的调试程序选项卡。
片刻后，“源”选项卡显示 file:// 节点中应用的 .NET 程序集的列表。
在组件代码（.razor 文件）和 C# 代码文件 (.cs) 中，当代码执行时将命中你设置的断点。命中断点后，正常单步执行代码 (F10) 或恢复代码执行 (F8)。

Blazor 提供调试代理，该代理实现 Chrome DevTools Protocol，并使用特定于 .NET 的信息扩展该协议。按下调试键盘快捷方式后，Blazor 会将 Chrome 开发者工具指向代理。代理连接到要调试的浏览器窗口（因此需要启用远程调试）。

浏览器源映射

浏览器源映射允许浏览器将编译后的文件映射回其原始源文件，并且通常用于客户端调试。但是，Blazor 当前不直接将 C# 映射到 JavaScript/WASM。相反，Blazor 在浏览器中进行 IL 解释，因此源映射不相关。

疑难解答

如果遇到错误，以下提示可能有所帮助：

在“调试程序”选项卡中，在浏览器中打开开发人员工具。在控制台中，执行 localStorage.clear() 以删除所有断点。
确认你已安装并信任 ASP.NET Core HTTPS 开发证书。有关详细信息，请参阅在 ASP.NET Core 强制实施 HTTPS。
Visual Studio 要求在“工具” > “选项” > “调试” > “常规”中选择“对 ASP.NET 启用 JavaScript 调试(Chrome、Edge 和 IE)”选项。这是 Visual Studio 的默认设置。如果调试不起作用，请确认已选中该选项。

`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。