配置 C# 调试
你可以在 Visual Studio Code 中通过 launch.json
、launchSettings.json
或你的用户 settings.json
文件配置 C# 调试器。
演练:设置命令行参数
在深入探讨所有可能的选项之前,让我们先来了解一个基本场景:为程序设置命令行参数。这些步骤也适用于更新其他基本选项,如环境变量或当前工作目录。
方法 1:launchSettings.json
对于 C# 开发工具包,建议的调试方式是让 C# 开发工具包从项目文件中的设置自动确定如何调试。这意味着你可能没有 <workspace_root>/.vscode/launch.json
文件,或者如果你有,你需要在活动配置中设置 "type": "dotnet"
。对于命令行参数,"从项目文件确定" 意味着从 <Project-Directory>/Properties/launchSettings.json
中提取值。launchSettings.json
的优点在于它允许在 Visual Studio Code、完整的 Visual Studio 和 dotnet run
之间共享设置。
对于此情况,以下是设置命令行参数的步骤
- 在工作区资源管理器视图中,导航到你想要启动的项目(.csproj 文件)的目录
- 如果还没有
Properties
目录,请创建一个 - 如果还没有
launchSettings.json
文件,请创建一个,你可以使用以下文本作为示例 - 将
commandLineArgs
属性更改为你想要的命令行参数
launchSettings.json
文件示例:
{
"profiles": {
"MyLaunchProfileName": {
"commandName": "Project",
"commandLineArgs": "MyFirstArgument MySecondArgument"
}
}
}
方法 2:launch.json
如果你在 VS Code 中使用 coreclr
或 clr
调试适配器类型,命令行参数存储在你的 <workspace_root>/.vscode/launch.json
中。在这种情况下编辑它们
- 打开
<workspace_root>/.vscode/launch.json
- 找到你想要启动的
coreclr
或clr
启动配置 - 编辑
args
属性。这可以是一个字符串,也可以是一个字符串数组
配置 launchSettings.json
通过 C# 开发工具包,你可以将 Visual Studio 中的 launchSettings.json
文件带到 Visual Studio Code 中使用
示例
{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iisExpress": {
"applicationUrl": "http://localhost:59481",
"sslPort": 44308
}
},
"profiles": {
"EnvironmentsSample": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://localhost:7152;http://localhost:5105",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"EnvironmentsSample-Staging": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://localhost:7152;http://localhost:5105",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Staging",
"ASPNETCORE_DETAILEDERRORS": "1",
"ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
}
},
"EnvironmentsSample-Production": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://localhost:7152;http://localhost:5105",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Production"
}
},
"IIS Express": {
"commandName": "IISExpress",
"launchBrowser": true,
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
}
}
}
配置文件属性
commandLineArgs
- 要传递给正在运行的目标的参数。executablePath
- 可执行文件的绝对或相对路径。workingDirectory
- 设置命令的工作目录。launchBrowser
- 如果应启动浏览器,则设置为true
。applicationUrl
- 要为 Web 服务器配置的 URL 列表(以分号分隔)。sslPort
- 用于网站的 SSL 端口。httpPort
- 用于网站的 HTTP 端口。
可配置选项列表
以下是调试时你可能想要更改的常见选项。
PreLaunchTask
preLaunchTask
字段会在调试程序之前运行 tasks.json
中关联的 taskName。你可以通过从 VS Code 命令面板执行命令 Tasks: Configure Tasks Runner 来获取默认的构建预启动任务。
这会创建一个运行 dotnet build
的任务。你可以在 VS Code 任务 文档中了解更多信息。
可用性
launch.json
✔️settings.json
❌launchSettings.json
❌
程序
程序字段设置为要启动的应用程序 dll 或 .NET Core 主机可执行文件的路径。
此属性通常采用以下形式:"${workspaceFolder}/bin/Debug/<target-framework>/<project-name.dll>"。
示例:"${workspaceFolder}/bin/Debug/netcoreapp1.1/MyProject.dll"
其中
- <target-framework> 是调试项目所针对的框架。这通常在项目文件中作为 'TargetFramework' 属性找到。
- <project-name.dll> 是调试项目的构建输出 dll 的名称。这通常与项目文件名相同,但带有 '.dll' 扩展名。
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 作为executablePath
Cwd
目标进程的工作目录。
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 作为workingDirectory
Args
这些是将传递给你的程序的参数。
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 作为commandLineArgs
在入口处停止
如果你需要在目标的入口点停止,你可以选择将 stopAtEntry
设置为 "true"。
可用性
launch.json
✔️settings.json
✔️ 作为csharp.debug.stopAtEntry
launchSettings.json
❌
启动 Web 浏览器
ASP.NET Core 项目的默认 launch.json
模板(截至 C# 扩展 v1.20.0)使用以下配置来在 ASP.NET 启动时让 VS Code 启动 Web 浏览器
"serverReadyAction": {
"action": "openExternally",
"pattern": "\\bNow listening on:\\s+(https?://\\S+)"
}
关于此的注意事项
-
如果你不希望浏览器自动启动,你可以直接删除此元素(如果你的
launch.json
中有launchBrowser
元素,也可以删除它)。 -
此模式使用 ASP.NET Core 写入控制台的 URL 启动 Web 浏览器。如果你想修改 URL,请参阅指定浏览器的 URL。如果目标应用程序在另一台机器或容器上运行,或者
applicationUrl
具有特殊主机名(例如:"applicationUrl": "http://*:1234/"
),这可能很有用。 -
serverReadyAction
是 VS Code 的一项新功能。相比 C# 扩展调试器中内置的旧版launchBrowser
功能,它更受推荐,因为它可以在 C# 扩展在远程机器上运行时工作,它使用为 VS Code 配置的默认浏览器,并且还允许使用脚本调试器。如果这些功能对你都不重要,你可以继续使用launchBrowser
。如果你想运行特定程序而不是启动默认浏览器,也可以继续使用launchBrowser
。 -
有关
serverReadyAction
的更多文档可在 Visual Studio Code 2019 年 2 月发布说明中找到。 -
其工作原理是 VS Code 抓取输出到控制台的内容。如果某行匹配模式,它将针对模式“捕获”到的 URL 启动浏览器。
以下是模式作用的解释
\\b
: 匹配单词边界。请注意\b
表示单词边界,但由于它在 JSON 字符串中,\
需要转义,因此为\\b
。Now listening on:
: 这是一个字符串字面量,意味着下一个文本必须是Now listening on:
。\\s+
: 匹配一个或多个空格字符。(
: 这是“捕获组”的开始。它指示要保存并用于启动浏览器的文本区域。http
: 字符串字面量。s?
: 字符s
或无。://
: 字符串字面量。\\S+
: 一个或多个非空白字符。)
: 捕获组的结束。
-
两种形式的浏览器启动都需要
"console": "internalConsole"
,因为浏览器启动器会抓取目标进程的标准输出,以了解 Web 服务器何时完成了初始化。
指定浏览器的 URL
如果你想忽略控制台输出中的 URL,你可以从模式中删除 (
和 )
,并将 uriFormat
设置为你想要启动的 URL。
示例
"serverReadyAction": {
"action": "openExternally",
"pattern": "\\bNow listening on:\\s+https?://\\S",
"uriFormat": "http://localhost:1234"
}
如果你想使用控制台输出中的端口号,但不是主机名,你也可以使用类似这样的内容
"serverReadyAction": {
"action": "openExternally",
"pattern": "\\bNow listening on:\\s+http://\\S+:([0-9]+)",
"uriFormat": "http://localhost:%s"
}
实际上,你几乎可以打开任何 URL,例如你可以通过以下方式打开默认的 swagger ui
"serverReadyAction": {
"action": "openExternally",
"pattern": "\\bNow listening on:\\s+http://\\S+:([0-9]+)",
"uriFormat": "http://localhost:%s/swagger/index.html"
}
注意 你需要确保你的项目已设置 swaggerui 才能执行此操作。
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 带有launchBrowser
和applicationUrl
环境变量
可以使用此架构将环境变量传递给你的程序
"env": {
"myVariableName":"theValueGoesHere"
}
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 作为environmentVariables
控制台(终端)窗口
"console"
设置控制目标应用程序在哪种控制台(终端)窗口中启动。它可以设置为以下任何值 --
"internalConsole"
(默认):目标进程的控制台输入(stdin)和输出(stdout/stderr)通过 VS Code 调试控制台路由。此模式的优点是,它允许你在一个地方看到来自调试器和目标程序的消息,因此你不会错过重要消息或需要来回切换。这对于具有简单控制台交互的程序很有用(例如:使用Console.WriteLine
和/或Console.ReadLine
)。当目标程序需要完全控制控制台时,例如更改光标位置、使用Console.ReadKey
进行输入等的程序,不应使用此模式。有关向控制台输入内容的说明,请参阅下文。"integratedTerminal"
:目标进程将在 VS Code 的集成终端中运行。在编辑器下方的选项卡组中选择终端选项卡与你的应用程序交互。使用此模式时,默认情况下,启动调试时不会显示调试控制台。如果使用launch.json
,这可以通过internalConsoleOptions
进行配置。"externalTerminal"
:目标进程将在其自己的外部终端中运行。使用此模式时,你需要在 Visual Studio Code 和外部终端窗口之间切换焦点。
可用性
launch.json
✔️settings.json
✔️ 作为csharp.debug.console
launchSettings.json
❌
注意:
csharp.debug.console
设置仅用于通过dotnet
调试配置类型启动的控制台项目。
使用 internalConsole 时向目标进程输入文本
使用 internalConsole
时,你可以在 Visual Studio Code 中输入文本,这些文本将从 Console.ReadLine
和其他从 stdin
读取的类似 API 返回。为此,在程序运行时,将文本输入到调试控制台底部的输入框中。按 Enter 键会将文本发送到目标进程。请注意,如果在程序在调试器下停止时在此框中输入文本,此文本将被评估为 C# 表达式,而不是发送到目标进程。
示例
launchSettingsProfile
和 launchSettingsFilePath
虽然 launchSettings.json
的完全支持需要使用带有 "type": "dotnet"
的启动配置,但 coreclr
和 clr
调试器类型也支持 launchSettings.json
功能的有限子集。这对于希望在 Visual Studio Code 和完整的 Visual Studio 中使用相同设置的用户很有用。
要配置要使用的 launchSettings.json
配置文件(或阻止使用它),请设置 launchSettingsProfile
选项
"launchSettingsProfile": "ProfileNameGoesHere"
例如,这将使用此 launchSettings.json
示例文件中的 myVariableName
{
"profiles": {
"ProfileNameGoesHere": {
"commandName": "Project",
"environmentVariables": {
"myVariableName": "theValueGoesHere"
}
}
}
}
如果未指定 launchSettingsProfile
,将使用第一个带有 "commandName": "Project"
的配置文件。
如果 launchSettingsProfile
设置为 null/空字符串,则 Properties/launchSettings.json
将被忽略。
默认情况下,调试器将在 {cwd}/Properties/launchSettings.json
中搜索 launchSettings.json
。要自定义此路径,请设置 launchSettingsFilePath
"launchSettingsFilePath": "${workspaceFolder}/<Relative-Path-To-Project-Directory/Properties/launchSettings.json"
限制
- 仅支持具有
"commandName": "Project"
的配置文件。 - 仅支持
environmentVariables
、applicationUrl
和commandLineArgs
属性 launch.json
中的设置将优先于launchSettings.json
中的设置,因此例如,如果launch.json
中的args
已设置为非空字符串/数组,则launchSettings.json
的内容将被忽略。
可用性
launch.json
✔️settings.json
❌launchSettings.json
❌
源文件映射
你可以选择通过提供一个使用此形式的映射来配置如何打开源文件
"sourceFileMap": {
"C:\\foo":"/home/me/foo"
}
在此示例中
C:\foo
是编译模块(例如:MyCode.dll)时一个或多个源文件(例如:program.cs
)的原始位置。它可以是包含源文件的目录,也可以是源文件的完整路径(例如:c:\foo\program.cs
)。它不需要存在于运行 Visual Studio Code 的计算机上,或者如果你正在远程调试,也不需要在远程机器上。调试器从.pdb
(符号)文件中读取源文件的路径,并使用此映射转换路径。/home/me/foo
是 Visual Studio Code 现在可以找到源文件的路径。
可用性
launch.json
✔️settings.json
✔️ 作为csharp.debug.sourceFileMap
launchSettings.json
❌
仅我的代码
你可以选择通过将 justMyCode
设置为 "false" 来禁用它。当你尝试调试一个没有符号或已优化的库时,你应该禁用“仅我的代码”。
"justMyCode":false
“仅我的代码”是一组功能,通过隐藏你可能正在使用的优化库(如 .NET Framework 本身)的一些细节,使你更容易专注于调试你的代码。此功能最重要的子部分是 --
- 用户未处理的异常:在异常即将被框架捕获之前,自动停止调试器
- 仅我的代码单步执行:在单步执行时,如果框架代码回调到用户代码,则自动停止。
可用性
launch.json
✔️settings.json
✔️ 作为csharp.debug.justMyCode
launchSettings.json
❌
需要完全匹配的源
调试器要求 PDB 和源代码完全相同。要更改此设置并禁用源代码相同,请添加
"requireExactSource": false
可用性
launch.json
✔️settings.json
✔️ 作为csharp.debug.requireExactSource
launchSettings.json
❌
单步进入属性和运算符
调试器默认情况下会跳过托管代码中的属性和运算符。在大多数情况下,这提供了更好的调试体验。要更改此设置并启用单步进入属性或运算符,请添加
"enableStepFiltering": false
可用性
launch.json
✔️settings.json
✔️ 作为csharp.debug.enableStepFiltering
launchSettings.json
❌
日志记录
你可以选择启用或禁用应记录到输出窗口的消息。日志字段中的标志是:'exceptions'、'moduleLoad'、'programOutput'、'browserStdOut' 和 'consoleUsageMessage'。
在 'logging.diagnosticsLog' 下还有高级选项,用于诊断调试器的问题。
可用性
launch.json
✔️settings.json
✔️ 在csharp.debug.logging
下launchSettings.json
❌
PipeTransport
如果你需要调试器使用另一个可执行文件连接到远程计算机,以在 VS Code 和 .NET Core 调试器后端 (vsdbg) 之间中继标准输入和输出,那么请按照此架构添加 pipeTransport 字段
"pipeTransport": {
"pipeProgram": "ssh",
"pipeArgs": [ "-T", "ExampleAccount@ExampleTargetComputer" ],
"debuggerPath": "~/vsdbg/vsdbg",
"pipeCwd": "${workspaceFolder}",
"quoteArgs": true
}
有关管道传输的更多信息可以在此处找到。
你可以在此处找到有关为 Linux 的 Windows 子系统 (WSL) 配置管道传输的信息,以及此处。
可用性
launch.json
✔️settings.json
❌launchSettings.json
❌
操作系统特定配置
如果需要针对每个操作系统更改特定命令,你可以使用字段:'windows'、'osx' 或 'linux'。你可以替换上述任何字段以适应特定操作系统。
禁止 JIT 优化
.NET 调试器支持以下选项。如果为 true,当目标进程中加载优化模块(在 Release 配置中编译的 .dll)时,调试器将要求即时 (Just-In-Time) 编译器生成禁用优化功能的代码。该选项默认为 false。
"suppressJITOptimizations": true
.NET 中优化工作原理:如果你正在尝试调试代码,当代码未优化时会更容易。这是因为当代码被优化时,编译器和运行时会对发出的 CPU 代码进行更改,使其运行更快,但与原始源代码的映射不那么直接。这意味着调试器通常无法告诉你局部变量的值,并且代码单步执行和断点可能无法按你预期的方式工作。
通常,Release 构建配置会创建优化代码,而 Debug 构建配置则不会。Optimize
MSBuild 属性控制是否告知编译器优化代码。
在 .NET 生态系统中,代码通过两步过程从源代码转换为 CPU 指令:首先,C# 编译器将你输入的文本转换为称为 MSIL 的中间二进制形式,并将其写入 .dll 文件。随后,.NET 运行时将此 MSIL 转换为 CPU 指令。这两个步骤都可以在一定程度上进行优化,但 .NET 运行时执行的第二步执行了更重要的优化。
此选项的作用:此选项控制当在目标进程中加载已启用优化编译的 DLL 时发生什么。如果此选项为 false(默认值),则当 .NET 运行时将 MSIL 代码编译为 CPU 代码时,它会保持优化启用。如果此选项为 true,则调试器会请求禁用优化。
何时使用此选项:当你从其他来源(例如 nuget 包)下载了 DLL,并且想要调试此 DLL 中的代码时,应使用此选项。为了使其正常工作,你还必须找到此 DLL 的符号 (.pdb) 文件。
如果你只对调试本地构建的代码感兴趣,最好将此选项保持为 false,因为在某些情况下,启用此选项会显著减慢调试速度。导致这种减速有两个原因 --
- 优化后的代码运行速度更快。如果你关闭了许多代码的优化,时间开销可能会增加。
- 如果启用了“仅我的代码”,调试器甚至不会尝试加载已优化 DLL 的符号。查找符号可能需要很长时间。
此选项的限制:在两种情况下,此选项将无法工作
1:在你将调试器附加到已运行的进程的情况下,此选项对在调试器附加时已加载的模块没有影响。
2:此选项对已预编译 (ngen) 为本机代码的 DLL 没有影响。但是,你可以通过将环境变量 COMPlus_ReadyToRun
设置为 0
来启动进程,从而禁用预编译代码的使用。如果你面向旧版 .NET Core (2.x),还要将 COMPlus_ZapDisable
设置为 '1'。如果你在调试器下启动,可以通过将此设置添加到 launch.json
来进行配置
"env": {
"COMPlus_ZapDisable": "1",
"COMPlus_ReadyToRun": "0"
}
可用性
launch.json
✔️settings.json
✔️ 作为csharp.debug.suppressJITOptimizations
launchSettings.json
❌
符号选项
symbolOptions
元素允许自定义调试器如何搜索符号。示例
"symbolOptions": {
"searchPaths": [
"~/src/MyOtherProject/bin/debug",
"https://my-companies-symbols-server"
],
"searchMicrosoftSymbolServer": true,
"searchNuGetOrgSymbolServer": true,
"cachePath": "/symcache",
"moduleFilter": {
"mode": "loadAllButExcluded",
"excludedModules": [ "DoNotLookForThisOne*.dll" ]
}
}
属性
searchPaths: 符号服务器 URL(例如:https://msdl.microsoft.com/download/symbols
)或目录(例如:/build/symbols)的数组,用于搜索 .pdb
文件。除了默认位置、模块旁边和 .pdb
最初放置的路径外,还将搜索这些目录。
searchMicrosoftSymbolServer: 如果为 true
,则 Microsoft 符号服务器 (https://msdl.microsoft.com/download/symbols) 将添加到符号搜索路径。如果未指定,此选项默认为 false
。
searchNuGetOrgSymbolServer: 如果为 true
,则 Nuget.org 符号服务器 (https://symbols.nuget.org/download/symbols) 将添加到符号搜索路径。如果未指定,此选项默认为 false
。
cachePath": 从符号服务器下载的符号应缓存的目录。如果未指定,在 Windows 上调试器默认为 %TEMP%\\SymbolCache
,在 Linux 和 macOS 上调试器默认为 ~/.dotnet/symbolcache
。
moduleFilter.mode: 此值为 "loadAllButExcluded"
或 "loadOnlyIncluded"
。在 "loadAllButExcluded"
模式下,调试器会为所有模块加载符号,除非该模块在 'excludedModules' 数组中。在 "loadOnlyIncluded"
模式下,调试器不会尝试为任何模块加载符号,除非它在 'includedModules' 数组中,或者通过 'includeSymbolsNextToModules' 设置包含。
loadAllButExcluded 模式的属性
moduleFilter.excludedModules: 调试器不应加载符号的模块数组。支持通配符(例如:MyCompany.*.dll)。
loadOnlyIncluded 模式的属性
moduleFilter.includedModules: 调试器应加载符号的模块数组。支持通配符(例如:MyCompany.*.dll)。
moduleFilter.includeSymbolsNextToModules: 如果为 true,对于不在 'includedModules' 数组中的任何模块,调试器仍将检查模块本身和启动可执行文件旁边,但不会检查符号搜索列表上的路径。此选项默认为 'true'。
可用性
launch.json
✔️settings.json
✔️ 在csharp.debug.symbolOptions
下launchSettings.json
❌
源链接选项
源链接 (Source Link) 是一项功能,当你调试在另一台计算机上构建的代码(例如来自 nuget 包的代码)时,它使调试器能够通过从 Web 下载来自动显示匹配的源代码。为了实现这一点,你正在调试的代码的 .pdb 文件包含将 DLL 中的源文件映射到调试器可以下载的 URL 的数据。有关源链接的更多信息可以在 https://aka.ms/SourceLinkSpec 找到。
launch.json
中的 sourceLinkOptions
元素允许按 URL 自定义源链接行为。它是一个从 URL 到该 URL 的源链接选项的映射。URL 名称中支持通配符。目前唯一的自定义是该 URL 是否启用了源链接,但未来可能会添加更多选项。
示例
"sourceLinkOptions": {
"https://raw.githubusercontent.com/*": { "enabled": true },
"*": { "enabled": false }
}
此示例为 GitHub URL 启用源链接,并为所有其他 URL 禁用源链接。
此选项的默认值是为所有 URL 启用源链接。同样,对于在 sourceLinkOptions
映射中没有规则的任何 URL,也会启用源链接。
要禁用所有 URL 的源链接,请使用 "sourceLinkOptions": { "*": { "enabled": false } }
。
如果多个条目覆盖同一 URL,则使用更具体的条目(字符串长度更长的条目)。
目前,源链接仅适用于无需身份验证即可访问的源文件。因此,例如,调试器可以从 GitHub 上的开源项目下载源文件,但无法从私有 GitHub 仓库或 Visual Studio Team Services 下载。
可用性
launch.json
✔️settings.json
❌launchSettings.json
❌
目标架构选项 (macOS M1)
Apple M1 上的 .NET 同时支持 x86_64 和 ARM64。调试时,调试器附加到的进程的架构必须与调试器匹配。如果它们不匹配,可能会导致 Unknown Error: 0x80131c3c
。
扩展会尝试根据 PATH 中 dotnet --info
的输出解析 targetArchitecture
,否则它会尝试使用与 VS Code 相同的架构。
你可以通过在 launch.json
中设置 targetArchitecture
来覆盖此行为。
示例
"targetArchitecture": "arm64"
可用性
launch.json
✔️settings.json
❌launchSettings.json
❌
检查开发证书
此选项控制在启动时,调试器是否应检查计算机是否具有用于开发在 HTTPS 端点上运行的 Web 项目的自签名 HTTPS 证书。为此,它会尝试运行 dotnet dev-certs https --check --trust
,如果未找到证书,它将提示用户建议创建一个。如果用户批准,扩展将运行 dotnet dev-certs https --trust
来创建受信任的自签名证书。
如果未指定,当设置了 serverReadyAction
时,此选项默认为 true。此选项在 Linux、VS Code 远程和 VS Code 网页版场景中不起作用。
你可以通过在 launch.json
中将 checkForDevCert
设置为 false 来覆盖此行为。
示例
"checkForDevCert": "false"
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 作为useSSL