配置 C# 调试
您可以使用 launch.json
、launchSettings.json
或您的用户 settings.json
文件在 Visual Studio Code 中配置 C# 调试器。
以下是您可能需要在调试时更改的常见选项。
配置 VS Code 的调试行为
PreLaunchTask
preLaunchTask
字段会在调试程序之前运行 tasks.json
中的关联 taskName。您可以通过从 VS Code 命令面板执行命令“任务: 配置任务运行器”来获取默认的生成预启动任务。
这将创建一个运行 dotnet build
的任务。您可以在 VS Code 任务文档中阅读更多内容。
可用性
launch.json
✔️settings.json
❌launchSettings.json
❌
程序
program 字段设置为要启动的应用程序 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 开始)使用以下内容来配置 VS Code 在 ASP.NET 启动时启动 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
设置为您想要启动的内容。
示例
"serverReadyAction": {
"action": "openExternally",
"pattern": "\\bNow listening on:\\s+https?://\\S",
"uriFormat": "https://127.0.0.1:1234"
}
如果您想使用控制台输出中的端口号,但不使用主机名,您也可以使用类似这样的内容
"serverReadyAction": {
"action": "openExternally",
"pattern": "\\bNow listening on:\\s+http://\\S+:([0-9]+)",
"uriFormat": "https://127.0.0.1:%s"
}
实际上,您可以打开几乎任何 URL,例如,您可以通过执行以下操作来打开默认的 swagger ui
"serverReadyAction": {
"action": "openExternally",
"pattern": "\\bNow listening on:\\s+http://\\S+:([0-9]+)",
"uriFormat": "https://127.0.0.1:%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 和外部终端窗口之间切换焦点。
使用 internalConsole 时向目标进程输入文本
使用 internalConsole
时,你可以向 Visual Studio Code 输入文本,这些文本将从 Console.ReadLine
和类似的从 stdin
读取的 API 返回。为此,在程序运行时,在调试控制台底部的输入框中键入文本。按 Enter 将文本发送到目标进程。请注意,如果在程序在调试器下停止时在此框中输入文本,则此文本将被评估为 C# 表达式,而不是发送到目标进程。
示例
可用性
launch.json
✔️settings.json
✔️ 作为csharp.debug.console
launchSettings.json
❌
launchSettings.json 支持
除了 launch.json
之外,还可以通过 launchSettings.json
文件配置启动选项。launchSettings.json
的优点在于,它允许在 Visual Studio Code、完整 Visual Studio 和 dotnet run
之间共享设置。
要配置要使用的 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
中的设置,例如,如果args
在launch.json
中已设置为非空字符串/数组,则将忽略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
❌
仅我的代码
你可以选择通过将其设置为 "false" 来禁用 justMyCode
。当你尝试调试已拉取的没有符号或已优化的库时,应禁用“仅我的代码”。
"justMyCode":false
“仅我的代码”是一组功能,它通过隐藏你可能正在使用的优化库(如 .NET 框架本身)的一些细节,使你可以更轻松地专注于调试你的代码。此功能最重要的子部分是 --
- 用户未处理的异常:在异常即将被框架捕获之前自动停止调试器
- “仅我的代码”单步执行:在单步执行时,如果框架代码回调到用户代码,则自动停止。
可用性
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
}
有关管道传输的更多信息,请参见此处。
你可以在此处找到有关为 Windows Subsystem for Linux (WSL) 配置管道传输的信息。
可用性
launch.json
✔️settings.json
❌launchSettings.json
❌
操作系统特定配置
如果需要针对每个操作系统更改特定命令,则可以使用以下字段:“windows”、“osx”或“linux”。你可以替换上述任何字段以针对特定操作系统。
禁止 JIT 优化
.NET 调试器支持以下选项。如果为 true,则当在目标进程中加载优化的模块(在 Release 配置中编译的 .dll)时,调试器将请求即时编译器生成禁用优化的代码。该选项默认为 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'ed) 为本机代码的 dll 没有影响。但是,你可以通过使用设置为 0
的环境变量 COMPlus_ReadyToRun
启动进程来禁用预编译代码的使用。如果你的目标是较旧版本的 .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:用于搜索 .pdb
文件的符号服务器 URL(例如:https://msdl.microsoft.com/download/symbols
)或目录(例如:/build/symbols)的数组。除了默认位置之外,还将在模块旁边和最初放置 .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 的数据。有关 Source Link 的更多信息,请访问 https://aka.ms/SourceLinkSpec。
launch.json
中的 sourceLinkOptions
元素允许按 URL 自定义 Source Link 的行为。它是从 URL 到该 URL 的 Source Link 选项的映射。URL 名称支持通配符。目前唯一的自定义选项是是否为该 URL 启用 Source Link,但将来可能会添加更多选项。
示例
"sourceLinkOptions": {
"https://raw.githubusercontent.com/*": { "enabled": true },
"*": { "enabled": false }
}
此示例为 GitHub URL 启用 Source Link,并禁用所有其他 URL 的 Source Link。
此选项的默认值是为所有 URL 启用 Source Link。类似地,对于 sourceLinkOptions
映射中没有规则的任何 URL,也会启用 Source Link。
要禁用所有 URL 的 Source Link,请使用 "sourceLinkOptions": { "*": { "enabled": false } }
。
如果多个条目涵盖同一个 URL,则使用更具体的条目(字符串长度更长的条目)。
目前,Source Link 仅适用于无需身份验证即可访问的源文件。因此,例如,调试器可以从 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
❌
检查 DevCert
此选项控制在启动时,调试器是否应检查计算机是否具有用于开发在 https 终结点上运行的 Web 项目的自签名 HTTPS 证书。为此,它会尝试运行 dotnet dev-certs https --check --trust
,如果未找到证书,它将提示用户建议创建一个证书。如果用户批准,扩展程序会运行 dotnet dev-certs https --trust
来创建受信任的自签名证书。
如果未指定,则当设置 serverReadyAction
时,默认为 true。此选项在 Linux、VS Code 远程和 VS Code for Web 方案中不起作用。
您可以通过在 launch.json
中将 checkForDevCert
设置为 false 来覆盖此行为。
示例
"checkForDevCert": "false"
可用性
launch.json
✔️settings.json
❌launchSettings.json
✔️ 作为useSSL
配置 launchSettings.json
使用 C# Dev Kit,您可以将 Visual Studio 中的 launchSettings.json
引入以与 Visual Studio Code 一起使用
示例
{
"iisSettings": {
"windowsAuthentication": false,
"anonymousAuthentication": true,
"iisExpress": {
"applicationUrl": "https://127.0.0.1:59481",
"sslPort": 44308
}
},
"profiles": {
"EnvironmentsSample": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://127.0.0.1:7152;https://127.0.0.1:5105",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},
"EnvironmentsSample-Staging": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://127.0.0.1:7152;https://127.0.0.1:5105",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Staging",
"ASPNETCORE_DETAILEDERRORS": "1",
"ASPNETCORE_SHUTDOWNTIMEOUTSECONDS": "3"
}
},
"EnvironmentsSample-Production": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": true,
"applicationUrl": "https://127.0.0.1:7152;https://127.0.0.1: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 端口。