🚀 在 VS Code 中获取 ！

配置 C# 调试

您可以使用 launch.json、launchSettings.json 或用户 settings.json 文件在 Visual Studio Code 中配置 C# 调试器。

以下是在调试时您可能想要更改的常用选项。

配置 VS Code 的调试行为

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）使用以下内容来配置 VS Code 以在 ASP.NET 启动时启动 Web 浏览器

    "serverReadyAction": {
        "action": "openExternally",
        "pattern": "\\bNow listening on:\\s+(https?://\\S+)"
    }

关于此的说明

  1. 如果您不希望浏览器自动启动，您可以删除此元素（以及 launchBrowser 元素，如果您的 launch.json 中有该元素）。

  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 ✔️ 与 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# 表达式，而不是发送到目标进程。

示例

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

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. 仅支持 environmentVariables、applicationUrl 和 commandLineArgs 属性
  3. 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 ❌

仅我的代码

您可以选择通过将 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
    }

有关管道传输的更多信息，请参见 此处。

您可以在 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 无效。但是，您可以通过使用环境变量 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 ❌

源链接选项

源链接是一项功能，它使您在调试在另一台计算机上构建的代码（例如来自 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 ❌

检查 DevCert

此选项控制在启动时，调试器是否应检查计算机是否具有用于开发在 https 终结点上运行的 Web 项目的自签名 HTTPS 证书。为此，它尝试运行 dotnet dev-certs https --check --trust，如果未找到证书，它将提示用户建议创建一个证书。如果用户批准，则扩展运行 dotnet dev-certs https --trust 以创建受信任的自签名证书。

如果未指定，则当设置 serverReadyAction 时，默认为 true。此选项在 Linux、VS Code 远程和 VS Code for the Web 场景中不起作用。

您可以通过在 launch.json 中将 checkForDevCert 设置为 false 来覆盖此行为。

示例

    "checkForDevCert": "false"

可用性

  • launch.json ✔️
  • settings.json ❌
  • launchSettings.json ✔️ 作为 useSSL

配置 launchSettings.json

使用 C# 开发工具包，您可以将 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 端口。

另请参阅

6/6/2023