企业官网建设流程全解析

如何在 Visual Studio Code 中调试本地构建的 PowerShell 源码工程

【免费下载链接】PowerShellPowerShell for every system!项目地址: https://gitcode.com/GitHub_Trending/po/PowerShell

当你想修改或扩展 PowerShell 引擎本身（而不是写 .ps1 脚本）时，需要单步进入 C# 源码、观察参数绑定、命令发现等内部逻辑。PowerShell 仓库自带了面向 VS Code 的调试配置：.vscode/launch.json 和 .vscode/tasks.json 已经提交在仓库根目录，按下面这条路径走，最终结果是：在 VS Code 中按 F5 后，"Build" 任务用Start-PSBuild编译出一份开发版pwsh，调试器在Main入口停下来，继续运行后得到可交互的 PowerShell 控制台，且可以随时在 C# 代码里打断点单步执行。

准备条件

在开始之前，核对以下四项。前两项是 docs/debugging/README.md 明确要求的，后两项由构建模块的自举机制决定：

1. VS Code 已安装 C# 扩展（ms-dotnettools.csharp）。仓库的 .vscode/extensions.json 也推荐了该扩展。

2. .NET Core 调试器。它是半自动安装的：安装 C# 扩展后，必须先在 VS Code 中打开一个 C# 文件（比如src/powershell/Program.cs），编辑器检测到调试请求时才会触发 .NET Core 调试器的实际安装。

3. pwsh可执行文件在 PATH 中（Windows 上系统自带的 Windows PowerShell 不算，需要自装 PowerShell Core 6 Beta 9 或更新的版本，见 docs/building/windows-core.md）。构建脚本本身就是 PowerShell 代码，依赖自装的pwsh来运行。Linux 上可以用仓库自带脚本安装：

   ./tools/install-powershell.sh

4. .NET CLI（dotnet）必须在 PATH 中，这一点 VS Code 无法自动满足。Start-PSBootstrap会把 .NET SDK 装到~/.dotnet（非 Windows）或"$env:LocalAppData\Microsoft\dotnet"（Windows），但不会把它加入 PATH，需要手动补：

   # Bash export PATH=$PATH:$HOME/.dotnet

   # PowerShell $env:path = $env:path + ";" + $env:LocalAppData\Microsoft\dotnet

   .NET SDK 版本以仓库根目录 global.json 为准。

用 ".NET Core Launch" 走完整调试主路径

用 VS Code 打开 PowerShell 仓库根目录，无需额外配置——调试配置和构建任务都已提交在仓库里：

• .vscode/tasks.json 提供三个 shell 任务：Bootstrap（调用Start-PSBootstrap）、Clean Build和Build。其中Build是默认构建任务，执行内容为：

  Import-Module '${workspaceFolder}/build.psm1'; Start-PSBuild -Output (Join-Path '${workspaceFolder}' debug)

  即调用 build.psm1 中的Start-PSBuild，把可执行文件固定输出到仓库根目录的debug文件夹。

• .vscode/launch.json 中的.NET Core Launch配置（type: coreclr）设置了program: ${workspaceRoot}/debug/pwsh、preLaunchTask: Build、justMyCode: false、stopAtEntry: true、externalConsole: true。

执行步骤：

1. 确认已打开过至少一个 C# 文件（见准备条件第 2 条），否则调试器尚未安装。
2. 在调试下拉框选择".NET Core Launch"，按 F5。VS Code 先运行Build任务完成编译，再启动pwsh进程。
3. 因为stopAtEntry为true，进程会在Main入口停下，点击绿色继续箭头（或再按 F5）才开始运行。
4. 因为externalConsole为true，PowerShell 会在外部控制台窗口中交互式运行。文档要求Gnome Terminal 或 XTerm 至少安装其一（Linux 环境）；两者都没有时编辑器会提示你安装。

如果构建阶段失败，最常见的原因是包源：Start-PSBuild默认引用需要认证的私有 Azure Artifacts feed。docs/building/linux.md 和 docs/building/windows-core.md 都给出了替代方案——给构建命令加-UseNuGetOrg改用公开的 NuGet.org 源。对应到 VS Code，就是编辑tasks.json中Build任务的 command，加上-UseNuGetOrg参数（同样见下一条注意事项：这种改动不要提交）。

验证调试会话是否建立

文档给出的成功判据是这条链：

• Build任务完成后，可执行文件位于${workspaceRoot}/debug/pwsh——这是launch.json里program字段指向的路径，调试器正是靠这个固定位置找到刚编译出来的程序。
• F5 启动后，调试器在Main处停下。此时说明构建和调试附着都成功。
• 按 F5 继续后，外部终端里出现可交互的 PowerShell 提示符，你在编辑器里对 C# 代码（例如src/System.Management.Automation/下的引擎代码）设置的断点即可在后续运行中被命中，且justMyCode: false允许进入 .NET 框架库内部。

替代路径：".NET Core Attach" 附加到已运行的 pwsh

如果你已经通过别的方式（终端直接运行./debug/pwsh或& (Get-PSOutput)）启动了一个pwsh进程，不想走 launch 流程，可以用 launch.json 中的".NET Core Attach"配置：

{ "type": "coreclr", "request": "attach", "justMyCode": false, "processId": "${command:pickProcess}" }

它通过pickProcess命令让你从进程列表里挑选要附加的目标。docs/debugging/README.md 还提到，如果需要更细粒度的控制，可以把processName换成processId直接填 PID，并提醒：此类改动不要提交。

限制与注意事项

• 不要提交对.vscode的改动。调试文档明确要求：tasks.json的默认配置是为了让任何人开箱即用而设计的，本地为加参数（如-UseNuGetOrg）或填 PID 做的修改只应留在本地。

• 调试器依赖构建输出位置。.NET Core Launch假定可执行文件在debug/pwsh，这正是Build任务里-Output参数的作用；如果绕过Build任务、改用 docs/building/linux.md 中的默认输出路径（./src/powershell-unix/bin/Debug/net11.0/linux-x64/publish/pwsh），launch 配置就找不到程序，要么手动把产物放到debug/，要么用 Attach 方式。

• 如果目标不是调试 C# 源码，而是排查运行中的 PowerShell 子系统行为，同一个文档还提供了两个辅助手段：Get-TraceSource列出可用 tracer，Trace-Command打开其中若干（如CommandDiscovery、ParameterBinding、PathResolution），例如：

  Trace-Command -Expression { Get-ChildItem . } -Name PathResolution -PSHost

  其中-PSHost指定输出到控制台，-Name指定要启用的 tracer。

• 仓库还提供 tools/debug.sh 脚本，用带 SOS 插件的 LLDB 启动 PowerShell；调试文档自己的建议是 VS Code 体验更好且支持单步，LLDB 只是 Linux 上的补充手段。

完成一次 F5 全流程后，你手里就有了可复用的调试循环：改 C# 代码 → 断点 → F5（自动重新构建）→ 在Main或断点处观察变量。后续若要跑测试验证改动，构建文档给出的入口是Start-PSPester -UseNuGetOrg（Pester 测试）和Start-PSxUnit（xUnit 测试）。

【免费下载链接】PowerShellPowerShell for every system!项目地址: https://gitcode.com/GitHub_Trending/po/PowerShell