diff --git a/README.md b/README.md index b266cc7cf..23ba25ba5 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -# winapp CLI +# WinApp CLI > [!IMPORTANT] -> :warning: **Status: Public Preview** — The Windows App Development CLI (winapp CLI) is experimental and in active development. We'd love your feedback! Share your thoughts by creating an [issue](https://github.com/microsoft/WinAppCli/issues). +> :warning: **Status: Public Preview** — The Windows App Development CLI (WinApp CLI) is experimental and in active development. We'd love your feedback! Share your thoughts by creating an [issue](https://github.com/microsoft/WinAppCli/issues). > [!NOTE] > The **`main` branch** contains work that is in **active development**. Documentation, features, and behavior here may differ from what is publicly released. For the latest stable version, see the [latest release](https://github.com/microsoft/WinAppCli/releases/latest). To try the newest in-progress build, see [Install from latest build](#install-from-latest-build-main-branch) below. @@ -45,23 +45,28 @@ • Usage • - Docs + Docs • Feedback
-The Windows App Development CLI (winapp CLI) is a single command-line interface for managing Windows SDKs, packaging, generating app identity, manifests, certificates, and using build tools with any app framework. This tool bridges the gap between cross-platform development and Windows-native capabilities. +The Windows App Development CLI (WinApp CLI) is a single command-line interface for creating, running, debugging, testing, and packaging Windows apps. It manages Windows SDKs, app identity, manifests, certificates, and build tools for WinUI and any other app framework.

-Whether you're building with .NET/Win32, CMake, Electron, or Rust, this CLI gives you access to: +Whether you're building with WinUI, .NET/Win32, CMake, Electron, or Rust, this CLI gives you access to: +- **WinUI from the terminal** - Create apps from official templates with `winapp new` and launch them with `winapp run` - **Modern Windows APIs** - [Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/) and Windows SDK with automatic setup and code generation - **Package Identity** - Debug and test by adding package identity without full packaging in a snap - **MSIX Packaging** - App packaging with signing and Store readiness +- **UI automation and agent tooling** - Inspect and drive running apps with `winapp ui`, and ground AI coding agents with `find-ui` and `find-api` - **Developer Tools** - Manifests, certificates, assets, and build integration +Full documentation is published on Microsoft Learn: **[Windows App Development CLI](https://learn.microsoft.com/windows/apps/dev-tools/winapp-cli/)**. + Perfect for: +- **WinUI developers** who want to create, run, test, and package apps from the terminal, VS Code, or an AI coding agent - **Cross-platform developers using frameworks like Qt or Electron** wanting native Windows features or targeting Windows - **Developers who love their current tools** and want to build Windows apps from VS Code, or any other editor - **Developers crafting CI/CD pipelines** to automate building apps for Windows @@ -77,12 +82,12 @@ Our goal is to support developers wherever they are, with the tools and framewor - Before: 12 manual steps to access Windows APIs. After: 4 winapp commands (init, create-addon, add-electron-debug-identity, pack) + Before: 12 manual steps to access Windows APIs. After: 4 WinApp CLI commands (init, create-addon, add-electron-debug-identity, pack)

-

Without winapp CLI, setting up a project involves 12 manual steps—downloading SDKs, generating headers, creating manifests, and more. With the CLI, it's just 4 commands.

+

Without WinApp CLI, setting up a project involves 12 manual steps—downloading SDKs, generating headers, creating manifests, and more. With the CLI, it's just 4 commands.

-**Few examples of what package identity and MSIX packaging unlocks:** +**A few examples of what package identity and MSIX packaging unlock:** - [Interactive native notifications](https://learn.microsoft.com/windows/apps/develop/notifications/app-notifications/app-notifications-quickstart?tabs=cs) and notification management - [Integration with Windows Explorer, Taskbar, Share sheet](https://learn.microsoft.com/windows/apps/develop/windows-integration/integrate-sharesheet-packaged), and other shell surfaces @@ -99,9 +104,13 @@ Our goal is to support developers wherever they are, with the tools and framewor ## ✏️ Get started -Checkout our getting started guides for step by step instructions of how to setup your environment, generate manifests, assets, and certificate, how to debug APIs that require package identity, and how to MSIX package your app. +Check out our getting started guides for step by step instructions of how to setup your environment, generate manifests, assets, and certificate, how to debug APIs that require package identity, and how to MSIX package your app.

+ + Get Started with WinUI + +
Get Started with .NET @@ -133,8 +142,9 @@ Checkout our getting started guides for step by step instructions of how to setu Additional guides: - [Packaging an EXE/CLI](/docs/guides/packaging-cli.md): step by step guide of packaging an existing exe/cli as MSIX +- [Sparse packaging](./docs/guides/sparse.md): give an unpackaged app package identity with an identity-only MSIX and external content +- [Shell completion](./docs/guides/shell-completion.md): tab completion for commands, options, and values in PowerShell, bash, zsh, and fish - [.NET file-based apps](./docs/guides/dotnet-file-based.md): run a single `.cs` file with package identity, no project file or manifest required -- [MAUI (Windows)](./docs/guides/maui.md): package and sign .NET MAUI Windows outputs with the generated resizetizer manifest - **Electron JS/TypeScript bindings** *(npm only)*: opt into auto-generated WinRT bindings via `winapp init --add-js-bindings`. See task-focused guides: - [File picker](/docs/guides/electron/js-file-picker.md) — open native Windows file/folder pickers from the renderer - [Toast notifications](/docs/guides/electron/js-notification.md) — show Windows toasts with actions @@ -145,7 +155,7 @@ Additional guides: ### WinGet WinGet -The easiest way to use the CLI is via WinGet (Windows Package Manager). In Terminal, simply run: +The easiest way to use the CLI is via WinGet (Windows Package Manager). In Terminal, run: `winget install Microsoft.winappcli --source winget` @@ -232,8 +242,6 @@ npx winapp --help **App Identity & Debugging:** - [`perf`](./docs/guides/winui-performance.md) - Record and query WinUI operation trees, layout/scrolling timings, and managed GC suspension context - -- [`pack`](./docs/usage.md#pack) - Create MSIX packages from directories - [`run`](./docs/usage.md#run) - Run app as a packaged application for debugging (loose layout registration) - [`create-debug-identity`](./docs/usage.md#create-debug-identity) - Add sparse package identity to an existing exe - [`embed-identity`](./docs/usage.md#embed-identity) - Connect an exe to its sparse identity package by embedding the `` element @@ -242,8 +250,9 @@ npx winapp --help See also: [Debugging Guide](./docs/debugging.md) — choosing between `winapp run` and `create-debug-identity`, IDE setup, and debugging scenarios. -**Certificates & Signing:** +**Packaging, Certificates & Signing:** +- [`pack`](./docs/usage.md#pack) - Create MSIX packages from a project or prepared directories - [`cert`](./docs/usage.md#cert) - Generate and install development certificates - [`sign`](./docs/usage.md#sign) - Sign MSIX packages and executables - [`az-sign`](./docs/usage.md#az-sign) - Sign with Azure Trusted Signing (cloud-managed identity, no local PFX) @@ -257,6 +266,12 @@ See also: [Security guidance](./docs/security.md) — what development certifica - [`store`](./docs/usage.md#store) - Run Microsoft Store Developer CLI commands - [`get-winapp-path`](./docs/usage.md#get-winapp-path) - Get paths to installed SDK components - [`config`](./docs/usage.md#config) - Show or change your per-user winapp settings +- [`complete`](./docs/usage.md#shell-completion) - Tab completion for PowerShell, bash, zsh, and fish + +**UI Automation & Sandbox:** + +- [`ui`](./docs/usage.md#ui) - Inspect and interact with running app UIs through UI Automation (screenshots, element trees, clicks, and text input). See the [UI Automation guide](./docs/ui-automation.md) +- [`target`](./docs/usage.md#target) - Run commands, copy files, and capture the desktop inside Windows Sandbox. See [Windows Sandbox execution](./docs/sandbox-execution.md) - [`devtools`](./docs/usage.md#devtools) - Inspect, comment on and live-edit a running WinUI app ([guide](./docs/guides/devtools.md)) **Discovery** (agent-first — built for AI coding agents to ground generated code in real metadata and real samples, and usable by hand): @@ -267,11 +282,12 @@ See also: [Security guidance](./docs/security.md) — what development certifica **Node.js/Electron Specific:** - [`node create-addon`](./docs/usage.md#node-create-addon) - Generate native C# or C++ addons +- [`node generate-bindings`](./docs/usage.md#node-generate-bindings) - Generate JavaScript/TypeScript bindings for WinRT APIs - [`node add-electron-debug-identity`](./docs/usage.md#node-add-electron-debug-identity) - Add identity to Electron processes - [`node clear-electron-debug-identity`](./docs/usage.md#node-clear-electron-debug-identity) - Remove identity from Electron processes The full CLI usage can be found here: [Documentation](/docs/usage.md) -Use winapp from JavaScript or TypeScript: [NPM programmatic guide](/docs/npm-usage.md) +Use WinApp CLI from JavaScript or TypeScript: [NPM programmatic guide](/docs/npm-usage.md) ## 🧾 Samples @@ -287,6 +303,8 @@ This repository includes samples demonstrating how to use the CLI with various f | [WinUI App](/samples/winui-app/README.md) | Packaged WinUI 3 app registered and launched via `winapp run ` | | [WinUI Unpackaged App](/samples/winui-unpackaged-app/README.md) | Unpackaged WinUI 3 app launched via `winapp run ` | | [WinUI Solution](/samples/winui-solution/README.md) | Multi-project `.sln` (app + test project) demonstrating `winapp run` solution-mode auto-selection | +| [C++ WinUI App](/samples/cpp-app-winui/README.md) | WinUI 3 window built in C++ with CMake, without XAML or MSBuild | +| [.NET MAUI App](/samples/maui-app/README.md) | .NET MAUI Windows project packaged and signed with `winapp` | | [Electron](/samples/electron/README.md) | Electron Forge app with appxmanifest, assets, native C++ addon, and C# addon | | [Electron WinML](/samples/electron-winml/README.md) | Electron app using Windows ML for image classification | | [Node.js WinUI 3](/samples/node-winui/README.md) | Native WinUI 3 controls created directly from JavaScript | @@ -299,11 +317,11 @@ This repository includes samples demonstrating how to use the CLI with various f The **[WinApp VS Code Extension](https://marketplace.visualstudio.com/items?itemName=Microsoft-WinAppCLI.winapp)** 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. -Install it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=Microsoft-WinAppCLI.winapp). Checkout the repo for the WinApp VS Code Extension at [microsoft/WinAppVSCE](https://github.com/microsoft/WinAppVSCE). +Install it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=Microsoft-WinAppCLI.winapp). Check out the repo for the WinApp VS Code Extension at [microsoft/WinAppVSCE](https://github.com/microsoft/WinAppVSCE). ## 🤖 Using with AI Coding Agents -winapp ships a single plugin (at [`plugins/winapp/`](./plugins/winapp/)) — an agent plus skills — that conforms to the [Agent Plugins 1.0](https://agent-plugins.org/) specification and is distributed to GitHub Copilot and Claude Code through their respective plugin marketplaces. +WinApp CLI ships a single plugin (at [`plugins/winapp/`](./plugins/winapp/)) — an agent plus skills — that conforms to the [Agent Plugins 1.0](https://agent-plugins.org/) specification and is distributed to GitHub Copilot and Claude Code through their respective plugin marketplaces. **GitHub Copilot CLI** (global — works across all projects) ```bash @@ -316,7 +334,7 @@ claude plugin marketplace add microsoft/WinAppCli claude plugin install winappcli@winappcli ``` -This gives agents full understanding of winapp commands, workflows, and troubleshooting. +This gives agents full understanding of WinApp CLI commands, workflows, and troubleshooting. ## 🔧 Feedback and Support diff --git a/docs/README.md b/docs/README.md index 1eb3a6c5e..114d63f78 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,23 +1,62 @@ - -# Windows App Development CLI (winapp CLI) + +# Windows App Development CLI (WinApp CLI) > [!IMPORTANT] > The Windows App Development CLI is currently in **public preview**. Features and commands may change before the final release. Share your feedback by [creating an issue](https://github.com/microsoft/WinAppCli/issues). -The Windows App Development CLI (winapp CLI) is a single command-line interface for managing Windows SDKs, packaging, generating app identity, manifests, certificates, and using build tools with any app framework. This tool bridges the gap between cross-platform development and Windows-native capabilities. +The Windows App Development CLI (WinApp CLI) is a command-line tool for building Windows apps with the framework you choose. It works from a terminal, the editor you prefer, or an AI coding agent. -Whether you're building with .NET/Win32, CMake, Electron, or Rust, this CLI gives you access to: +- **WinUI apps:** create, run, debug, test, and package [WinUI](https://learn.microsoft.com/windows/apps/winui/winui3/) apps without opening Visual Studio. +- **Cross-platform and other frameworks:** bring Windows features to your existing Electron, Flutter, Tauri, Rust, .NET, or C++ app without changing frameworks. WinApp CLI sets up the [Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/) and Windows SDK, gives your app package identity so you can call APIs like notifications and on-device AI, and packages it as MSIX for the Microsoft Store or your own distribution. -- **Modern Windows APIs** - [Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/) and Windows SDK with automatic setup and code generation -- **Package Identity** - Debug and test by adding package identity without full packaging -- **MSIX Packaging** - App packaging with signing and Store readiness -- **Developer Tools** - Manifests, certificates, assets, and build integration +## Key benefits of WinApp CLI -## Why package identity? +**Create and run WinUI apps from the terminal** + +`winapp new` creates a WinUI app from the official templates, including blank, NavigationView, TabView, and MVVM starters. `winapp run` builds the project, installs the matching Windows App Runtime, and launches the app, whether it's packaged or unpackaged. [Build your first WinUI app](https://learn.microsoft.com/windows/apps/get-started/start-here) + +**Debug with package identity and crash diagnostics** + +Run your app with package identity so you can test notifications, on-device AI, and other APIs that require identity. Add `--debug-output` to capture debug messages and crash dumps. For WinUI crashes, WinApp CLI decodes stowed exceptions to point you at the XAML event handler that failed. [Debugging with package identity](debugging.md) + +**Ground AI coding agents in real WinUI code** + +`winapp find-ui` returns working XAML and C# from the WinUI 3 Gallery and the Windows Community Toolkit. `winapp find-api` inspects the Windows Runtime APIs your project references. Agents use them to generate code from real samples and metadata instead of guessing. [Use WinApp CLI with AI agents](#use-winapp-cli-with-ai-agents) + +**Automate and test your app's UI** + +`winapp ui` inspects and interacts with running apps through UI Automation, and captures screenshots and recordings. Run your app in Windows Sandbox to test it in a clean environment. [UI automation](ui-automation.md) + +**Package, sign, and ship** -Many Windows APIs require your app to have package identity. With identity, your app gains access to features like notifications, OS integration, and on-device AI. For a full list of what package identity unlocks and help choosing the right packaging model, see [Packaging overview](https://learn.microsoft.com/windows/apps/package-and-deploy/packaging/). +`winapp pack` builds your project, packages it as MSIX, and signs it in one step. Generate development certificates locally, sign release builds with Azure Trusted Signing, and install WinApp CLI on GitHub Actions or Azure DevOps runners. [Package your app](usage.md#pack) + +**Bring Windows features to any framework** + +Add the Windows SDK and Windows App SDK, package identity, and MSIX packaging to apps built with .NET, C++, Electron, Flutter, Rust, or Tauri, without changing your build system. [See supported frameworks](#supported-frameworks) + +## Get started with WinUI + +After you [install WinApp CLI](#installation) and the [.NET SDK](https://dotnet.microsoft.com/download), create and run a WinUI app: + +```powershell +winapp new --name MyWinUIApp --template winui-navview --use-defaults +cd MyWinUIApp +winapp run +``` + +When you're ready to test a package locally, generate a development certificate and create a signed MSIX package: + +```powershell +winapp cert generate --manifest ./Package.appxmanifest +winapp pack ./MyWinUIApp.csproj -c Release --cert ./devcert.pfx +``` + +The development certificate uses a default password and is for local testing only. Before you distribute your app, sign it with a trusted certificate, for example with [`winapp az-sign`](usage.md#az-sign). For more information, see [Security](security.md#the-default-password). + +For a step-by-step walkthrough that includes setup and your first UI change, see [Build your first WinUI app](https://learn.microsoft.com/windows/apps/get-started/start-here). To see all available templates, run `winapp new --list`. For the complete workflow, including debugging, UI automation, and packaging, see [Using WinApp CLI with WinUI](guides/winui.md). ## Installation @@ -29,6 +68,8 @@ The easiest way to install the CLI is via WinGet (Windows Package Manager): winget install Microsoft.winappcli --source winget ``` +If you use the WinGet PowerShell module, run `Install-WinGetPackage Microsoft.winappcli` instead. + ### NPM For Electron projects, install via NPM: @@ -59,13 +100,32 @@ Or if using Electron/Node.js: npx winapp --help ``` +## Use WinApp CLI with AI agents + +WinApp CLI is designed to work well with AI coding agents. Commands such as `find-ui` and `find-api` return machine-readable output with `--json`, so an agent can look up real WinUI samples and Windows Runtime APIs before it writes code. + +Install the WinApp CLI plugin to give your agent skills for the WinApp CLI workflow: + +```powershell +# GitHub Copilot CLI +copilot plugin install microsoft/WinAppCli + +# Claude Code +claude plugin marketplace add microsoft/WinAppCli +claude plugin install winappcli@winappcli +``` + +If you work in Visual Studio Code, the [WinApp VS Code extension](https://learn.microsoft.com/windows/apps/develop/ai-assisted/vs-code-tools#winapp-vs-code-extension) runs WinApp CLI commands from the editor and launches your app with package identity when you press **F5**. Install it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=Microsoft-WinAppCLI.winapp). + ## Supported frameworks -winapp CLI works with a variety of app frameworks: +WinApp CLI works with WinUI and other app frameworks: | Framework | Guide | |-----------|-------| +| WinUI | [Get started with WinUI](guides/winui.md) | | .NET / WPF / WinForms | [Get started with .NET](guides/dotnet.md) | +| .NET MAUI | [Get started with .NET MAUI](guides/maui.md) | | C++ (CMake) | [Get started with C++](guides/cpp.md) | | Electron | [Get started with Electron](guides/electron/index.md) | | Rust | [Get started with Rust](guides/rust.md) | @@ -84,23 +144,49 @@ Additional guides: | Category | Commands | |----------|----------| -| **Setup** | [init](usage.md#init), [restore](usage.md#restore), [update](usage.md#update) | -| **Identity & Debugging** | [run](usage.md#run), [create-debug-identity](usage.md#create-debug-identity), [embed-identity](usage.md#embed-identity), [unregister](usage.md#unregister) | +| **Create & set up** | [new](usage.md#new), [init](usage.md#init), [restore](usage.md#restore), [update](usage.md#update) | +| **Run & debug** | [run](usage.md#run), [create-debug-identity](usage.md#create-debug-identity), [embed-identity](usage.md#embed-identity), [unregister](usage.md#unregister) | | **Packaging** | [pack](usage.md#pack) | | **Manifests** | [manifest generate](usage.md#manifest-generate), [manifest update-assets](usage.md#manifest-update-assets), [manifest add-alias](usage.md#manifest-add-alias) | -| **Certificates & Signing** | [cert generate](usage.md#cert-generate), [cert install](usage.md#cert-install), [sign](usage.md#sign), [create-external-catalog](usage.md#create-external-catalog) | +| **Certificates & Signing** | [cert generate](usage.md#cert-generate), [cert install](usage.md#cert-install), [sign](usage.md#sign), [az-sign](usage.md#az-sign), [create-external-catalog](usage.md#create-external-catalog) | +| **Code search for agents** | [find-ui](usage.md#find-ui), [find-api](usage.md#find-api) | +| **UI automation & Sandbox** | [ui](usage.md#ui), [devtools](usage.md#devtools), [target](usage.md#target) | | **Utilities** | [tool](usage.md#tool), [store](usage.md#store), [get-winapp-path](usage.md#get-winapp-path), [config](usage.md#config), [complete](usage.md#shell-completion) | -| **UI Automation** | [ui](usage.md#ui), [devtools](usage.md#devtools) | -| **Node.js/Electron** | [node create-addon](usage.md#node-create-addon), [node add-electron-debug-identity](usage.md#node-add-electron-debug-identity), [node clear-electron-debug-identity](usage.md#node-clear-electron-debug-identity) | +| **Node.js/Electron** | [node create-addon](usage.md#node-create-addon), [node generate-bindings](usage.md#node-generate-bindings), [node add-electron-debug-identity](usage.md#node-add-electron-debug-identity), [node clear-electron-debug-identity](usage.md#node-clear-electron-debug-identity) | For the full CLI reference, see [CLI reference](usage.md). +## Samples + +The [samples folder](https://github.com/microsoft/WinAppCli/tree/main/samples) on GitHub has a runnable project for each supported framework: + +| Sample | Description | +|--------|-------------| +| [WinUI app](https://github.com/microsoft/WinAppCli/tree/main/samples/winui-app) | Packaged WinUI app registered and launched with `winapp run` | +| [WinUI unpackaged app](https://github.com/microsoft/WinAppCli/tree/main/samples/winui-unpackaged-app) | Unpackaged WinUI app launched with `winapp run` | +| [WinUI solution](https://github.com/microsoft/WinAppCli/tree/main/samples/winui-solution) | Multi-project solution (app and test project) that shows how `winapp run` selects the app project | +| [C++ WinUI app](https://github.com/microsoft/WinAppCli/tree/main/samples/cpp-app-winui) | WinUI window built in C++ with CMake, without XAML or MSBuild | +| [WPF app](https://github.com/microsoft/WinAppCli/tree/main/samples/wpf-app) | WPF desktop app | +| [.NET MAUI app](https://github.com/microsoft/WinAppCli/tree/main/samples/maui-app) | .NET MAUI Windows project packaged and signed with WinApp CLI | +| [C++ app](https://github.com/microsoft/WinAppCli/tree/main/samples/cpp-app) | Native C++ Win32 app built with CMake | +| [Electron](https://github.com/microsoft/WinAppCli/tree/main/samples/electron) | Electron Forge app with a manifest, assets, and native C++ and C# addons | +| [Rust app](https://github.com/microsoft/WinAppCli/tree/main/samples/rust-app) | Rust app that calls Windows APIs | +| [Tauri app](https://github.com/microsoft/WinAppCli/tree/main/samples/tauri-app) | Tauri app with a Rust backend | +| [Flutter app](https://github.com/microsoft/WinAppCli/tree/main/samples/flutter-app) | Flutter desktop app with package identity and the Windows App SDK | +| [Sparse app](https://github.com/microsoft/WinAppCli/tree/main/samples/sparse-app) | WPF app with sparse packaging (identity-only MSIX) and an installer | + +## Why package identity? + +Many Windows APIs require your app to have package identity. With identity, your app gains access to features like notifications, OS integration, and on-device AI. WinUI app templates include a package manifest, so `winapp run` gives them identity by default. For a full list of what package identity unlocks and help choosing the right packaging model, see [Packaging overview](https://learn.microsoft.com/windows/apps/package-and-deploy/packaging/). + ## Open source -winapp CLI is open source. You can find the source code, file issues, and contribute on [GitHub](https://github.com/microsoft/WinAppCli). +WinApp CLI is open source. You can find the source code, file issues, and contribute on [GitHub](https://github.com/microsoft/WinAppCli). For help, see [Support](https://github.com/microsoft/WinAppCli/blob/main/SUPPORT.md). ## Related topics +- [Build your first WinUI app](https://learn.microsoft.com/windows/apps/get-started/start-here) +- [WinUI overview](https://learn.microsoft.com/windows/apps/winui/winui3/) - [CLI reference](usage.md) - [Debugging with package identity](debugging.md) - [Security guidance](security.md) @@ -108,6 +194,5 @@ winapp CLI is open source. You can find the source code, file issues, and contri - [Windows Sandbox execution](sandbox-execution.md) - [NPM programmatic API](npm-usage.md) - [Framework guides](guides/dotnet.md) -- [Get started with Electron](guides/electron/index.md) - [Windows App SDK documentation](/windows/apps/windows-app-sdk/) - [MSIX packaging documentation](/windows/msix/) diff --git a/docs/guides/winui.md b/docs/guides/winui.md new file mode 100644 index 000000000..501f7ba3a --- /dev/null +++ b/docs/guides/winui.md @@ -0,0 +1,180 @@ + + + +# Using WinApp CLI with WinUI + +This guide shows how to use WinApp CLI across the full inner loop of a WinUI 3 app: create a project from an official template, build and launch it with package identity, debug crashes, find controls and APIs, automate the UI, and produce a signed MSIX package. Every step runs from the command line, so it works in any editor, in CI, and with AI coding agents. + +WinUI project templates already include a `Package.appxmanifest`, so you don't need to run `winapp init` for a WinUI app. If you're adding package identity to an existing .NET app that doesn't use WinUI, see [Using WinApp CLI with .NET](dotnet.md) instead. + +## Prerequisites + +- Windows 10 version 1809 or later, or Windows 11. +- The [.NET SDK](https://dotnet.microsoft.com/download), version 8.0.100 or later. The experimental Reactor templates require the .NET 10 SDK. WinApp CLI doesn't install toolchains, so `winapp new` and `winapp run` stop with guidance if the .NET SDK is missing. +- WinApp CLI: + + ```powershell + winget install Microsoft.winappcli --source winget + ``` + +- [Developer Mode](https://learn.microsoft.com/windows/advanced-settings/developer-mode), which Windows requires to register the app from your build output. Turn it on in **Settings > System > For developers**. For what this changes on your machine, see [Security](../security.md#developer-mode). + +## Create a WinUI app + +`winapp new` scaffolds a WinUI app from the official `Microsoft.WindowsAppSDK.WinUI.CSharp.Templates` pack. It installs or updates the template pack on demand and then calls `dotnet new` for you. + +```powershell +# Pick a template and a name interactively +winapp new + +# Or create a NavigationView app without prompts +winapp new --name MyApp --template winui-navview --use-defaults +``` + +Run `winapp new --list` to see the templates in the installed pack. The pack includes these templates: + +| Template | Description | +|----------|-------------| +| `winui` | Minimal blank XAML app (default). [See screenshot](https://learn.microsoft.com/windows/apps/dev-tools/visual-studio#winui-blank-app-packaged) | +| `winui-navview` | XAML app with a NavigationView shell. [See screenshot](https://learn.microsoft.com/windows/apps/dev-tools/visual-studio#winui-navigation-app) | +| `winui-tabview` | XAML app with a TabView shell. [See screenshot](https://learn.microsoft.com/windows/apps/dev-tools/visual-studio#winui-tabview-app) | +| `winui-mvvm` | XAML app that uses the MVVM pattern with CommunityToolkit.Mvvm. [See screenshot](https://learn.microsoft.com/windows/apps/dev-tools/visual-studio#winui-mvvm-app) | +| `winui-lib` | WinUI class library | +| `winui-unittest` | Packaged MSTest project for WinUI unit tests | +| `reactor`, `reactor-mvu`, `reactor-navview`, `reactor-tabview` | Experimental. WinUI apps written in C# only, with no XAML | + +> [!NOTE] +> The Reactor templates reference prerelease `Microsoft.UI.Reactor` packages. Their APIs can change or be removed in a future release. + +For every option, see the [`new` command reference](../usage.md#new). + +## Build and run with identity + +From the project folder, `winapp run` builds the project, installs the Windows App SDK runtime that matches your architecture if it's missing, registers the app with package identity, and launches it. + +```powershell +cd MyApp +winapp run +``` + +`winapp run` accepts a project file, a solution file, a folder that contains one of them, or a folder of build output: + +```powershell +# A specific project and configuration +winapp run .\MyApp.csproj -c Release --arch arm64 + +# A solution: WinApp CLI finds the single app project and skips libraries and tests +winapp run .\MySolution.sln + +# A solution with more than one app project +winapp run .\MySolution.sln --project MyApp + +# Build output that you produced yourself +winapp run .\bin\x64\Debug\net10.0-windows10.0.26100.0\win-x64 +``` + +WinApp CLI reads the project's `WindowsPackageType` property to decide how to launch it. A packaged project runs with package identity. A project that sets `WindowsPackageType` to `None` runs as an unpackaged app without identity. To run a packaged project as unpackaged, pass the property on the command line: + +```powershell +winapp run -p WindowsPackageType=None +``` + +Other useful options include `--clean` to remove the previous registration and the app's saved data (LocalState and settings) for a fresh first run, `--no-launch` to register without starting the app, and `--detach --json` to return the process ID and exit so that scripts and agents can keep working while the app runs. For the full list, see [Project mode (.NET SDK projects)](../usage.md#project-mode-net-sdk-projects). + +### Use dotnet run instead + +If you prefer `dotnet run`, use the `Microsoft.Windows.SDK.BuildTools.WinApp` NuGet package. The package hooks `dotnet run` so that it calls `winapp run` and launches the app with identity. Projects that you create with `winapp new` already reference the package, so `dotnet run` works without extra setup. For other projects, add the package first: + +```powershell +dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease +dotnet run +``` + +You can pass `winapp run` options as `WinAppRun*` MSBuild properties, for example `dotnet run -p:WinAppRunDebugOutput=true`. To turn off the integration, set `EnableWinAppRunSupport` to `false` in the project file. For details, see [dotnet run support](../dotnet-run-support.md). + +## Debug crashes + +Add `--debug-output` to capture `OutputDebugString` messages and first-chance exceptions while the app runs. When a WinUI app fails with a stowed exception, WinApp CLI analyzes the crash dump and prints the original error and call stack instead of a generic failure code. + +```powershell +winapp run --debug-output +``` + +Add `--symbols` to download symbols for full native function names. Because `--debug-output` attaches WinApp CLI as the debugger, you can't attach Visual Studio or another debugger to the same process. To debug with your IDE instead, see [Debugging with WinApp CLI](../debugging.md). For details about the stowed-exception analysis, see [WinUI stowed-exception triage](../debugging.md#winui-stowed-exception-triage). + +## Find controls and APIs + +`winapp find-ui` searches XAML and C# samples from WinUI Gallery and the Windows Community Toolkit by intent, and returns the code for a scenario that you pick. `winapp find-api` searches the Windows and WinRT API surface that your project references, such as Windows App SDK and Windows SDK types, members, and enums. + +```powershell +# Find a control by what you want to build +winapp find-ui "tabbed layout" + +# Get the XAML and C# for one of the returned scenarios +winapp find-ui --id gallery-tabview-1 + +# Look up an API +winapp find-api NavigationView +``` + +Both commands support `--json`, so AI coding agents can use them to choose controls and verify API names. For more information, see the [`find-ui`](../usage.md#find-ui) and [`find-api`](../usage.md#find-api) references. + +## Automate and verify the UI + +`winapp ui` drives a running app through Microsoft UI Automation. Use it to inspect the element tree, invoke controls, wait for state changes, and take screenshots. Agents can use the same commands to check their own changes. + +```powershell +winapp run --detach +winapp ui inspect -a MyApp +winapp ui search Button -a MyApp +winapp ui invoke PART_PaneToggleButton -a MyApp +winapp ui screenshot -a MyApp +``` + +The `PART_PaneToggleButton` selector targets the menu button in the `winui-navview` template. For your own controls, copy a selector from the output of `winapp ui inspect` or `winapp ui search`. + +To run the app in Windows Sandbox instead of on your desktop, add `--on sandbox` to `winapp run` and `winapp ui`. For more information, see [UI automation](../ui-automation.md) and [Sandbox execution](../sandbox-execution.md). + +## Package and sign + +When you're ready to test a package locally, generate a development certificate whose publisher matches your manifest, and then build and package the project in one step: + +```powershell +winapp cert generate --manifest .\Package.appxmanifest +winapp pack .\MyApp.csproj -c Release --arch x64 --cert .\devcert.pfx +``` + +`winapp pack` builds the project and produces a signed `.msix`. To combine builds for several architectures into one `.msixbundle`, see [Multi-architecture bundles](../usage.md#multi-architecture-bundles). The project must be packaged, so a project that sets `WindowsPackageType` to `None` can't be packed. For WinUI projects, the Windows App SDK build owns the manifest, the entry point, and resource generation, so `--manifest`, `--executable`, and `--skip-pri` aren't accepted. + +The development certificate is for local testing only, and it uses a default password. Before you distribute your app, sign it with a trusted certificate, for example with [`winapp az-sign`](../usage.md#az-sign) and Azure Trusted Signing. For more information, see [Packaging a project directly](../usage.md#packaging-a-project-directly) and [Security](../security.md#the-default-password). + +## Existing WinUI projects + +WinApp CLI works with WinUI projects that you created in Visual Studio. Point `winapp run` at the project file, the solution file, or the folder that contains one. For `winapp pack`, pass the `.csproj`. You can keep building and debugging in Visual Studio and use WinApp CLI for scripts, CI, and agent workflows. + +## WinUI with C++ + +`winapp run` also builds and launches C++/WinRT WinUI projects (`.vcxproj`) that you created from the Visual Studio **WinUI Blank App (Packaged)** template. It builds the project with Visual Studio's MSBuild, registers the app with package identity, and launches it: + +```powershell +winapp run .\MyApp.vcxproj + +# Or from the folder that contains the project +winapp run . +``` + +C++ projects need Visual Studio or Build Tools for Visual Studio with the **Desktop development with C++** workload and **C++ WinUI app development tools**. `winapp pack` doesn't build `.vcxproj` projects, so create the MSIX package in Visual Studio. For prerequisites and options, see [C++ projects (.vcxproj)](../usage.md#c-projects-vcxproj). For C++ apps that don't use WinUI, see [Using WinApp CLI with C++](cpp.md). + +## Samples + +- [`winui-app`](../../samples/winui-app): a packaged WinUI app with controls set up for `winapp ui` automation +- [`winui-unpackaged-app`](../../samples/winui-unpackaged-app): a WinUI app that runs without package identity +- [`winui-solution`](../../samples/winui-solution): a multi-project solution that shows how `winapp run` picks the app project +- [`cpp-winui-app`](../../samples/cpp-winui-app): a packaged C++/WinRT WinUI app (Visual Studio `.vcxproj` with XAML) that runs with `winapp run` + +## Next steps + +- [Get started with WinUI](https://learn.microsoft.com/windows/apps/get-started/start-here) +- [WinApp CLI command reference](../usage.md) +- [Debugging with WinApp CLI](../debugging.md) +- [UI automation](../ui-automation.md) diff --git a/scripts/port-mslearn-docs.ps1 b/scripts/port-mslearn-docs.ps1 index 74969eeee..66f03a982 100644 --- a/scripts/port-mslearn-docs.ps1 +++ b/scripts/port-mslearn-docs.ps1 @@ -486,15 +486,15 @@ if ($portedIndexContent -match '(?ms)(## Supported frameworks\s*\n.+?)(?=\n## )' # Build guides/index.md using the extracted content $guidesIndex = @" --- -title: winapp CLI framework guides -description: Step-by-step guides for using the winapp CLI with .NET, C++, Electron, Rust, Tauri, Flutter, and other frameworks. +title: WinApp CLI framework guides +description: Step-by-step guides for using the WinApp CLI with WinUI, .NET, .NET MAUI, C++, Electron, Rust, Tauri, Flutter, and other frameworks. ms.date: $msDate ms.topic: overview --- # Framework guides -These guides walk you through using the winapp CLI with your app framework — from project setup to debugging with package identity to packaging as MSIX. +These guides walk you through using the WinApp CLI with your app framework — from project setup to debugging with package identity to packaging as MSIX. "@ @@ -548,10 +548,11 @@ Write-Info " Generated guides/index.md" # under the winapp-cli node — pages are only reachable via "Related topics". This # step emits the child TOC so every ported page appears in the left-hand nav. # -# NOTE: The *parent* dev-tools TOC in MicrosoftDocs/windows-dev-docs-pr must branch -# into this file, e.g.: -# - name: winapp CLI -# href: winapp-cli/toc.yml +# NOTE: The parent Tools TOC in MicrosoftDocs/windows-dev-docs-pr +# (hub/apps/tools/toc.yml) includes this file so the pages render inside the +# existing Tools navigation instead of a separate, standalone TOC: +# - name: WinApp CLI +# href: ../dev-tools/winapp-cli/toc.yml # That one-time edit lives in the docs repo (outside the winapp-cli folder this # script writes) and is not something the port script can generate. @@ -560,13 +561,14 @@ Write-Step "Generating toc.yml" # Curated left-nav labels keyed by output-relative path. Anything ported but not # listed here falls back to its H1 title (and is flagged so a maintainer can add it). $TocLabels = [ordered]@{ - "index.md" = "winapp CLI overview" + "index.md" = "Overview" "usage.md" = "Commands and usage" "debugging.md" = "Debugging with package identity" "ui-automation.md" = "UI Automation" "sandbox-execution.md" = "Windows Sandbox execution" "security.md" = "Security guidance" "guides/index.md" = "Framework guides" + "guides/winui.md" = "WinUI" "guides/dotnet.md" = ".NET / WPF / WinForms" "guides/dotnet-file-based.md" = ".NET file-based apps" "guides/maui.md" = ".NET MAUI" @@ -610,9 +612,9 @@ function Get-PortedTitle { } function New-TocNode { - param([string]$Href, [object[]]$Items = @()) + param([string]$Href, [object[]]$Items = @(), [switch]$Expanded) $name = if ($TocLabels.Contains($Href)) { $TocLabels[$Href] } else { Get-PortedTitle $Href } - return @{ Name = $name; Href = $Href; Items = $Items } + return @{ Name = $name; Href = $Href; Items = $Items; Expanded = [bool]$Expanded } } function ConvertTo-TocLines { @@ -624,14 +626,22 @@ function ConvertTo-TocLines { Write-Warn " Skipping TOC entry for un-ported file: $($node.Href)" continue } - $lines.Add("$pad- name: $(Format-MsLearnYamlValue $node.Name)") - $lines.Add("$pad href: $($node.Href)") + $childLines = @() if ($node.Items -and $node.Items.Count -gt 0) { $childLines = ConvertTo-TocLines -Nodes $node.Items -Indent ($Indent + 2) - if ($childLines.Count -gt 0) { - $lines.Add("$pad items:") - foreach ($cl in $childLines) { $lines.Add($cl) } - } + } + $lines.Add("$pad- name: $(Format-MsLearnYamlValue $node.Name)") + if ($childLines.Count -gt 0) { + # Learn repeats a parent's own name as its first child when the parent + # has an href, so emit a name-only parent with an explicit "Overview" child. + if ($node.Expanded) { $lines.Add("$pad expanded: true") } + $lines.Add("$pad items:") + $lines.Add("$pad - name: Overview") + $lines.Add("$pad href: $($node.Href)") + foreach ($cl in $childLines) { $lines.Add($cl) } + } + else { + $lines.Add("$pad href: $($node.Href)") } } return , $lines.ToArray() @@ -656,7 +666,8 @@ $tocTree = @( (New-TocNode "ui-automation.md") (New-TocNode "sandbox-execution.md") (New-TocNode "security.md") - (New-TocNode "guides/index.md" @( + (New-TocNode "guides/index.md" -Expanded @( + (New-TocNode "guides/winui.md") (New-TocNode "guides/dotnet.md") (New-TocNode "guides/dotnet-file-based.md") (New-TocNode "guides/maui.md") diff --git a/scripts/tests/validate-mslearn-docs.Tests.ps1 b/scripts/tests/validate-mslearn-docs.Tests.ps1 index ddfd53492..31a49d86c 100644 --- a/scripts/tests/validate-mslearn-docs.Tests.ps1 +++ b/scripts/tests/validate-mslearn-docs.Tests.ps1 @@ -230,7 +230,7 @@ Describe 'port-mslearn-docs: generated toc.yml + guides index' { } It 'lists the overview as the first entry' { - $script:Toc | Should -Match '(?m)^- name: winapp CLI overview' + $script:Toc | Should -Match '(?m)^- name: Overview\r?\n href: index\.md' } It 'nests the Electron guides under the Framework guides subtree' {