mirror of
https://github.com/microsoft/PowerToys.git
synced 2025-12-15 19:27:56 +01:00
Dev doc: Work in vscode (#41704)
<!-- Enter a brief description/summary of your PR here. What does it fix/what does it change/how was it tested (even manually, if necessary)? --> ## Summary of the Pull Request Doc and debugging setting in vscode. <!-- Please review the items on the PR checklist before submitting--> ## 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 <!-- Provide a more detailed description of the PR, other things fixed, or any additional comments/features here --> ## 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. <!-- Describe how you validated the behavior. Add automated tests wherever possible, but list manual validation steps taken as well --> ## Validation Steps Performed Can debug locally in vscode --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
5
.github/actions/spell-check/expect.txt
vendored
5
.github/actions/spell-check/expect.txt
vendored
@@ -247,6 +247,7 @@ CONFIGW
|
|||||||
CONFLICTINGMODIFIERKEY
|
CONFLICTINGMODIFIERKEY
|
||||||
CONFLICTINGMODIFIERSHORTCUT
|
CONFLICTINGMODIFIERSHORTCUT
|
||||||
CONOUT
|
CONOUT
|
||||||
|
coreclr
|
||||||
constexpr
|
constexpr
|
||||||
contentdialog
|
contentdialog
|
||||||
contentfiles
|
contentfiles
|
||||||
@@ -268,6 +269,8 @@ cpcontrols
|
|||||||
cph
|
cph
|
||||||
cplusplus
|
cplusplus
|
||||||
CPower
|
CPower
|
||||||
|
cpptools
|
||||||
|
cppvsdbg
|
||||||
cppwinrt
|
cppwinrt
|
||||||
createdump
|
createdump
|
||||||
CREATEPROCESS
|
CREATEPROCESS
|
||||||
@@ -279,6 +282,7 @@ CRH
|
|||||||
critsec
|
critsec
|
||||||
cropandlock
|
cropandlock
|
||||||
Crossdevice
|
Crossdevice
|
||||||
|
csdevkit
|
||||||
CSearch
|
CSearch
|
||||||
CSettings
|
CSettings
|
||||||
cso
|
cso
|
||||||
@@ -2012,6 +2016,7 @@ XButton
|
|||||||
xclip
|
xclip
|
||||||
xcopy
|
xcopy
|
||||||
XDeployment
|
XDeployment
|
||||||
|
xdf
|
||||||
XDocument
|
XDocument
|
||||||
XElement
|
XElement
|
||||||
xfd
|
xfd
|
||||||
|
|||||||
43
.vscode/launch.json
vendored
Normal file
43
.vscode/launch.json
vendored
Normal file
@@ -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
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
128
doc/devdocs/development/dev-with-vscode.md
Normal file
128
doc/devdocs/development/dev-with-vscode.md
Normal file
@@ -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 |
|
||||||
Reference in New Issue
Block a user