调试

你可以使用 Microsoft C# 扩展在 Visual Studio Code 中调试 C# 应用程序。

运行和调试

C# 扩展与 C# Dev Kit 一起，提供了多种方式来运行和调试你的 C# 应用程序。

要在没有 C# Dev Kit 的情况下运行和调试，请参阅 Microsoft C# 扩展的 GitHub 页面上的文档。

使用 F5 调试

在安装了 C# Dev Kit 扩展且“调试”视图中没有可选择的调试配置时，你可以通过打开一个 .cs 文件然后按 F5 来开始调试你的项目。调试器会自动找到你的项目并开始调试。如果你有多个项目，它会提示你选择要开始调试的项目。

你还可以从 VS Code 侧边栏的运行和调试视图开始调试会话。更多信息请参阅 在 VS Code 中调试。

使用解决方案资源管理器调试

安装了 C# Dev Kit 扩展后，当你在解决方案资源管理器中右键单击你的项目时，会出现一个调试上下文菜单。

有三个选项

• 启动新实例 - 这会启动你的项目并附加一个调试器。
• 在不调试的情况下启动 - 这会运行你的项目但不附加调试器。
• 单步执行到新实例 - 这会启动你的项目并附加一个调试器，但在代码的入口点处停止。

使用命令面板调试

安装了 C# Dev Kit 扩展后，你还可以通过使用调试: 选择并开始调试命令，从命令面板 ⇧⌘P (Windows, Linux Ctrl+Shift+P) 开始调试。

注意：这会在你的调试下拉列表中添加一个启动配置条目。

使用动态（内存中）启动配置进行调试

安装了 C# Dev Kit 扩展后，你可以创建动态启动配置。创建它们的方式取决于你的项目是否有一个现有的 launch.json 文件。

现有的 launch.json

如果你有一个现有的 launch.json，你可以转到“调试”视图，选择下拉菜单，然后选择 C# 选项。这应该会给你一个启动目标的选择，你可以将它们添加到你的下拉列表中。选择后，你可以按 F5 或使用新生成的配置点击开始调试。

没有 launch.json

如果你的项目中没有 launch.json，你可以在“调试”视图的显示所有自动调试配置中添加和访问这些动态配置。

移除动态（内存中）启动配置

你可以使用命令面板 ⇧⌘P (Windows, Linux Ctrl+Shift+P) 并使用命令调试: 选择并开始调试来移除生成的配置。

在下拉列表中，它会列出你所有现有的调试配置。如果你将鼠标悬停在动态配置上，右侧会出现一个可点击的垃圾桶图标。你可以选择该图标来移除动态配置。

使用编辑器调试/运行按钮进行调试

当编辑器中打开一个 .cs 文件时，可以通过位于编辑器窗口右上角的按钮来访问运行和调试选项。这些操作将使用当前文件查询项目系统，并确定要启动的关联项目。

两个选项是

• 运行与此文件关联的项目：这将使用调试适配器以 noDebug: true 模式启动你的程序。
• 调试与此文件关联的项目：这将在调试器下启动你的程序。

使用 launch.json 调试

如果你正在使用 C# Dev Kit，我们建议不要使用此选项。但是，如果你需要直接修改调试配置，请参阅为 C# 调试配置 launch.json。

附加到进程

你可以使用命令面板 ⇧⌘P (Windows, Linux Ctrl+Shift+P) 并运行调试: 附加到 .NET 5+ 或 .NET Core 进程命令来附加到 C# 进程。

配置选项

有许多选项和设置可用于配置调试器。你可以使用 launchSettings.json、VS Code 用户设置来修改你的调试选项，或者直接修改你的 launch.json。

launchSettings.json

如果你有来自 Visual Studio 的 launchSettings.json，你应该会看到你的配置文件在使用F5 运行或从命令面板运行时列出。

更多详情请参考配置 C# 调试。

用户设置

如果你希望在使用 C# 调试器时更改设置，可以在 文件 > 首选项 > 设置 (⌘, (Windows, Linux Ctrl+,)) 下找到这些选项，并搜索它们。

• csharp.debug.stopAtEntry - 如果为 true，调试器应在目标的入口点停止。此选项默认为 false。
• csharp.debug.console - 启动控制台项目时，指示目标程序应在哪个控制台中启动。注意：此选项仅用于 'dotnet' 调试配置类型。
  • internalConsole [默认] - VS Code 的调试控制台。此模式允许你在一个地方看到来自调试器和目标程序的消息。更多详情请参考完整文档。
  • integratedTerminal - VS Code 的集成终端。
  • externalTerminal - 可通过用户设置配置的外部终端。
• csharp.debug.sourceFileMap - 将构建时路径映射到本地源位置。所有构建时路径的实例都将被本地源路径替换。
    示例
      {\"<构建时路径>\":\"<本地源路径>\"}
• csharp.debug.justMyCode - 启用时（默认），调试器仅显示和单步进入用户代码（“我的代码”），忽略系统代码和其他经过优化或没有调试符号的代码。更多信息。
• csharp.debug.requireExactSource - 要求当前源代码与 pdb 匹配的标志。此选项默认为 true。
• csharp.debug.enableStepFiltering - 启用跳过属性和运算符的标志。此选项默认为 true。
• csharp.debug.logging.exceptions - 确定是否应将异常消息记录到输出窗口的标志。此选项默认为 true。
• csharp.debug.logging.moduleLoad - 确定是否应将模块加载事件记录到输出窗口的标志。此选项默认为 true。
• csharp.debug.logging.programOutput - 确定在不使用外部控制台时是否应将程序输出记录到输出窗口的标志。此选项默认为 true。
• csharp.debug.logging.diagnosticsLog - 用于诊断调试器问题的各种设置。
• csharp.debug.logging.browserStdOut - 确定是否应将启动 Web 浏览器时的 stdout 文本记录到输出窗口的标志。此选项默认为 true。
• csharp.debug.logging.elapsedTiming - 如果为 true，引擎日志记录将包括 adapterElapsedTime 和 engineElapsedTime 属性，以指示请求所花费的时间（以微秒为单位）。此选项默认为 false。
• csharp.debug.logging.threadExit - 控制当目标进程中的线程退出时是否记录消息。此选项默认为 false。
• csharp.debug.logging.processExit - 控制当目标进程退出或调试停止时是否记录消息。此选项默认为 true。
• csharp.debug.suppressJITOptimizations - 如果为 true，当优化的模块（在 Release 配置中编译的 .dll）加载到目标进程中时，调试器会要求即时（Just-In-Time）编译器生成禁用优化的代码。更多信息
• csharp.debug.symbolOptions.searchPaths - 用于搜索 .pdb 文件的符号服务器 URL（例如：http://MyExampleSymbolServer）或目录（例如：/build/symbols）的数组。除了模块旁边的默认位置和 pdb 最初放置的路径之外，还会搜索这些目录。
• csharp.debug.symbolOptions.searchMicrosoftSymbolServer - 如果为 true，Microsoft 符号服务器 (https://msdl.microsoft.com/download/symbols) 将被添加到符号搜索路径中。如果未指定，此选项默认为 false。
• csharp.debug.symbolOptions.searchNuGetOrgSymbolServer - 如果为 true，NuGet.org 符号服务器 (https://symbols.nuget.org/download/symbols) 将被添加到符号搜索路径中。如果未指定，此选项默认为 false。
• csharp.debug.symbolOptions.cachePath - 从符号服务器下载的符号应缓存的目录。如果未指定，在 Windows 上，调试器默认为 %TEMP%\\SymbolCache，在 Linux 和 macOS 上，调试器默认为 ~/.dotnet/symbolcache。
• csharp.debug.symbolOptions.moduleFilter.mode - 控制模块筛选器运行的两种基本操作模式之一。
  • loadAllButExcluded - 加载所有模块的符号，除非该模块在 excludedModules 数组中。
  • loadOnlyIncluded - 不尝试加载任何模块的符号，除非它在 includedModules 数组中，或者通过 includeSymbolsNextToModules 设置包含它。
• csharp.debug.symbolOptions.moduleFilter.excludedModules - 调试器不应加载符号的模块数组。支持通配符（例如：MyCompany.*.dll）。除非 mode 设置为 loadAllButExcluded，否则此属性将被忽略。
• csharp.debug.symbolOptions.moduleFilter.includedModules - 调试器应加载符号的模块数组。支持通配符（例如：MyCompany.*.dll）。除非 mode 设置为 loadOnlyIncluded，否则此属性将被忽略。
• csharp.debug.symbolOptions.moduleFilter.includeSymbolsNextToModules - 如果为 true，对于不在 includedModules 数组中的任何模块，调试器仍会检查模块本身和启动可执行文件旁边，但不会检查符号搜索列表中的路径。此选项默认为 true。除非 mode 设置为 loadOnlyIncluded，否则此属性将被忽略。
• csharp.debug.allowFastEvaluate - 当为 true 时（默认状态），调试器将通过模拟执行简单属性和方法来尝试更快的求值。
• csharp.experimental.debug.hotReload - 当为 true 时，如果目标应用程序支持热重载，调试器将启用在调试时应用更改。
• csharp.debug.hotReloadOnSave - 当为 true 时（默认状态），调试器将在文件保存时自动应用代码更改。
• csharp.debug.hotReloadVerbosity - 控制 C# 热重载输出窗口的日志记录详细程度。它可以设置为 minimal（默认）、detailed 或 diagnostic。如果热重载开始出现意外行为，建议提高详细程度级别。

Breakpoints

C# 调试器支持各种断点，例如源代码行断点、条件断点和日志点。

断点 - 条件断点

借助表达式求值，调试器还支持条件断点。你可以设置断点在表达式求值为 true 时中断。

断点 - 函数断点

调试器还支持函数断点。你可以通过在“调试”窗格的“断点”部分单击 + 来设置断点以在特定函数上中断。

断点 - 日志点

日志点（在 Visual Studio 中也称为跟踪点）允许你向调试控制台发送输出而无需编辑代码。它们与断点不同，因为它们不会停止应用程序的执行流。

要添加日志点，请在代码行旁边的最左侧边距中右键单击。选择添加日志点并键入你想要记录的消息。当命中日志点时，将对花括号（'{' 和 '}'）之间的任何表达式进行求值。

日志消息中还支持以下令牌

断点 - 触发断点

触发断点是一种在另一个断点命中后自动启用的断点。当代码中出现仅在特定先决条件发生后才出现的故障情况时，它们非常有用。

可以通过右键单击字形边距，选择 添加触发断点，然后选择哪个其他断点启用此断点来设置触发断点。

在异常处停止

C# 调试器支持配置选项，用于在抛出或捕获异常时调试器停止。这是通过运行视图的断点部分中的两个不同条目完成的

请注意，断点部分将缺少这些条目，直到该文件夹首次使用 C# 调试器进行调试。

选中所有异常将配置调试器在抛出异常时停止。如果启用了仅我的代码（默认启用），则如果异常在库代码中内部抛出并捕获，调试器将不会中断。但是，如果异常在库代码中抛出并返回到用户代码，调试器将中断。

选中用户未处理的异常将配置调试器在用户代码中抛出或经过用户代码后，异常在非用户代码中被捕获时停止。成为用户未处理的异常并不总是被调试进程中的错误——可能是用户代码正在实现一个 API，并且预期会引发异常。在许多情况下，确实存在问题，因此，默认情况下，当异常成为用户未处理时，调试器会停止。

异常条件

两个复选框都支持条件，以便仅在选定的异常类型上中断。要编辑条件，请选择铅笔图标（见上图）或右键单击条目并调用编辑条件。该条件是一个逗号分隔的异常类型列表，用于中断，或者如果列表以 '!' 开头，则是一个要忽略的异常类型列表。

条件示例

Expression evaluation

调试器还允许你在监视窗口以及调试控制台中求值表达式。

热重载

安装了 C# Dev Kit 扩展后，调试器允许你在调试时应用 C# 代码更改。

为了启用热重载，必须将 csharp.experimental.debug.hotReload 设置为 true，更多信息请参阅用户设置。热重载会话仅在目标调试器引擎支持应用代码更改时才会启动。

支持的项目和场景

C# Dev Kit 支持“经典”热重载体验，也称为“编辑并继续”。无论你是在断点处停止还是程序正在运行，都可以在调试时应用代码更改。

截至 2023 年 11 月，某些功能（例如 MetadataUpdateHandler，它使 ASP.NET Core 应用程序能够在做出更改后自动刷新浏览器）尚不可用。还不支持在不调试的情况下应用代码更改。

运行时在 .NET 8 中添加了对在 Linux/macOS 上调试时应用更改的支持，因此在为在这些操作系统上运行的 .NET 应用应用代码更改时，需要 .NET 8+ 的运行时版本。

有关 C# Dev Kit 当前支持的项目的更多信息，请参阅支持的项目。另请参阅 C# Dev Kit 常见问题解答，了解有关排查其他不支持场景的更多信息。

如何应用代码更改

一旦热重载会话开始并做出新的更改，你可以通过以下任何操作将这些更改应用到你的应用程序中

后续步骤

继续阅读以了解：

• 调试 - 了解如何在 VS Code 中为任何语言的项目使用调试器。