winui-dev-workflow

Name: winui-dev-workflow
Author: microsoft

111installs20forks

How to install winui-dev-workflow?

microsoft/win-dev-skills/winui-dev-workflow

$npx -y skills add microsoft/win-dev-skills --skill winui-dev-workflow

Installs into the current project.

Summary

Build and run workflow for WinUI 3 apps — project creation, BuildAndRun.ps1 script, winapp run, error diagnosis, and prerequisites. Use when building, running, or fixing build errors in a WinUI 3 project.

Files · 1

View on GitHub

SKILL.md

1	### Create or Open a Project
2
3	New app — scaffold with a template:
4	```powershell
5	dotnet new winui-mvvm -n <AppName>
6	cd <AppName>
7	```
8	Creates an MVVM project with CommunityToolkit.Mvvm, TitleBar, MicaBackdrop, and Frame navigation. Do NOT `mkdir` first — `-n` creates the folder.
9
10	Existing app — read the `.csproj` to understand:
11	- `<TargetFramework>` (e.g., `net10.0-windows10.0.26100.0`)
12	- `<PackageReference>` versions (WindowsAppSDK, CommunityToolkit)
13	- Project structure and established patterns
14
15	### Install Packages
16
17	```powershell
18	dotnet add package <Name>
19	```
20	Never specify `--version` — omitting it gets the latest stable and avoids outdated API mismatches.
21
22	### Build & Run
23
24	Use the `BuildAndRun.ps1` script (included with this skill) — it handles everything:
25
26	```powershell
27	.\BuildAndRun.ps1
28	```
29
30	Invoke the script with `mode: "async"`. The script stays attached to the running app so a `mode: "sync"` call blocks your turn for the entire lifetime of the app. The output contains the PID of the running app once the app starts, which looks like this:
31	```
32	✅ <pkg> launched (PID: 12345)
33	```
34
35	What the script does automatically:
36	1. Checks Developer Mode is enabled (fails fast if not)
37	2. Finds the `.csproj` in the current directory
38	3. Auto-detects platform (x64 or ARM64)
39	4. Builds with `dotnet build` (or Visual Studio MSBuild if you pass `-UseMSBuild`)
40	5. Finds the build output folder
41	6. Launches with `winapp run --debug-output`
42
43	Options:
44	```powershell
45	.\BuildAndRun.ps1 # auto-find csproj, build, run (should use async invocation)
46	.\BuildAndRun.ps1 MyApp.csproj # explicit project
47	.\BuildAndRun.ps1 -Detach # run in detached mode, no debug output or exceptions (safe to use mode: "sync")
48	.\BuildAndRun.ps1 -SkipRun # build only (safe to use mode: "sync")
49	.\BuildAndRun.ps1 -Symbols # build + run, adding --symbols (optional Symbol Server fallback)
50	.\BuildAndRun.ps1 /p:Configuration=Release # override defaults
51	```
52
53	If build fails: Read ALL errors, batch-fix them in one pass, then run `BuildAndRun.ps1` again.
54
55	If the app crashes on launch: `read_powershell` the shell — first-chance exceptions appear in the output. See the crash-diagnosis section below for WinUI stowed-exception triage.
56
57	### Diagnosing Crashes with `winapp run`
58
59	For WinUI apps, `--debug-output` (the `BuildAndRun.ps1` default) runs a stowed-exception triage on crash, surfacing the real WinUI/XAML error behind an opaque `0x8000FFFF` / `E_FAIL` — plus a fully symbolicated native dispatch stack (symbols auto-download, so `--debug-output` alone is enough). The first crash also downloads debugger components and can take a few minutes — it looks like a hang but it's caching; point `WINAPP_DBGTOOLS_DIR` at an existing Debugging Tools for Windows install to skip it. Later runs use the cache.
60
61	### Common Errors
62
63	\| Error \| Fix \|
64	\|-------\|-----\|
65	\| Developer Mode not enabled \| Settings → System → For developers → On \|
66	\| CS0234/CS0246 missing type \| Add `using` or `dotnet add package` \|
67	\| NETSDK1136 platform required \| BuildAndRun.ps1 handles this automatically \|
68	\| XLS0414 XAML type not found \| Add `xmlns` declaration \|
69	\| XDG0062 binding path missing \| Check `x:Bind` property exists on ViewModel \|
70	\| Blank window after launch \| `x:Bind` defaults to `OneTime` — add `Mode=OneWay` \|
71	\| App silently exits \| Use `winapp run`, never run the .exe directly \|
72	\| App crashes with opaque `0x8000FFFF` / `E_FAIL` \| Run under `--debug-output` (BuildAndRun.ps1 default) — WinUI stowed-exception triage surfaces the real XAML error + symbolicated native stack. `-Symbols` optional, not required \|
73	\| XAML compiler crashes silently \| Remove any `PresentationCore.dll` / `System.Windows` references \|
74	\| MSB3073 / `XamlCompiler.exe ... exited with code 1`, no `.xaml` named \| Old WindowsAppSDK XAML-compiler bug — update `Microsoft.WindowsAppSDK` NuGet to latest (≥ 2.1.3, or ≥ 1.8 on the 1.x line) \|
75	\| 0x80073CF6 package install failed \| Run `winapp init`, check manifest publisher matches cert \|
76	\| 0x8007000B bad image format \| Wrong platform target — use x64 or ARM64, not AnyCPU \|
77
78	### Prerequisites
79
80	\| Requirement \| Minimum \| Recommended (fresh installs) \| Install command \|
81	\|-------------\|---------\|------------------------------\|-----------------\|
82	\| Windows 10 v1903+ \| — \| — \| — \|
83	\| Developer Mode \| enabled \| enabled \| Settings → Advanced → Developer Mode → On \|
84	\| .NET SDK \| 8.0 \| 10.0 \| `winget install Microsoft.DotNet.SDK.10` \|
85	\| winapp CLI \| 0.3 \| latest \| `winget install Microsoft.WinAppCLI` \|
86	\| WinUI templates \| any \| latest \| `dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates` \|
87
88	If any of these are missing when you try

People who liked this also viewed

6 picks

Type

winui-dev-workflow

111installs20forks

View on GitHub

How to install winui-dev-workflow?

microsoft/win-dev-skills/winui-dev-workflow

$npx -y skills add microsoft/win-dev-skills --skill winui-dev-workflow

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	### Create or Open a Project
2
3	New app — scaffold with a template:
4	```powershell
5	dotnet new winui-mvvm -n <AppName>
6	cd <AppName>
7	```
8	Creates an MVVM project with CommunityToolkit.Mvvm, TitleBar, MicaBackdrop, and Frame navigation. Do NOT `mkdir` first — `-n` creates the folder.
9
10	Existing app — read the `.csproj` to understand:
11	- `<TargetFramework>` (e.g., `net10.0-windows10.0.26100.0`)
12	- `<PackageReference>` versions (WindowsAppSDK, CommunityToolkit)
13	- Project structure and established patterns
14
15	### Install Packages
16
17	```powershell
18	dotnet add package <Name>
19	```
20	Never specify `--version` — omitting it gets the latest stable and avoids outdated API mismatches.
21
22	### Build & Run
23
24	Use the `BuildAndRun.ps1` script (included with this skill) — it handles everything:
25
26	```powershell
27	.\BuildAndRun.ps1
28	```
29
30	Invoke the script with `mode: "async"`. The script stays attached to the running app so a `mode: "sync"` call blocks your turn for the entire lifetime of the app. The output contains the PID of the running app once the app starts, which looks like this:
31	```
32	✅ <pkg> launched (PID: 12345)
33	```
34
35	What the script does automatically:
36	1. Checks Developer Mode is enabled (fails fast if not)
37	2. Finds the `.csproj` in the current directory
38	3. Auto-detects platform (x64 or ARM64)
39	4. Builds with `dotnet build` (or Visual Studio MSBuild if you pass `-UseMSBuild`)
40	5. Finds the build output folder
41	6. Launches with `winapp run --debug-output`
42
43	Options:
44	```powershell
45	.\BuildAndRun.ps1 # auto-find csproj, build, run (should use async invocation)
46	.\BuildAndRun.ps1 MyApp.csproj # explicit project
47	.\BuildAndRun.ps1 -Detach # run in detached mode, no debug output or exceptions (safe to use mode: "sync")
48	.\BuildAndRun.ps1 -SkipRun # build only (safe to use mode: "sync")
49	.\BuildAndRun.ps1 -Symbols # build + run, adding --symbols (optional Symbol Server fallback)
50	.\BuildAndRun.ps1 /p:Configuration=Release # override defaults
51	```
52
53	If build fails: Read ALL errors, batch-fix them in one pass, then run `BuildAndRun.ps1` again.
54
55	If the app crashes on launch: `read_powershell` the shell — first-chance exceptions appear in the output. See the crash-diagnosis section below for WinUI stowed-exception triage.
56
57	### Diagnosing Crashes with `winapp run`
58
59	For WinUI apps, `--debug-output` (the `BuildAndRun.ps1` default) runs a stowed-exception triage on crash, surfacing the real WinUI/XAML error behind an opaque `0x8000FFFF` / `E_FAIL` — plus a fully symbolicated native dispatch stack (symbols auto-download, so `--debug-output` alone is enough). The first crash also downloads debugger components and can take a few minutes — it looks like a hang but it's caching; point `WINAPP_DBGTOOLS_DIR` at an existing Debugging Tools for Windows install to skip it. Later runs use the cache.
60
61	### Common Errors
62
63	\| Error \| Fix \|
64	\|-------\|-----\|
65	\| Developer Mode not enabled \| Settings → System → For developers → On \|
66	\| CS0234/CS0246 missing type \| Add `using` or `dotnet add package` \|
67	\| NETSDK1136 platform required \| BuildAndRun.ps1 handles this automatically \|
68	\| XLS0414 XAML type not found \| Add `xmlns` declaration \|
69	\| XDG0062 binding path missing \| Check `x:Bind` property exists on ViewModel \|
70	\| Blank window after launch \| `x:Bind` defaults to `OneTime` — add `Mode=OneWay` \|
71	\| App silently exits \| Use `winapp run`, never run the .exe directly \|
72	\| App crashes with opaque `0x8000FFFF` / `E_FAIL` \| Run under `--debug-output` (BuildAndRun.ps1 default) — WinUI stowed-exception triage surfaces the real XAML error + symbolicated native stack. `-Symbols` optional, not required \|
73	\| XAML compiler crashes silently \| Remove any `PresentationCore.dll` / `System.Windows` references \|
74	\| MSB3073 / `XamlCompiler.exe ... exited with code 1`, no `.xaml` named \| Old WindowsAppSDK XAML-compiler bug — update `Microsoft.WindowsAppSDK` NuGet to latest (≥ 2.1.3, or ≥ 1.8 on the 1.x line) \|
75	\| 0x80073CF6 package install failed \| Run `winapp init`, check manifest publisher matches cert \|
76	\| 0x8007000B bad image format \| Wrong platform target — use x64 or ARM64, not AnyCPU \|
77
78	### Prerequisites
79
80	\| Requirement \| Minimum \| Recommended (fresh installs) \| Install command \|
81	\|-------------\|---------\|------------------------------\|-----------------\|
82	\| Windows 10 v1903+ \| — \| — \| — \|
83	\| Developer Mode \| enabled \| enabled \| Settings → Advanced → Developer Mode → On \|
84	\| .NET SDK \| 8.0 \| 10.0 \| `winget install Microsoft.DotNet.SDK.10` \|
85	\| winapp CLI \| 0.3 \| latest \| `winget install Microsoft.WinAppCLI` \|
86	\| WinUI templates \| any \| latest \| `dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates` \|
87
88	If any of these are missing when you try

People who liked this also viewed

6 picks

Type