Skip to content

Commit d0dc568

Browse files
chiaramooneyCopilotnmetulev
authored
Update READMEs for VSC + Config for Pre-launch Build Task (#493)
## Description <!-- Briefly describe what this PR does and why --> Update READMEs for VSC. Added VSC section to README at root. Updated VSC README to callout that VSC extension does not rebuild app project, it only launches. Added instructions to README for how users can configure VS Code to rebuild their application before launching. ## Related Issue Fixes #490 Fixes #372 ## Type of Change <!-- Keep the applicable line(s), delete the rest --> - 📝 Documentation - ## Checklist <!-- Delete the ones that do not apply to your changes --> - [x] Tested locally on Windows - [x] Main [README.md](../README.md) updated (if applicable) ## AI Description <!-- ai-description-start --> This update enhances the documentation for the WinApp VS Code Extension. A new section has been added to the root README to introduce the extension and outline its capabilities. The VSC-specific README now clarifies that the extension does not rebuild projects automatically and provides instructions for users to configure their VS Code settings to enable project rebuilding before launching the app. <!-- ai-description-end --> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Nikola Metulev <nmetulev@users.noreply.github.com>
1 parent b55b68c commit d0dc568

2 files changed

Lines changed: 63 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -245,6 +245,15 @@ This repository includes samples demonstrating how to use the CLI with various f
245245
| [Tauri App](/samples/tauri-app/README.md) | Tauri cross-platform app with Rust backend |
246246
| [Flutter App](/samples/flutter-app/README.md) | Flutter desktop app with package identity and Windows App SDK |
247247

248+
## 🧩 VS Code Extension
249+
250+
The **WinApp VS Code Extension** brings WinApp CLI into Visual Studio Code. It can initialize projects, debug with package identity, package, sign, and more without leaving the editor. Press **F5** to launch your app with identity and automatically attach a debugger.
251+
252+
> [!IMPORTANT]
253+
> The extension is not yet available in the VS Code Marketplace. Download the latest prerelease: [**VS Code Extension**](https://nightly.link/microsoft/WinAppCli/workflows/build-package/main/vscode-extension.zip)
254+
255+
For setup, configuration, and troubleshooting details, see the [VS Code Extension README](./src/winapp-VSC/README.md).
256+
248257
## 🤖 Using with AI Coding Agents
249258

250259
AI coding agents (GitHub Copilot, Claude Code, etc.) auto-discover skill files in your project.

‎src/winapp-VSC/README.md‎

Lines changed: 54 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,17 @@
11
# WinApp — VS Code Extension
22

3-
The **WinApp** extension brings the [Windows App Development CLI (winapp CLI)](https://github.com/microsoft/WinAppCli) into Visual Studio Code so you can initialize, build, debug, package, and sign Windows applications without leaving the editor.
3+
The **WinApp** extension brings the [Windows App Development CLI (WinApp CLI)](https://github.com/microsoft/WinAppCli) into Visual Studio Code so you can initialize, debug, package, and sign Windows applications without leaving the editor.
44

5-
> **Status: Public Preview** — The winapp CLI and this extension are experimental and in active development. We'd love your feedback! [File an issue](https://github.com/microsoft/WinAppCli/issues).
5+
> **Status: Public Preview** — The WinApp CLI and this extension are experimental and in active development. We'd love your feedback! [File an issue](https://github.com/microsoft/WinAppCli/issues).
6+
7+
## Get Started
8+
9+
> [!IMPORTANT]
10+
> The WinApp VS Code Extension is not yet available in the VS Code Marketplace. We plan to publish the extension publicly soon.
11+
12+
Try the WinApp extension today by downloading our latest prerelease: [**VS Code Extension**](https://nightly.link/microsoft/WinAppCli/workflows/build-package/main/vscode-extension.zip)
13+
14+
Simply navigate to the 'Extensions' tab in VS Code, and select the option to 'Install via VSIX...'. You may need to restart VS Code for the extension to begin working.
615

716
## Features
817

@@ -23,7 +32,7 @@ All commands are accessible from the Command Palette (`Ctrl+Shift+P`). Type **Wi
2332
| **WinApp: Add Manifest Execution Alias** | Add an execution alias to the manifest so the packaged app can be launched from the command line. |
2433
| **WinApp: Update Manifest Assets** | Auto-generate all required app icon assets from a single source image (PNG, JPG, GIF, or BMP). |
2534
| **WinApp: Generate Certificate** | Create a development certificate for signing, with an option to install it immediately. |
26-
| **WinApp: Install Certificate** | Install an existing `.pfx` or `.cer` certificate. |
35+
| **WinApp: Install Certificate** | Install an existing `.pfx` or `.cer` certificate. (requires Admin elevation) |
2736
| **WinApp: Certificate Info** | Display certificate details (subject, thumbprint, expiry) to verify a certificate matches your manifest. |
2837
| **WinApp: Sign Package** | Sign an MSIX package or executable with a certificate. |
2938
| **WinApp: Run SDK Tool** | Run Windows SDK tools (`makeappx`, `signtool`, `mt`, `makepri`) with custom arguments. |
@@ -41,6 +50,37 @@ The extension provides a **custom `winapp` debug type** that launches your app w
4150
4. It launches your app via `winapp run` to give it package identity.
4251
5. A child debug session attaches to the running process using the debugger you specified.
4352

53+
> [!IMPORTANT]
54+
> The `winapp` debug type assumes your project has already been built and that a build output folder containing an `.exe` exists in your project. It **does not** build your project automatically — so after making code changes, you must rebuild your project before launching to see those changes reflected in the running app.
55+
56+
> [!TIP]
57+
> You can automate the build step by adding a `preLaunchTask` to your `launch.json` configuration. This tells VS Code to run a build task before every debug session, so your changes are always compiled before launch.
58+
>
59+
> 1. Define a build task in `.vscode/tasks.json` (example for .NET):
60+
> ```jsonc
61+
> {
62+
> "version": "2.0.0",
63+
> "tasks": [
64+
> {
65+
> "label": "build",
66+
> "command": "dotnet",
67+
> "type": "process",
68+
> "args": ["build", "${workspaceFolder}"],
69+
> "problemMatcher": "$msCompile"
70+
> }
71+
> ]
72+
> }
73+
> ```
74+
> 2. Reference it in your `launch.json`:
75+
> ```jsonc
76+
> {
77+
> "type": "winapp",
78+
> "request": "launch",
79+
> "name": "WinApp: Launch and Attach",
80+
> "preLaunchTask": "build"
81+
> }
82+
> ```
83+
4484
**Supported debuggers:**
4585
4686
| `debuggerType` | Language | Required Extension |
@@ -93,7 +133,7 @@ See the full [Debugging Guide](https://github.com/microsoft/WinAppCli/blob/main/
93133

94134
### Generate manifests and assets
95135

96-
Use **WinApp: Generate Manifest** to create an `AppxManifest.xml` from a template, then **WinApp: Update Manifest Assets** to auto-generate all required app icons from a single source image. Use **WinApp: Add Manifest Execution Alias** to add a command-line alias so your packaged app can be launched by typing its name in a terminal.
136+
Use **WinApp: Generate Manifest** to create an `Package.appxmanifest` from a template, then **WinApp: Update Manifest Assets** to auto-generate all required app icons from a single source image. Use **WinApp: Add Manifest Execution Alias** to add a command-line alias so your packaged app can be launched by typing its name in a terminal.
97137

98138
### Package and sign
99139

@@ -123,6 +163,16 @@ The winapp CLI is bundled with the extension — no separate installation requir
123163

124164
For debugging, install the debugger extension that matches your app's language (see [Supported debuggers](#integrated-debugging) above).
125165

166+
## Troubleshooting
167+
168+
| Problem | Cause | Solution |
169+
|---------|-------|----------|
170+
| **"No folders containing .exe files found in the workspace..."** or **"No build output folder selected..."** when pressing F5 | The project hasn't been built yet, or the build output is in an unexpected location. | Build your project first (e.g., `dotnet build`), or set `inputFolder` in `launch.json` to point to the folder containing your `.exe`. |
171+
| **Debugger doesn't attach** | The required debugger extension isn't installed. | Install the matching extension for your language — see [Supported debuggers](#integrated-debugging). |
172+
| **App launches but changes aren't visible** | The `winapp` debug type does not build the project automatically. | Rebuild your project before pressing F5, or add a `preLaunchTask` to automate it (see the tip in [Integrated Debugging](#integrated-debugging)). |
173+
| **Certificate trust error when running** | The development certificate isn't installed or has expired. | Run **WinApp: Generate Certificate** and choose to install it, or run **WinApp: Install Certificate** with your existing `.pfx` file. (requires Admin elevation) |
174+
| **"Access denied" or permission errors** | Some operations (certificate install, package registration) require elevation. | Run VS Code as Administrator, or use an elevated terminal for the failing command. |
175+
126176
## Feedback and Support
127177

128178
- [File an issue or feature request](https://github.com/microsoft/WinAppCli/issues)

0 commit comments

Comments
 (0)