用 VS Code 开发 PowerToys：混合 C++/C 解决方案的构建与调试实战指南

PowerToys 是一个 C++ / C# / WinAppSDK 混合的大型解决方案，日常迭代并不强制使用完整版 Visual Studio。本文基于仓库官方开发文档 dev-with-vscode.md，系统讲解如何在 VS Code 中完成 PowerToys 的内循环开发：配置 Developer PowerShell 终端、用裸 msbuild 或仓库自带 task 构建、用 cppvsdbg / coreclr 调试原生与托管进程，以及常用清理、单项目重建等任务的处理方式。读完本文，你可以完全脱离 Visual Studio IDE，在 VS Code 中独立完成模块级的构建、调试与快速迭代。

为什么 VS Code 适合 PowerToys 的增量开发

PowerToys 解决方案包含大量 C++ 模块（runner、keyboardmanager、fancyzones、ZoomIt 等）、.NET 模块（MouseUtils、launcher、settings-ui）以及 WinUI 3 应用。根据官方文档的定位：VS Code 很适合增量开发和单模块快速迭代，但当需要 XAML 设计器工具或某些专项诊断能力时，仍可能更适合完整版 Visual Studio。这一"分工"决定了本文所有配置都围绕"快"展开——裸 msbuild 命令、按项目而非整解决方案构建、以及直接 attach 到已运行进程。

VS Code 下开发 PowerToys 需要安装两个核心扩展：

领域	扩展	说明
C++	ms-vscode.cpptools	IntelliSense、调试（cppvsdbg）
C#	ms-dotnettools.csdevkit（或 C#）	语言服务 / 测试资源管理器

构建篇一：配置 Developer PowerShell 终端

在 VS Code 中跑 msbuild 的前提是当前终端已经加载了 Visual Studio 开发者环境（MSVC 工具链、NuGet、vcpkg 路径等）。官方推荐的方式是在 VS Code 设置项 terminal.integrated.profiles.windows 中新增一个"Developer PowerShell for VS"终端配置文件，启动时自动执行 Launch-VsDevShell.ps1 初始化环境，同时保留你打开仓库前所在的工作目录。

针对 Visual Studio 2026（文档推荐）的配置：

"Developer PowerShell for VS": {
    // Configure based on your preference
    "path": "C:\\Program Files\\WindowsApps\\Microsoft.PowerShell_7.5.2.0_arm64__8wekyb3d8bbwe\\pwsh.exe",
    "args": [
        "-NoExit",
        "-Command",
        "& {",
        "$orig = Get-Location;",
        // Adjust path based on your edition (Community/Professional/Enterprise)
        "& 'C:\\Program Files\\Microsoft Visual Studio\\18\\Enterprise\\Common7\\Tools\\Launch-VsDevShell.ps1';",
        "Set-Location $orig",
        "}"
    ]
},

针对 Visual Studio 2022 的配置：

"Developer PowerShell for VS 2022": {
    // Configure based on your preference
    "path": "C:\\Program Files\\WindowsApps\\Microsoft.PowerShell_7.5.2.0_arm64__8wekyb3d8bbwe\\pwsh.exe",
    "args": [
        "-NoExit",
        "-Command",
        "& {",
        "$orig = Get-Location;",
        // Adjust path based on your edition (Community/Professional/Enterprise)
        "& 'C:\\Program Files\\Microsoft Visual Studio\\2022\\Enterprise\\Common7\\Tools\\Launch-VsDevShell.ps1';",
        "Set-Location $orig",
        "}"
    ]
},

使用这套配置时有三个要点需要注意：

1. 按实际安装情况调整路径：path 是 PowerShell 7 在 WindowsApps 下的安装位置，版本号（如 7.5.2.0）与架构后缀需匹配你的机器；Launch-VsDevShell.ps1 的目录中 18 / 2022 对应 VS 版本，Enterprise 需替换为你实际的 Community / Professional / Enterprise 版本。
2. 工作目录保持技巧：脚本先 Get-Location 暂存当前目录，执行 VsDevShell 后再 Set-Location $orig 切回，避免 VsDevShell 把目录切到别处导致相对路径命令失效。
3. 设为默认终端（可选）：文档建议把该 Developer PowerShell 配置为默认终端 profile，这样在 VS Code 中获得更深度的集成体验（包括与 VS Code coding agent 的协作）。

完成配置后，即可在 VS Code 集成终端中直接使用裸 msbuild 命令构建，也可以改用下一节的 task 方式。

构建篇二：裸 msbuild 命令

在 Developer PowerShell 终端中，官方文档给出了四类最常用的 msbuild 用法，覆盖整解决方案还原/构建、单 .NET 项目与单 C++ 项目的场景：

# Restore:
msbuild powertoys.slnx -t:restore -p:configuration=debug -p:platform=x64 -m

# Build powertoys slnx
msbuild powertoys.slnx -p:configuration=debug -p:platform=x64 -m

# dotnet project
msbuild src\settings-ui\Settings.UI\PowerToys.Settings.csproj -p:Platform=x64 -p:Configuration=Debug -m

# native project
msbuild "src\modules\MouseUtils\FindMyMouse\FindMyMouse.vcxproj" -p:Configuration=Debug -p:Platform=x64 -m

对照仓库结构可以验证这些路径都是真实存在的：

• 解决方案文件为 PowerToys.slnx（新版 slnx 格式）；
• .NET 项目示例对应 src/settings-ui/Settings.UI/PowerToys.Settings.csproj；
• 原生项目示例对应 src/modules/MouseUtils/FindMyMouse/FindMyMouse.vcxproj。

参数含义：-t:restore 指定只执行 NuGet 还原目标；-p:configuration= / -p:platform= 传入构建配置与平台（x64 / arm64）；-m 启用多核并行编译。ARM64 机器上把平台参数换成 arm64 即可。

除裸命令外，仓库还提供了一组更省心的构建脚本 tools/build/BUILD-GUIDelines.md 有完整说明：

• tools\build\build-essentials.cmd / build-essentials.ps1：先还原 PowerToys.slnx 的 NuGet 包，再构建 essentials（runner + settings），自动检测平台并自动初始化 VS 开发者环境；
• tools\build\build.cmd / build.ps1：构建当前目录下的 .sln/.csproj/.vcxproj，同样自动检测平台、自动初始化 Dev 环境，并支持透传额外 MSBuild 参数（如 '/p:CIBuild=true'）与 -RestoreOnly 只还原；
• 脚本失败时会写出 build.<configuration>.<platform>.all.log / .errors.log / .warnings.log / .trace.binlog 等日志，方便排查。

VS Code tasks.json：把构建变成一键任务

仓库已随 .vscode/tasks.json 提供了封装好的构建任务，与上面的 tools\build 脚本一一对应：

• PT: Build (quick)：调用 tools\build\build.cmd -Path ${fileDirname}，并按 isDefault: build 设为默认构建任务；
• PT: Build (with options)：额外通过交互式输入框选择 Platform（X64 / ARM64，留空自动检测宿主平台）、Configuration（Debug / Release）以及追加的 MSBuild 参数（如 /p:CIBuild=true /m）；
• PT: Build Essentials (quick) / PT: Build Essentials (with options)：对应 build-essentials.cmd，构建 runner + settings 这一最小可用组合。

所有任务都配置了 $msCompile problem matcher，编译错误会直接出现在 VS Code 的"问题"面板中。值得注意的是，Windows 下这些 shell 任务显式指定了 cmd.exe /d /c 作为 shell，以避免用户 profile 干扰。

对于极少在开发内循环中用到的安装包生成，文档指引到 tools/build/build-installer.ps1（完整打包流水线：还原、构建、MSIX 签名、WiX v5 MSI/bootstrapper，支持 -PerUser、-InstallerSuffix wix5|vnext 等参数）——本地调试通常不需要跑它。

调试篇：launch.json 中的三类调试配置

仓库自带 .vscode/launch.json，覆盖了 PowerToys 混合技术栈最常见的三种调试场景。文档中给出的示例配置（含仓库当前实际的架构可选增强）如下：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Run native executable (no build)",
            "type": "cppvsdbg",
            "request": "launch",
            "program": "${workspaceFolder}\\${input:arch}\\Debug\\PowerToys.exe",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [],
            "console": "integratedTerminal"
        },
        {
            "name": "C/C++ Attach to PowerToys Process (native)",
            "type": "cppvsdbg",
            "request": "attach",
            "processId": "${command:pickProcess}",
            "symbolSearchPath": "${workspaceFolder}\\${input:arch}\\Debug;${workspaceFolder}\\Debug;${workspaceFolder}\\symbols"
        },
        {
            "name": "Run managed code (managed, no build, ARCH configurable)",
            "type": "coreclr",
            "request": "launch",
            "program": "${workspaceFolder}\\${input:arch}\\Debug\\WinUI3Apps\\PowerToys.Settings.exe",
            "args": [],
            "cwd": "${workspaceFolder}",
            "env": {},
            "console": "internalConsole",
            "stopAtEntry": false
        }
    ]
}

三个配置分别对应文档讲解的三种调试模式：

1. 启动式调试（Run，不构建）

Run native executable (no build) 使用 cppvsdbg 直接拉起已经构建好的可执行文件 PowerToys.exe（runner 宿主进程，位于 x64/Debug/ 下）。工作流是：先完成构建，再按 F5。仓库实际文件比文档示例更进一步——定义了一个 pickString 类型的 input:arch（x64 / arm64，默认 x64），${input:arch} 会同时替换 exe 路径和符号搜索路径，从而支持选择目标架构；若要切到 Release 或另一架构，按文档提示编辑路径或新增 launch 条目即可。

2. 附加到运行中的进程（Attach）

如果 PowerToys 已经在运行（比如你不想重启整个应用），可以直接附加：

1. 选择 "C/C++ Attach to PowerToys Process (native)" 配置后 F5，或使用 VS Code 命令面板中的 "C/C++: (Windows) Attach to Process"；
2. 在进程列表里过滤 PowerToys.exe 或某个模块专属进程（如各 WinUI 模块的 UI 进程）；
3. processId: ${command:pickProcess} 会弹出进程选择器，symbolSearchPath 则指向 ${workspaceFolder}\${input:arch}\Debug、Debug 与 symbols 三个符号目录，保证 PDB 能被找到。

这个模式对 PowerToys 特别有用：runner 是宿主，多数模块以 DLL 形式加载进 runner 进程，部分模块则派生独立进程，attach 是命中这些代码最快的方式。

3. 托管代码调试（coreclr）

很多模块的 UI 是托管组件（加载进 PowerToys 进程或独立 WinUI 3 进程）。cppvsdbg 本身可以调试混合模式，但如果你需要更丰富的 .NET 检查能力，仓库给出了 type: coreclr 的第二套配置：

• 文档示例中，Run managed code 配置直接 launch arm64/Debug/WinUI3Apps/PowerToys.Settings.exe（设置 UI 的独立 WinUI 3 进程）；
• 仓库实际的 .vscode/launch.json 在此基础上把架构也参数化了，并额外提供了一条 Run AdvancedPaste (managed, no build, ARCH configurable) 配置，直接拉起 WinUI3Apps\PowerToys.AdvancedPaste.exe，说明这种 coreclr 配置模式可以按模块复制扩展；
• 另一种等效做法：先按常规方式启动原生宿主，再用 coreclr 以 processId 方式附加到同一个托管进程上；
• 对托管模块的调试与原生 attach 类似——挑选对应进程附加即可。

平台限制：文档特别注明——在 arm64 机器上只能调试 arm64 代码（没有跨架构仿真调试），这与上文 input:arch 默认 x64 的设计相呼应，ARM64 用户需要保证构建与调试架构一致。

常用任务与实用技巧

官方文档总结了一张内循环任务速查表，这里完整继承并补充说明：

任务	命令 / 操作	说明
Clean	git clean -xdf（慎用）或 msbuild /t:Clean PowerToys.slnx	深度清理会删除包与构建输出
重建单个项目	msbuild path\to\proj.vcxproj /t:Rebuild -p:Platform=x64 -p:Configuration=Debug	比构建整个解决方案快得多
生成安装包（内循环中很少用）	见 tools/build/build-installer.ps1	本地调试通常不需要
资源转换错误	重新执行 restore + build	用于触发自定义 PowerShell 目标

几点实践提示：

• git clean -xdf 慎用：它会连同未跟踪的构建产物、还原的包目录一起删除，之后必须完整重新还原（整解决方案 restore + build 耗时明显更长）；日常清理优先用 msbuild /t:Clean。
• 单项目 Rebuild 是内循环的核心节奏：改一个模块时只重建对应的 .vcxproj / .csproj（配合上文 PT: Build (quick) 任务的 ${fileDirname} 语义，构建的正是"当前文件所在目录"下的项目），可以把反馈时间从整解决方案级别压缩到项目级别。
• 资源转换类错误（PowerToys 构建链中含 resx/rc、自定义 PowerShell 目标等生成步骤）多数情况下重新跑一遍 restore + build 即可恢复。

小结与延伸阅读

本文覆盖的 VS Code 开发内循环可以浓缩为四步：装好 cpptools / csdevkit 扩展 → 配置 Developer PowerShell 终端（VS 2026 / 2022 两种模板）→ 用裸 msbuild 或 PT: Build task 构建 → 用 .vscode/launch.json 中现成的 cppvsdbg / coreclr 配置启动或附加调试。所有关键文件都已随仓库提供：.vscode/launch.json、.vscode/tasks.json、.vscode/settings.json、tools/build/BUILD-GUIDELINES.md。

如果想进一步理解调试 PowerToys 的多进程模型（runner 宿主 + 模块 DLL/子进程）、提权调试的限制（FancyZones 无法移动提权窗口、Shortcut Guide 在提权前台窗口前不出现）以及 Visual Studio 侧的 Shell Process Debugging Tool 方案，可继续阅读 debugging.md。