可以使用基于 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
编译器指令包括延迟,以确保应用的发布版本不存在延迟。
C#
protected override void OnInitialized()
{
#if DEBUG
Thread.Sleep(10000)
#endif
...
}
C#
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
。