现已推出!阅读有关 11 月的新功能和修复的信息。

配置 C# 调试

您可以使用 launch.jsonlaunchSettings.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+)"
    }

关于此的一些说明

  1. 如果您希望浏览器自动启动,您可以直接删除此元素(以及如果您的 launch.json 中有 launchBrowser 元素)。

  2. 此模式使用 ASP.NET Core 写入控制台的 URL 启动 Web 浏览器。如果您想修改 URL,请参阅指定浏览器的 URL。如果目标应用程序在另一台计算机或容器上运行,或者 applicationUrl 具有特殊的主机名(示例:"applicationUrl": "http://*:1234/"),这可能很有用。

  3. serverReadyAction 是 VS Code 的一项新功能。建议使用它来替代 C# 扩展调试器中内置的先前 launchBrowser 功能,因为它可以在 C# 扩展在远程计算机上运行时工作,它使用为 VS Code 配置的默认浏览器,并且它还允许使用脚本调试器。如果您不需要这些功能,您可以继续使用 launchBrowser。如果您想运行特定程序而不是启动默认浏览器,您也可以继续使用 launchBrowser

  4. 有关 serverReadyAction 的更多文档,请参阅Visual Studio Code 2019 年 2 月发布说明

  5. 它的工作原理是 VS Code 抓取设置到控制台的输出。如果某一行与该模式匹配,则会针对该模式“捕获”的 URL 启动浏览器。

    以下是对该模式作用的解释

    • \\b:在单词边界处匹配。请注意,\b 表示单词边界,但因为这是在 json 字符串中,所以 \ 需要转义,因此是 \\b
    • Now listening on::这是一个字符串文字,意味着下一个文本必须是 Now listening on:
    • \\s+:匹配一个或多个空格字符。
    • (:这是“捕获组”的开始。这表示要保存并用于启动浏览器的文本区域。
    • http:字符串文字。
    • s?:字符 s 或无字符。
    • ://:字符串文字。
    • \\S+:一个或多个非空白字符。
    • ):捕获组的结束。
  6. 两种浏览器启动形式都需要 "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 ✔️ 使用 launchBrowserapplicationUrl

环境变量

可以使用此架构将环境变量传递给您的程序

    "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# 表达式,而不是发送到目标进程。

示例

Example of inputting text to the Console to be set to the target process's standard input

可用性

  • 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"

限制

  1. 仅支持具有 "commandName": "Project" 的配置文件。
  2. 仅支持 environmentVariablesapplicationUrlcommandLineArgs 属性
  3. launch.json 中的设置将优先于 launchSettings.json 中的设置,例如,如果 argslaunch.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 端口。

另请参阅