winui-setup · diff
git:20260825.f12cc57 to git:20260826.26aa303
74 added, 78 removed. Audit A to A.
---
name: winui-setup
- description: "Install and verify the prerequisites the win-dev-skills WinUI 3 toolchain depends on — .NET SDK 10, the WinApp CLI, the WinUI 3 .NET templates, and Developer Mode. Use only when the user explicitly asks to set up or repair the toolchain. Do not invoke automatically when another skill reports a missing prerequisite; tell the user what is missing and ask them to invoke this skill."
+ description: "Install and verify the prerequisites the win-dev-skills WinUI 3 toolchain depends on — .NET SDK 8.0.100+, WinApp CLI 0.6+, and Developer Mode. Use only when the user explicitly asks to set up or repair the toolchain. Do not invoke automatically when another skill reports a missing prerequisite; tell the user what is missing and ask them to invoke this skill."
---
### Purpose
- Install and verify the prerequisites every other `winui-*` skill assumes are already present on the machine.
+ Install and verify the prerequisites every other `winui-*` skill assumes. WinApp CLI 0.6 owns WinUI template discovery and installation through `winapp new`; **do not install the template pack separately**.
> [!IMPORTANT]
> Run this skill only when the user explicitly asks to set up or repair the toolchain. If it is loaded without an explicit request, do not run checks or installations; explain what the skill changes and wait for confirmation.
- This skill is **idempotent** — every step checks first, skips if already satisfied, prints `[OK] already installed` and moves on. Re-running on a fully set-up machine is a fast no-op.
+ This skill is idempotent: detect everything first, install or upgrade only what is needed, and print one final summary.
### Steps
- The first thing to do is **batch all detection up front** — run every check in parallel/together so you can show the user the full picture before installing anything. Then install only what's missing.
-
#### Detect everything
- Run all of these together; collect the results:
+ Run these checks together so the user sees the full state before anything changes:
```powershell
- # .NET SDK — accept any installed SDK >= 8.0
- $dotnetSdks = (& dotnet --list-sdks 2>$null) -replace ' \[.*$',''
- $dotnetOk = $dotnetSdks | ForEach-Object { [version]($_ -split '-')[0] } |
- Where-Object { $_.Major -ge 8 } | Select-Object -First 1
+ $minimumDotNet = [version]'8.0.100'
+ $minimumWinApp = [version]'0.6.0'
- # WinApp CLI — needs to be present AND >= 0.3
+ # .NET SDK — project-mode winapp run requires SDK 8.0.100+
+ $dotnetSdks = @(& dotnet --list-sdks 2>$null) | ForEach-Object {
+ $text = ($_ -replace ' \[.*$','').Trim()
+ $parsed = $null
+ if ([version]::TryParse(($text -split '-')[0], [ref]$parsed)) { $parsed }
+ }
+ $dotnetVersion = $dotnetSdks |
+ Where-Object { $_ -ge $minimumDotNet } |
+ Sort-Object -Descending |
+ Select-Object -First 1
+ $dotnetOk = $null -ne $dotnetVersion
+
+ # WinApp CLI — require 0.6+ for winapp new, find-ui, and project-mode run
+ $winappCmd = Get-Command winapp -ErrorAction SilentlyContinue
$winappVersion = $null
- $winappOk = $false
- $winappCmd = Get-Command winapp -ErrorAction SilentlyContinue
if ($winappCmd) {
- $raw = (& winapp --version 2>$null) -as [string]
- if ($raw) {
- $base = ($raw -split '-')[0] # strip "-prerelease.N" if present
- try {
- $winappVersion = [version]$base
- $winappOk = $winappVersion -ge [version]'0.3'
- } catch {}
+ foreach ($line in @(& winapp --version 2>$null)) {
+ $match = [regex]::Match(
+ [string]$line,
+ '^\s*v?(?<version>\d+\.\d+\.\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?\s*$'
+ )
+ if ($match.Success) {
+ $parsed = $null
+ if ([version]::TryParse($match.Groups['version'].Value, [ref]$parsed)) {
+ $winappVersion = $parsed
+ }
+ }
}
}
-
- # WinUI 3 templates
- $templatesOk = [bool](dotnet new list winui 2>$null | Select-String 'winui-mvvm' -Quiet)
+ $winappOk = $winappVersion -ge $minimumWinApp
# Developer Mode
$devModeOk = ((Get-ItemProperty `
- -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' `
- -Name AllowDevelopmentWithoutDevLicense -ErrorAction SilentlyContinue
+ -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' `
+ -Name AllowDevelopmentWithoutDevLicense -ErrorAction SilentlyContinue
).AllowDevelopmentWithoutDevLicense) -eq 1
```
- Print a one-shot status table so the user sees what you're about to do:
+ Print a one-shot status table:
- ```
- .NET SDK ≥ 8 ✅ found 10.0.100 (or ❌ missing — will install Microsoft.DotNet.SDK.10)
- WinApp CLI ⚠ found 0.3.1 — will upgrade to latest
- (or ❌ missing/too old — will install Microsoft.WinAppCLI)
- WinUI 3 templates ✅ found — will reinstall to make sure they're at latest
- Developer Mode ❌ disabled — needs admin to enable
+ ```text
+ .NET SDK >= 8.0.100 [OK] found 10.0.100
+ WinApp CLI >= 0.6.0 [!] found 0.5.1 — will upgrade
+ Developer Mode [X] disabled — needs admin to enable
```
- > **Always upgrade WinApp CLI and the WinUI templates** even when they're already present — they ship breaking changes between releases and the rest of the `winui-*` skills assume latest. The minimum bar is "WinApp CLI ≥ 0.3 and templates installed at all"; the goal is "both at latest".
-
#### Install what's missing
- Skip anything already-OK from detection. The remaining steps:
+ ##### .NET SDK
- ##### .NET SDK (only if no SDK ≥ 8.0 was found)
+ Only when no SDK at or above `8.0.100` was found:
```powershell
winget install --id Microsoft.DotNet.SDK.10 --exact --silent --accept-package-agreements --accept-source-agreements
```
- `.NET 8.0` is the floor. If the user already has 8.0, 9.0, or 10.0 installed (any patch), the requirement is met — do not install another SDK side-by-side.
+ Do not install another SDK when 8.0.100+, 9.x, or 10.x is already present.
- ##### WinApp CLI — install if missing/old, then always upgrade
+ ##### WinApp CLI
- If `$winappOk` is false (missing or `< 0.3`), install it. Then **always** run `winget upgrade` regardless, so even already-present installs get bumped to latest:
+ If `winapp` is missing, install it. If it is present but below 0.6.0, try to upgrade it. Skip both commands when the installed version already meets the minimum:
```powershell
- # Install only if missing or too old
- winget install --id Microsoft.WinAppCLI --exact --silent --accept-package-agreements --accept-source-agreements
-
- # Always — upgrade to latest (no-op if already at latest)
- winget upgrade --id Microsoft.WinAppCLI --exact --silent --accept-package-agreements --accept-source-agreements
- ```
-
- ##### Refresh `$env:Path`
-
- If you installed the .NET SDK or anything else via winget in this session, **refresh PATH** so subsequent steps can find the new tools. Without this, `dotnet new install` will fail with "command not found" even though the SDK is on disk:
+ # When winapp is missing
+ winget install --id Microsoft.WinAppCli --exact --silent --accept-package-agreements --accept-source-agreements
- ```powershell
- $env:Path = [Environment]::GetEnvironmentVariable('Path','Machine') + ';' + [Environment]::GetEnvironmentVariable('Path','User')
+ # When winapp is present but older than 0.6.0
+ winget upgrade --id Microsoft.WinAppCli --exact --silent --accept-package-agreements --accept-source-agreements
```
- ##### WinUI 3 .NET templates — always reinstall to get latest
-
- Run this every time, whether or not `$templatesOk` was true. `dotnet new install` against an already-installed template package upgrades it in place to the latest version:
+ Refresh PATH after any winget install or upgrade:
```powershell
- dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates
+ $env:Path = [Environment]::GetEnvironmentVariable('Path','Machine') + ';' +
+ [Environment]::GetEnvironmentVariable('Path','User')
```
- ##### Developer Mode (ask the user first!)
+ Run the version detection again. If the result is still below `0.6.0`, report the actual version and mark setup failed; do not continue with old command fallbacks.
- Developer Mode is the DWORD `AllowDevelopmentWithoutDevLicense` under `HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock`. Setting it requires admin, which means a UAC prompt will pop up. **Do not just trigger UAC out of nowhere — ask the user first** so they're not surprised by the elevation prompt. Use language like:
+ > `winapp new` installs the official `Microsoft.WindowsAppSDK.WinUI.CSharp.Templates` pack on demand and can update it with `--template-version latest`. Do not run `dotnet new install` during setup.
- > Developer Mode is currently disabled. Enabling it requires a one-time admin elevation (a UAC prompt will appear). Would you like me to enable it now? (yes / no / I'll do it later)
+ ##### Developer Mode (ask first)
- Only if the user agrees, re-elevate **only this step** via UAC:
+ Developer Mode requires admin elevation. **Ask the user before triggering UAC.** Only if they agree, elevate this one operation:
```powershell
Start-Process powershell -Verb RunAs -ArgumentList @(
- '-NoProfile','-Command',
- "New-Item -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -Force | Out-Null; " +
- "Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' " +
- "-Name AllowDevelopmentWithoutDevLicense -Type DWord -Value 1"
+ '-NoProfile','-Command',
+ "New-Item -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -Force | Out-Null; " +
+ "Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' " +
+ "-Name AllowDevelopmentWithoutDevLicense -Type DWord -Value 1"
) -Wait
```
- If the user declines (either says no, or accepts but then dismisses the UAC prompt), do not abort the whole skill. Print the literal command above so they can run it later from an elevated PowerShell, and continue to the summary.
+ If the user declines or dismisses UAC, continue to the summary and print the command for later use.
- ### Final summary — always print this
+ ### Final summary
- After everything, print a single-table summary so the user knows exactly what changed:
+ Always print a single summary:
- ```
+ ```text
==== winui-setup summary ====
- .NET SDK ≥ 8 ⏭ already present (9.0.313)
- WinApp CLI ✅ upgraded to 0.4.0 (or ✅ installed, ⏭ already at latest, ❌ failed)
- WinUI 3 templates ✅ updated to latest
- Developer Mode ✅ enabled (or ⏭ skipped — user declined, or ❌ failed: <reason>)
+ .NET SDK >= 8.0.100 [>] already present (10.0.100)
+ WinApp CLI >= 0.6.0 [OK] upgraded to 0.6.0
+ Developer Mode [OK] enabled
```
You're ready. If the current harness exposes the `winui-dev` orchestrator agent,
start a fresh session with that agent and ask it to build a WinUI app. Otherwise,
start a fresh session in the current harness and ask it to perform the WinUI task;
it will load the relevant `winui-*` skills on demand.
For GitHub Copilot CLI, for example:
copilot --agent winui:winui-dev -p "build me a WinUI 3 markdown editor"
### Things to NOT do
- - ❌ **Do not install Visual Studio.** It is not required — these skills build and run with the dotnet and winapp clis.
- - ❌ **Do not install or upgrade the user's AI coding harness** as part of this skill. `winui-setup` manages Windows/WinUI development prerequisites only.
- - ❌ **Do not elevate the entire session** — only step 5 needs admin. Elevating earlier steps would install winget packages into the admin user's profile instead of the user's, which is wrong.
- - ❌ **Do not skip the PATH refresh** — agents that skip it install the SDK and then immediately fail on `dotnet new install`.
- - ❌ **Do not trigger UAC for Developer Mode without asking the user first** — the prompt is jarring if it pops up unannounced. Always confirm before elevating.
- - ❌ **Do not silently retry on failure.** If a `winget install` fails (no network, package source down, permissions), record the error in the summary table and move on. Let the user see what failed.
- - ❌ **Do not install .NET 10 if the machine already has any .NET SDK ≥ 8.0** — the floor is 8.0, and adding another SDK side-by-side wastes disk space.
+ - Do not install Visual Studio; these skills build and run with `dotnet` and `winapp`.
+ - Do not install or upgrade the user's AI coding harness; this skill manages Windows/WinUI development prerequisites only.
+ - Do not install the WinUI template pack separately; `winapp new` owns it in 0.6+.
+ - Do not elevate the entire session; only the Developer Mode registry write needs admin.
+ - Do not skip the PATH refresh after a winget install or upgrade.
+ - Do not trigger UAC without asking the user first.
+ - Do not silently retry failed installs or accept WinApp CLI below 0.6.0.
+ - Do not install .NET 10 when any SDK at or above 8.0.100 is already available.