From dd25769a9674e18d997e75b54cdd985c0b2df284 Mon Sep 17 00:00:00 2001 From: Kai Tao <69313318+vanzue@users.noreply.github.com> Date: Thu, 11 Sep 2025 16:12:53 +0800 Subject: [PATCH] Dev doc: Work in vscode (#41704) ## Summary of the Pull Request Doc and debugging setting in vscode. ## PR Checklist - [ ] Closes: #xxx - [ ] **Communication:** I've discussed this with core contributors already. If the work hasn't been agreed, this work might be rejected - [ ] **Tests:** Added/updated and all pass - [ ] **Localization:** All end-user-facing strings can be localized - [ ] **Dev docs:** Added/updated - [ ] **New binaries:** Added on the required places - [ ] [JSON for signing](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ESRPSigning_core.json) for new binaries - [ ] [WXS for installer](https://github.com/microsoft/PowerToys/blob/main/installer/PowerToysSetup/Product.wxs) for new binaries and localization folder - [ ] [YML for CI pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ci/templates/build-powertoys-steps.yml) for new test projects - [ ] [YML for signed pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/release.yml) - [ ] **Documentation updated:** If checked, please file a pull request on [our docs repo](https://github.com/MicrosoftDocs/windows-uwp/tree/docs/hub/powertoys) and link it here: #xxx ## Detailed Description of the Pull Request / Additional comments This pull request adds support for developing and debugging PowerToys using Visual Studio Code by introducing a new launch configuration and comprehensive developer documentation. These changes make it easier for contributors to build, debug, and iterate on both native and managed components of PowerToys within VS Code. **VS Code integration and developer workflow:** * Added `.vscode/launch.json` with configurations for launching and attaching to native (`PowerToys.exe`) and managed (`PowerToys.Settings.exe`) processes, supporting both C++ and .NET debugging scenarios. * Introduced `doc/devdocs/development/dev-with-vscode.md`, a detailed guide covering VS Code setup, building, debugging, and common developer workflows for the PowerToys project. This includes extension recommendations, shell integration, sample build commands, and troubleshooting tips. ## Validation Steps Performed Can debug locally in vscode --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/actions/spell-check/expect.txt | 5 + .vscode/launch.json | 43 +++++++ doc/devdocs/development/dev-with-vscode.md | 128 +++++++++++++++++++++ 3 files changed, 176 insertions(+) create mode 100644 .vscode/launch.json create mode 100644 doc/devdocs/development/dev-with-vscode.md diff --git a/.github/actions/spell-check/expect.txt b/.github/actions/spell-check/expect.txt index 8b9f694e3b..c4c13282e4 100644 --- a/.github/actions/spell-check/expect.txt +++ b/.github/actions/spell-check/expect.txt @@ -247,6 +247,7 @@ CONFIGW CONFLICTINGMODIFIERKEY CONFLICTINGMODIFIERSHORTCUT CONOUT +coreclr constexpr contentdialog contentfiles @@ -268,6 +269,8 @@ cpcontrols cph cplusplus CPower +cpptools +cppvsdbg cppwinrt createdump CREATEPROCESS @@ -279,6 +282,7 @@ CRH critsec cropandlock Crossdevice +csdevkit CSearch CSettings cso @@ -2012,6 +2016,7 @@ XButton xclip xcopy XDeployment +xdf XDocument XElement xfd diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000000..b2d2bca9ac --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,43 @@ +{ + "version": "0.2.0", + "inputs": [ + { + "id": "arch", + "type": "pickString", + "description": "Select target architecture", + "options": ["x64", "arm64"], + "default": "x64" + } + ], + "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 + } + ] +} \ No newline at end of file diff --git a/doc/devdocs/development/dev-with-vscode.md b/doc/devdocs/development/dev-with-vscode.md new file mode 100644 index 0000000000..4b1b7def24 --- /dev/null +++ b/doc/devdocs/development/dev-with-vscode.md @@ -0,0 +1,128 @@ +## Developing PowerToys with Visual Studio Code + +This guide shows how to build, debug, and contribute to PowerToys using VS Code instead of (or alongside) full Visual Studio. It focuses on common inner‑loop tasks for C++, .NET, and mixed scenarios present in the solution. + +> PowerToys is a large mixed C++ / C# / WinAppSDK solution. VS Code works well for incremental development and quick module iterations, but occasionally you may still prefer full Visual Studio for designer tooling or specialized diagnostics. + +--- +VS Code extensions Needed: + +| Area | Extension | Notes | +|------|-----------|-------| +| C++ | ms-vscode.cpptools | IntelliSense, debugging (cppvsdbg) | +| C# | ms-dotnettools.csdevkit (or C#) | Language service / test explorer | + +--- + +## Building in VS Code +### Configure developer powershell for vs2022 for more convenient dev in vscode. +1. Configure profile in in settings, entry: "terminal.integrated.profiles.windows" +2. Add below config as entry: +```json + "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;", + // Configure based on your environment + "& 'C:\\Program Files\\Microsoft Visual Studio\\2022\\Enterprise\\Common7\\Tools\\Launch-VsDevShell.ps1';", + "Set-Location $orig", + "}" + ] + }, +``` +3. [Optional] Set Developer PowerShell for VS 2022 as your default profile, so that you can get a deep integration with vscode coding agent. + +4. Now You can build with plain `msbuild` or configure tasks.json in below section +Or reach out to "tools\build\BUILD-GUIDELINES.md" + +### Sample plain msbuild command +```powershell +# Restore: +msbuild powertoys.sln -t:restore -p:configuration=debug -p:platform=x64 -m + +# Build powertoys sln +msbuild powertoys.sln -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 +``` + +--- + +## Debugging + +### Existing launch configuration + +The repo provides `.vscode/launch.json` with: + +- `Run PowerToys.exe (no build)`: Launches the already-built executable at `x64/Debug/PowerToys.exe` using `cppvsdbg`. + +Build first, then press F5. To switch configuration (Release / ARM64) either edit the path or create additional launch entries. + +### Attaching to a running instance + +If PowerToys is already running, you can attach to that process: + +2. VS Code command palette: “C/C++: (Windows) Attach to Process”. +3. Filter for `PowerToys.exe` / module-specific processes. + +### Debugging managed components + +Many modules have a managed component loaded into the PowerToys process. `cppvsdbg` can debug mixed mode, but if you need richer .NET inspection you can create a second configuration using `type: coreclr` and `processId` attachment after the native launch, or just attach separately: + +Similar for attach to managed code. +> Note: In arm64 machine, can only debug arm64 code. + +```jsonc +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Run native executable (no build)", + "type": "cppvsdbg", + "request": "launch", + "program": "${workspaceFolder}\\x64\\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}\\x64\\Debug;${workspaceFolder}\\Debug;${workspaceFolder}\\symbols" + }, + { + "name": "Run managed code (managed, no build)", + "type": "coreclr", + "request": "launch", + "program": "${workspaceFolder}\\arm64\\Debug\\WinUI3Apps\\PowerToys.Settings.exe", + "args": [], + "cwd": "${workspaceFolder}", + "env": {}, + "console": "internalConsole", + "stopAtEntry": false + } + ] +} +``` +--- + +## 6. Common tasks & tips + +| Task | Command / Action | Notes | +|------|------------------|-------| +| Clean | `git clean -xdf` (careful) or `msbuild /t:Clean PowerToys.sln` | Deep clean removes packages & build outputs | +| Rebuild single project | `msbuild path\to\proj.vcxproj /t:Rebuild -p:Platform=x64 -p:Configuration=Debug` | Faster than whole solution | +| Generate installer (rare in inner loop) | See `tools\build\build-installer.ps1` | Usually not needed for local debug | +| Resource conversion errors | Re-run restore + build | Triggers custom PowerShell targets | \ No newline at end of file