使用 Visual Studio Code 调试已编译的 cmdlet

本指南向您展示如何使用 Visual Studio Code (VS Code) 和 C# 扩展以交互方式调试已编译的 PowerShell 模块的 C# 源代码。

假设您熟悉 Visual Studio Code 调试器。

• 有关 VS Code 调试器的一般介绍，请参阅在 Visual Studio Code 中调试。

• 有关调试 PowerShell 脚本文件和模块的示例，请参阅使用 Visual Studio Code 进行远程编辑和调试。

本指南假设您已阅读并遵循编写便携式模块指南中的说明。

创建构建任务

在启动调试会话之前自动构建您的项目。重建可确保您调试最新版本的代码。

配置构建任务：

1. 在命令面板中，运行配置默认构建任务命令。

   运行配置默认构建任务

2. 在选择要配置的任务对话框中，选择从模板创建tasks.json文件。

3. 在选择任务模板对话框中，选择.NET Core。

如果尚不存在，则会创建一个新的 tasks.json 文件。

要测试您的构建任务：

1. 在命令面板中，运行运行构建任务命令。

2. 在选择要运行的构建任务对话框中，选择构建。

有关被锁定的 DLL 文件的信息

默认情况下，成功的构建不会在终端窗格中显示输出。如果您看到包含文本项目文件不存在的输出，则应编辑 tasks.json 文件。包括 C# 项目的显式路径，表示为 "$ {workspaceFolder}/myModule"。在此示例中，myModule 是项目文件夹的名称。此条目必须位于 args 列表中的 build 条目之后，如下所示：

    {
        "label": "build",
        "command": "dotnet",
        "type": "shell",
        "args": [
            "build",
            "${workspaceFolder}/myModule",
            // Ask dotnet build to generate full paths for file names.
            "/property:GenerateFullPaths=true",
            // Do not generate summary otherwise it leads to duplicate errors in Problems panel
            "/consoleloggerparameters:NoSummary",
        ],
        "group": "build",
        "presentation": {
            "reveal": "silent"
        },
        "problemMatcher": "$msCompile"
    }

调试时，模块 DLL 将导入到 VS Code 终端中的 PowerShell 会话中。 DLL 被锁定。当您运行构建任务而不关闭终端会话时，将显示以下消息：

Could not copy "obj\Debug\netstandard2.0\myModule.dll" to "bin\Debug\netstandard2.0\myModule.dll"`.

重建之前必须关闭终端会话。

设置调试器

要调试 PowerShell cmdlet，您需要设置自定义启动配置。此配置用于：

• 构建您的源代码
• 启动 PowerShell 并加载模块
• 让 PowerShell 在终端窗格中保持打开状态

当您在终端会话中调用 cmdlet 时，调试器会在源代码中设置的任何断点处停止。

为 PowerShell 配置 launch.json

1. 安装 C# for Visual Studio Code 扩展

2. 在“调试”窗格中，添加调试配置

3. 在选择环境对话框中，选择.NET Core

4. launch.json 文件将在编辑器中打开。将光标放在 configurations 数组中，您会看到 configuration 选择器。如果您没有看到此列表，请选择添加配置。

5. 要创建默认调试配置，请选择启动 .NET Core 控制台应用：

   启动 .NET Core 控制台应用程序

6. 编辑 name、program、args 和 console 字段，如下所示：

    {
        "name": "PowerShell cmdlets: pwsh",
        "type": "coreclr",
        "request": "launch",
        "preLaunchTask": "build",
        "program": "pwsh",
        "args": [
            "-NoExit",
            "-NoProfile",
            "-Command",
            "Import-Module ${workspaceFolder}/myModule/bin/Debug/netstandard2.0/myModule.dll",
        ],
        "cwd": "${workspaceFolder}",
        "stopAtEntry": false,
        "console": "integratedTerminal"
    }
   

program 字段用于启动 pwsh 以便运行正在调试的 cmdlet。 -NoExit 参数可防止 PowerShell 会话在导入模块后立即退出。当您遵循编写可移植模块指南时，Import-Module 参数中的路径是默认的构建输出路径。如果您已创建模块清单（.psd1 文件），则应使用该文件的路径。 / 路径分隔符适用于 Windows、Linux 和 macOS。您必须使用集成终端来运行要调试的 PowerShell 命令。

笔记

如果调试器没有在任何断点处停止，请在 Visual Studio Code 调试控制台中查找显示以下内容的行：

Loaded '/path/to/myModule.dll'. Skipped loading symbols. Module is optimized and the debugger option 'Just My Code' is enabled.

如果您看到此内容，请将 "justMyCode": false 添加到您的启动配置中（与 "console": "integratedTerminal" 处于同一级别。

为 Windows PowerShell 配置 launch.json

此启动配置适用于在 Windows PowerShell (powershell.exe) 中测试 cmdlet。创建第二个启动配置并进行以下更改：

1. 名称应为PowerShell cmdlet：powershell

2. 类型应该是clr

3. program 应该是 powershell

   它应该看起来像这样：

    {
        "name": "PowerShell cmdlets: powershell",
        "type": "clr",
        "request": "launch",
        "preLaunchTask": "build",
        "program": "powershell",
        "args": [
            "-NoExit",
            "-NoProfile",
            "-Command",
            "Import-Module ${workspaceFolder}/myModule/bin/Debug/netstandard2.0/myModule.dll",
        ],
        "cwd": "${workspaceFolder}",
        "stopAtEntry": false,
        "console": "integratedTerminal"
    }
   

启动调试会话

现在一切准备就绪，可以开始调试了。

• 在要调试的 cmdlet 的源代码中放置一个断点：

  断点在装订线中显示为红点

• 确保在调试视图的配置下拉菜单中选择相关的PowerShell cmdlet配置：

  选择启动配置

• 按F5或单击开始调试按钮

• 切换到终端窗格并调用您的 cmdlet：

  调用 cmdlet

• 执行在断点处停止：

  执行在断点处停止

您可以单步执行源代码、检查变量并检查调用堆栈。

要结束调试，请单击调试工具栏中的停止或按Shift+F5。用于调试的 shell 退出并释放对已编译的 DLL 文件的锁定。