Refocus docs overview and README on WinUI developers by niels9001 · Pull Request #986 · microsoft/winappCli

Niels Laute (niels9001) · 2026-10-05T13:07:44Z

Description

Refocuses the README and the MS Learn docs overview on WinUI developers. Packaging cross-platform apps is still covered, but it's no longer the main story. The Learn output generated from this branch is in MicrosoftDocs/windows-dev-docs-pr#7405.

docs/README.md (Learn overview)

Adds six benefit rows, each with an image on the left: create and run, debugging, coding agents, automated UI testing, packaging, and any framework.
Adds a samples table (WinUI samples listed first), the Install-WinGetPackage Microsoft.winappcli install option, a VS Code Marketplace link, and a Support link.
Adds card artwork in docs/images/card-*.png, generated with WPD Brand Studio.

docs/guides/winui.md

New WinUI guide for Learn.

scripts/port-mslearn-docs.ps1

Ports the new guide and images, and adds the TOC changes: an "Overview" first entry (the TOC is now nested under the existing Tools TOC in the docs repo, not standalone), and Framework guides expanded by default.

README.md

Adds WinUI to the intro, "Perfect for", and Get started badges. The Docs link now goes to Learn.
Fixes the Commands Overview:
- Moves pack under "Packaging, Certificates & Signing".
- Adds complete, a "UI Automation & Sandbox" section (ui, target), and node generate-bindings.
Adds C++ WinUI and MAUI to the Samples table.
Additional guides: adds sparse packaging and shell completion, and removes a duplicate MAUI entry.
Small style fixes.

Usage Example

N/A (docs only)

Related Issue

Related to MicrosoftDocs/windows-dev-docs-pr#7405

Type of Change

📝 Documentation

Checklist

Tested locally on Windows: scripts/port-mslearn-docs.ps1 -Version 0.7.2 (rebased on main) ported 27 files and 8 images. scripts/validate-mslearn-docs.ps1 passed, with 37 existing callout-style warnings.
Main README.md updated (if applicable)
Language-specific guides updated (if applicable)

Screenshots / Demo

Learn preview: https://review.learn.microsoft.com/en-us/windows/apps/dev-tools/winapp-cli/index?branch=pr-en-us-7405

Additional Notes

The telemetry page is intentionally not ported to Learn.

github-actions · 2026-10-05T13:45:28Z

⏳ Build in progress — metrics below are from a previous commit and will update when the current build finishes.

Build Metrics Report

Validation passed. All required build and validation jobs succeeded.

Binary Sizes

Artifact	Baseline	Current	Delta
CLI (ARM64)	57.78 MB	57.78 MB	✅ 0.0 KB (0.00%)
CLI (x64)	57.80 MB	57.80 MB	✅ 0.0 KB (0.00%)
MSIX (ARM64)	24.02 MB	24.02 MB	📉 -0.5 KB (-0.00%)
MSIX (x64)	25.46 MB	25.46 MB	📉 -0.5 KB (-0.00%)
NPM Package	50.05 MB	50.05 MB	📉 -0.5 KB (-0.00%)
NuGet Package	50.15 MB	50.15 MB	📉 -0.1 KB (-0.00%)

.NET Test Results (TRX reports)

Other suites are reflected in the overall validation status above.

✅ 8315 passed, 37 skipped out of 8352 tests in 1284.4s (+53.8s vs. baseline)

Test Coverage

✅ 86.7% line coverage, 81.3% branch coverage · ✅ no change vs. baseline

CLI Startup Time

41ms median (x64, winapp --version) · 📉 -12ms vs. baseline

Try This Build

Installs the MSIX for your architecture, replacing any previously installed build. Needs the GitHub CLI — the command offers to install it and sign you in if it is missing.

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) 986

Switching between builds often?

Put the tool on your PATH once:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) -AddToPath

Then this build is just:

winapp-pr 986

Run winapp-pr with no arguments to pick from a list of open PRs.

Updated 2026-10-09 10:42:07 UTC · commit 4a3c664 · workflow run

## Description Reorders the `winapp --help` screen to follow the app development workflow (create, run, debug, discover, test, then package) and updates the root description to match. Before this change, "Packaging & Signing" was the second group, directly under Setup. `run` was in the middle of "Development Tools", and low-level identity tools were mixed in with everyday commands. **New groups, in order** | Group | Commands | |---|---| | Get Started | `new`, `init`, `restore`, `update` | | Run & Debug | `run`, `create-debug-identity`, `unregister`, `target` | | Discovery | `find-ui`, `find-api` | | UI Automation | `ui` | | Package, Sign & Publish | `package`, `manifest`, `cert`, `sign`, `az-sign`, `store` | | Advanced | `embed-identity`, `create-external-catalog`, `tool`, `get-winapp-path` | **Root description** - Before: "CLI for Windows app development, including package identity, packaging, managing Package.appxmanifest, test certificates, Windows (App) SDK projections, and more. For use with any app framework targeting Windows" - After: "Create, run, debug, test, and package Windows apps from the command line. Works with WinUI and any other (cross-platform) app framework targeting Windows, and manages Windows SDKs, package identity, manifests, and certificates." - The root `ShortDescription` is updated to match. **Other changes** - Removes the trailing periods from the `run` and `unregister` short descriptions, so all help rows are consistent. - Regenerates `docs/cli-schema.json` with `build-cli.ps1 -OnlyDocs`. - No command names, options, or behavior change. ## Usage Example ```bash winapp --help ``` ## Related Issue Related to #986 (docs and README refocus on WinUI developers) ## Type of Change - ✨ New feature - 📝 Documentation ## Checklist - [x] Tested locally on Windows: - `dotnet test --project src/winapp-CLI/WinApp.Cli.Tests/WinApp.Cli.Tests.csproj --filter "FullyQualifiedName~CustomHelpTests|FullyQualifiedName~CliSchemaTests|FullyQualifiedName~CompleteCommandTests|FullyQualifiedName~WinAppParserConfigurationTests"` passed (42 tests). - `scripts/build-cli.ps1 -OnlyDocs` passed. ## Screenshots / Demo ```text Create, run, debug, test, and package Windows apps from the command line. Works with WinUI and any other (cross-platform) app framework targeting Windows, and manages Windows SDKs, package identity, manifests, and certificates. ┌─Get Started──────────────┐ │ new, init, restore, ... │ ├─Run & Debug──────────────┤ ├─Discovery────────────────┤ ├─UI Automation────────────┤ ├─Package, Sign & Publish──┤ └─Advanced─────────────────┘ ``` ## Additional Notes The category order only affects the root help screen. Subcommand help still uses the default renderer. --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: Nikola Metulev <nmetulev@users.noreply.github.com> Co-authored-by: Nikola Metulev <711864+nmetulev@users.noreply.github.com>

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Rename the first TOC entry to Overview, since the ported toc.yml is included under a WinApp CLI node in hub/apps/tools/toc.yml instead of rendering as a standalone TOC. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Copilot review overview

🟡 Changes recommended

The navigation rename breaks an existing test, and the new guide needs corrections to prevent failed commands and unexpected application-data deletion.

Review effort: Balanced
Findings: 4

Open (4)

Document that --clean deletes application data · New
Use a selector copied from the running app · New
Correct packaging guidance to require an explicit project input · New
Update TOC regression test for renamed Overview label · New

What changed in this PR

Refocuses the documentation on WinUI development while retaining guidance for other frameworks.

Changes:

Highlights WinUI workflows, samples, and tooling in both overviews.
Adds a WinUI guide covering creation through packaging.
Updates Learn navigation with an Overview entry and expanded framework guides.

File	Description
scripts/port-mslearn-docs.ps1	Updates Learn navigation and includes the WinUI guide.
README.md	Emphasizes WinUI and refreshes commands and samples.
docs/README.md	Adds benefit cards, quick-start instructions, and samples.
docs/guides/winui.md	Documents the WinUI development workflow.

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Rewrite the docs overview intro so it highlights both WinUI and the value for Electron, Flutter, Tauri, Rust, .NET, and C++ apps. Update the port test to expect the new Overview TOC label. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Nikola Metulev (nmetulev)

🤖 AI-generated review (winappcli pr-review skill) — verify before acting.

Decision: changes required. I published the CLI from this branch and ran every command in docs/guides/winui.md and in the overview quickstart. Most of them work. Two sections tell people to do something that doesn't work. Details are in the inline comments.

Must fix

"Test your app" never runs any tests. The winui-unittest app opens a blank window, prints no results, and winapp run waits until you close the window. This can't work with a plain launch. The template hands its command line to UnitTestClient.Run(Environment.CommandLine), which only runs tests when a test runner starts the app (today, Visual Studio Test Explorer). winapp run starts it with no arguments. Running dotnet test from the terminal also fails (0/2), because the tests run in a plain test host where the Windows App SDK isn't initialized and the UI-thread dispatcher (DispatcherQueue) is null.
winapp pack doesn't accept a solution or a folder. "Existing WinUI projects" says it does, but only winapp run accepts those inputs.

Non-blocking

winapp ui invoke btn-save-1234 fails because the template app has no such element.
"Use dotnet run instead" adds a package that projects created with winapp new already reference.
The overview's "ready to share" step signs with the development certificate, whose password is public.
No sample test runs the winapp new workflow this guide teaches. A Phase 1 that runs new --template winui-navview, then run --no-launch, cert generate, and pack would have caught both must-fix issues.

Follow-up outside this PR: the claim that winui-unittest runs its tests when launched already exists in docs/usage.md (lines 166 and 188), in the next-step message in NewCommand.cs (line 1243), and in the winapp-setup skill. It's worth a separate issue. MSTest 4.5 and Microsoft.Testing.Platform 2.5 (currently previews) let dotnet test --project . / dotnet run register and launch packaged WinUI test apps (docs), so the template could support the command line in the future. That issue should also cover how winapp run handles test projects. Today the template's Microsoft.Windows.SDK.BuildTools.WinApp reference redirects dotnet run to winapp run.

What I ran

Overview quickstart, verbatim: new --template winui-navview, run, cert generate, pack → signed MSIX ✅
new --list matches the template table ✅
run on a build-output folder, with -p WindowsPackageType=None, on a .sln, and with --detach --json ✅
pack rejects --manifest, --skip-pri, and WindowsPackageType=None, as documented ✅
find-ui "tabbed layout", find-ui --id gallery-tabview-1, find-api NavigationView ✅
ui inspect / search / invoke / screenshot locally, and run / ui with --on sandbox ✅
cpp-app-winui: cmake build, then winapp run .\build\Debug shows a Package Family Name ✅
Docs port: Pester 37/37, port-mslearn-docs.ps1 ported 27 files and 8 images, validate-mslearn-docs.ps1 passed, and the new links and anchors resolve ✅
Not run: --debug-output crash analysis and --arch arm64.

- Developer Mode: enable it in Settings - Fix winui-unittest description and remove the Test your app section - Disclose that --clean deletes app data - dotnet run works out of the box for winapp new projects - Use a real ui invoke selector - winapp pack takes a .csproj; document .vcxproj support for C++ WinUI - Reword local signing step and point to az-sign for distribution Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

…C (#7405) * Update winapp CLI docs from upstream port and nest under the Tools TOC Regenerate hub/apps/dev-tools/winapp-cli with scripts/port-mslearn-docs.ps1 from microsoft/winappCli#986 (v0.7.2), the same flow the release pipeline runs. Include the ported toc.yml from hub/apps/tools/toc.yml so the pages render in the existing Tools navigation. Keep the docs-repo-only Visual Studio templates and quickstart updates. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Regenerate winapp CLI docs with the balanced WinUI and cross-platform intro Ported from microsoft/winappCli#986 (ffe6a13) with scripts/port-mslearn-docs.ps1. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Re-port winapp CLI docs from microsoft/winappCli#986 (36cf911) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Rename Visual Studio Code extension to WinApp VS Code extension in Tools Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Mark the winui CLI template as C#-only in Visual Studio templates table winapp new scaffolds from the Microsoft.WindowsAppSDK.WinUI.CSharp.Templates pack, so the winui template only creates the C# variant of WinUI Blank App (Packaged). Match the existing winui-unittest (C#) row. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Add author and ms.author to the winapp CLI WinUI guide front matter AGENTS.md requires author and ms.author on every article. Use the repo defaults (GrantMeStrength / jken), which match the docfx.json metadata for apps/**. The port generator (scripts/port-mslearn-docs.ps1, Get-FrontMatter) lives upstream in microsoft/WinAppCli and doesn't emit these fields yet. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Remove duplicate Resources link from the WinUI quickstart next steps hub/apps/dev-tools/index.md no longer exists and redirects to /windows/apps/tools/, not to control examples. The same paragraph already links to Code samples and the WinUI Gallery (dev-tools/samples.md). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Use a TIP callout for the .vcxproj note in the winapp CLI C++ guide Replace the bold-text blockquote with Learn callout syntax. The block is copied verbatim from upstream microsoft/WinAppCli docs/guides/cpp.md, so the upstream source needs the same change to survive the next port. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Regenerate content index Committed unchanged from the generated-content-index artifact of Conceptual content index run 38464717388. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: GrantMeStrength <1928855+GrantMeStrength@users.noreply.github.com> Copilot-Session: 598eb8e8-713b-43e3-ad17-fcf7262888d1

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a1da2b76-ba63-485d-8aa1-5549229d42e9

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: d9f56c40-403c-4679-aeab-517dc51f98d0

Jaylyn Barbee (Jaylyn-Barbee)

LGTM from a porting-to-mslearn POV

Niels Laute (niels9001) mentioned this pull request Oct 5, 2026

Reorder root help around the app development workflow #987

Merged

1 task done

Niels Laute (niels9001) and others added 2 commits October 7, 2026 15:44

Refocus docs overview and README on WinUI developers

ca2b07e

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Niels Laute (niels9001) force-pushed the niels9001/docs-winui-focus branch from 25b3e94 to 06e6b9e Compare October 7, 2026 13:44

Niels Laute (niels9001) marked this pull request as ready for review October 7, 2026 13:58

Copilot AI balanced review requested due to automatic review settings October 7, 2026 13:58

Copilot started reviewing on behalf of Niels Laute (niels9001) October 7, 2026 13:58

View session

Copilot AI reviewed Oct 7, 2026

View reviewed changes

Comment thread docs/guides/winui.md Outdated

Comment thread docs/guides/winui.md Outdated

Comment thread docs/guides/winui.md Outdated

Comment thread scripts/port-mslearn-docs.ps1

Nikola Metulev (nmetulev) reviewed Oct 8, 2026

View reviewed changes

Comment thread docs/guides/winui.md Outdated

Comment thread docs/guides/winui.md

Comment thread docs/README.md Outdated

Nikola Metulev (nmetulev) reviewed Oct 8, 2026

View reviewed changes

Comment thread docs/guides/winui.md Outdated

Comment thread docs/guides/winui.md Outdated

Comment thread docs/guides/winui.md Outdated

Comment thread docs/guides/winui.md Outdated

Comment thread docs/guides/winui.md Outdated

Comment thread docs/README.md Outdated

Merge branch 'main' into niels9001/docs-winui-focus

b5ada3b

Niels Laute (niels9001) enabled auto-merge (squash) October 8, 2026 13:16

Niels Laute (niels9001) mentioned this pull request Oct 8, 2026

winui-unittest: tests don't run on launch, and docs/CLI guidance is wrong #1031

Open

github-actions Bot added 4 commits October 8, 2026 16:29

Merge branch 'main' into niels9001/docs-winui-focus

9e4a0b0

Merge branch 'main' into niels9001/docs-winui-focus

190ba86

Merge branch 'main' into niels9001/docs-winui-focus

090e70b

Merge branch 'main' into niels9001/docs-winui-focus

0980914

Nikola Metulev (nmetulev) disabled auto-merge October 8, 2026 21:53

Remove card images from docs overview for now

4a3c664

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Chiara Mooney (chiaramooney) reviewed Oct 16, 2026

View reviewed changes

Comment thread docs/guides/winui.md Outdated

Chiara Mooney (chiaramooney) requested a review from Jaylyn Barbee (Jaylyn-Barbee) October 20, 2026 18:15

Chiara Mooney (chiaramooney) added this to the 0.8 milestone Oct 20, 2026

Chiara Mooney (chiaramooney) and others added 2 commits October 20, 2026 11:36

Use consistent WinApp CLI capitalization in overview docs

43ea93b

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: a1da2b76-ba63-485d-8aa1-5549229d42e9

Merge branch 'main' into niels9001/docs-winui-focus

017eb64

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: d9f56c40-403c-4679-aeab-517dc51f98d0

Jaylyn Barbee (Jaylyn-Barbee) enabled auto-merge (squash) October 20, 2026 18:56

Jaylyn Barbee (Jaylyn-Barbee) approved these changes Oct 20, 2026

View reviewed changes

github-actions Bot added 8 commits October 20, 2026 19:28

Merge branch 'main' into niels9001/docs-winui-focus

6b4e6d1

Merge branch 'main' into niels9001/docs-winui-focus

e80fac3

Merge branch 'main' into niels9001/docs-winui-focus

ab855eb

Merge branch 'main' into niels9001/docs-winui-focus

f6044f8

Merge branch 'main' into niels9001/docs-winui-focus

017812b

Merge branch 'main' into niels9001/docs-winui-focus

ed0439e

Merge branch 'main' into niels9001/docs-winui-focus

4c5981d

Merge branch 'main' into niels9001/docs-winui-focus

b5c4dbe

Navigation Menu

Repository navigation

Refocus docs overview and README on WinUI developers - #986

Refocus docs overview and README on WinUI developers#986
Niels Laute (niels9001) wants to merge 20 commits into
mainfrom
niels9001/docs-winui-focus

Niels Laute (niels9001) commented Oct 5, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 5, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Nikola Metulev (nmetulev) left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Jaylyn Barbee (Jaylyn-Barbee) left a comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

Niels Laute (niels9001) commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Usage Example

Related Issue

Type of Change

Checklist

Screenshots / Demo

Additional Notes

Uh oh!

github-actions Bot commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Build Metrics Report

Binary Sizes

.NET Test Results (TRX reports)

Test Coverage

CLI Startup Time

Try This Build

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Nikola Metulev (nmetulev) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Jaylyn Barbee (Jaylyn-Barbee) left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Niels Laute (niels9001) commented Oct 5, 2026 •

edited

Loading

github-actions Bot commented Oct 5, 2026 •

edited

Loading