将 winapp CLI 与 WinUI 配合使用

本指南演示如何在 WinUI 3 应用的完整内部循环中使用 winapp CLI：从官方模板创建项目、使用包标识生成和启动项目、调试崩溃、查找控件和 API、自动执行 UI 并生成已签名的 MSIX 包。 每个步骤都从命令行运行，因此它适用于任何编辑器、CI 和 AI 编码代理。

WinUI 项目模板已包含一个 Package.appxmanifest，因此无需为 WinUI 应用运行 winapp init 。 如果要将包标识添加到不使用 WinUI 的现有 .NET 应用，请改为参阅将 winapp CLI 与 .NET 配合使用。

Prerequisites

  • Windows 10版本 1809 或更高版本，或Windows 11。

  • .NET SDK 版本 8.0.100 或更高版本。 实验性 Reactor 模板需要 .NET 10 SDK。 winapp CLI 不安装工具链，因此，如果缺少 .NET SDK，winapp new 和 winapp run 会停止并提供指导。

  • winapp CLI：

    winget install Microsoft.winappcli --source winget

  • 开发人员模式，这是 Windows 从生成输出注册应用必需使用的模式。 在设置 > 系统 > 开发者选项中打开它。 有关这会对您的计算机造成哪些更改，请参阅 “安全性”。

创建 WinUI 应用

winapp new 从官方 Microsoft.WindowsAppSDK.WinUI.CSharp.Templates 包搭建 WinUI 应用基架。 它按需安装或更新模板包，然后为你调用 dotnet new 。

# 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

运行 winapp new --list 以查看已安装包中的模板。 该包包含以下模板：

Template 描述
winui 最小空白 XAML 应用（默认值）。 请参阅屏幕截图
winui-navview 具有 NavigationView shell 的 XAML 应用。 请参阅屏幕截图
winui-tabview 具有 TabView shell 的 XAML 应用。 请参阅屏幕截图
winui-mvvm 将 MVVM 模式与 CommunityToolkit.Mvvm 配合使用的 XAML 应用。 请参阅屏幕截图
winui-lib WinUI 类库
winui-unittest WinUI 单元测试的打包 MSTest 项目
reactor、reactor-mvu、reactor-navview、reactor-tabview 实验的。 仅使用 C# 编写的 WinUI 应用，不带 XAML

Note

Reactor 模板引用预发行版 Microsoft.UI.Reactor 包。 其 API 可以在将来的版本中更改或删除。

有关每个选项，请参阅 new 命令参考。

使用标识构建和运行

在项目文件夹中，winapp run生成项目，安装与体系结构匹配的Windows 应用 SDK运行时（如果缺少该运行时）、使用包标识注册应用并启动它。

cd MyApp
winapp run

winapp run 接受项目文件、解决方案文件、包含其中一个文件的文件夹或生成输出的文件夹：

# 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 读取项目的 WindowsPackageType 属性，以确定如何启动它。 打包项目使用包标识运行。 将WindowsPackageType设置为None的项目在没有标识的情况下作为未打包的应用运行。 若要以未打包方式运行打包项目，请在命令行上传递属性：

winapp run -p WindowsPackageType=None

其他有用的选项包括：--clean 用于删除先前的注册以及应用保存的数据（LocalState 和设置），以便进行一次全新的首次运行；--no-launch 用于注册但不启动应用；--detach --json 用于返回进程 ID 并退出，以便脚本和智能体可以在应用运行时继续工作。 有关完整列表，请参阅Project模式（.NET SDK 项目）。

请改用 dotnet run

如果你更偏好使用 dotnet run，请使用 Microsoft.Windows.SDK.BuildTools.WinApp NuGet 包。 该包挂接到 dotnet run，以便调用 winapp run 并通过标识启动应用。 你使用 winapp new 创建的项目已引用该包，因此 dotnet run 无需额外设置即可工作。 对于其他项目，请先添加包：

dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease
dotnet run

你可以将 dotnet run -p:WinAppRunDebugOutput=true 选项作为 WinAppRun* MSBuild 属性传递，例如 winapp run。 若要关闭集成，请在项目文件中将 EnableWinAppRunSupport 设置为 false。 有关详细信息，请参阅 dotnet 运行支持。

调试崩溃

添加 --debug-output 以捕获 OutputDebugString 消息，并在应用运行时捕获首次机会异常。 当 WinUI 应用失败并出现存放异常时，winapp CLI 会分析故障转储并输出原始错误和调用堆栈，而不是泛型故障代码。

winapp run --debug-output

添加 --symbols 以下载完整本机函数名称的符号文件。 由于--debug-output将 winapp CLI 附加为调试器，因此无法将Visual Studio或其他调试器附加到同一进程。 若要改用 IDE 进行调试，请参阅 使用 winapp CLI 进行调试。 有关存放异常分析的详细信息，请参阅 WinUI 存放异常分类。

查找控件和 API

winapp find-ui按意向搜索 WinUI Gallery 和 Windows Community Toolkit 中的 XAML 和 C# 示例，并返回所选方案的代码。 winapp find-api搜索项目引用的 Windows 和 WinRT API 接口面，例如 Windows 应用 SDK 和 Windows SDK 类型、成员和枚举。

# 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

这两个命令都支持 --json，因此 AI 编码代理可以使用它们来选择控件并验证 API 名称。 有关详细信息，请参阅 find-ui 和 find-api 引用。

自动执行并验证 UI

winapp ui通过Microsoft UI 自动化驱动正在运行的应用。 使用它来检查元素树、调用控件、等待状态更改并获取屏幕截图。 代理可以使用相同的命令来检查自己的更改。

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

PART_PaneToggleButton选择器以模板中的winui-navview菜单按钮为目标。 对于自己的控件，请从 winapp ui inspect 或 winapp ui search 的输出中复制选择器。

若要在 Windows 沙盒中而不是在桌面上运行该应用，请将winapp run添加到winapp ui和--on sandbox。 有关详细信息，请参阅 UI 自动化 和 沙盒执行。

打包和签名

准备好在本地测试包时，生成发布者与清单匹配的开发证书，然后在一个步骤中生成并打包项目：

winapp cert generate --manifest .\Package.appxmanifest
winapp pack .\MyApp.csproj -c Release --arch x64 --cert .\devcert.pfx

winapp pack 构建项目并生成已签名的 .msix。 若要将多个体系结构的生成合并为一个 .msixbundle，请参阅 多体系结构捆绑包。 项目必须打包，因此将 WindowsPackageType 设置为 None 的项目无法打包。 对于 WinUI 项目，Windows 应用 SDK 生成过程负责清单、入口点和资源生成，因此不接受 --manifest、--executable 和 --skip-pri。

开发证书仅用于本地测试，并且使用默认密码。 在分发应用之前，请使用受信任的证书对其进行签名，例如使用winapp az-sign和Azure 受信任签名。 有关详细信息，请参阅直接打包项目和安全。

现有 WinUI 项目

winapp CLI 适用于在Visual Studio中创建的 WinUI 项目。 将 winapp run 指向项目文件、解决方案文件或包含其中一个文件的文件夹。 对于 winapp pack，传递 .csproj。 可以在 Visual Studio 中继续构建和调试，并将 winapp CLI 用于脚本、CI 和代理工作流。

使用 C++ 的 WinUI

winapp run 还生成并启动你通过 Visual Studio WinUI 空白应用（打包）模板创建的 C++/WinRT WinUI 项目 (.vcxproj)。 它使用 Visual Studio 的 MSBuild 生成项目，使用包标识注册应用并启动它：

winapp run .\MyApp.vcxproj

# Or from the folder that contains the project
winapp run .

C++ 项目需要 Visual Studio 或适用于 Visual Studio 的生成工具，以及 桌面开发（使用 C++）工作负载和 C++ WinUI 应用开发工具。 winapp pack不会生成.vcxproj项目，因此请在Visual Studio中创建 MSIX 包。 有关先决条件和选项，请参阅 C++ 项目（.vcxproj）。 对于不使用 WinUI 的 C++ 应用，请参阅 将 winapp CLI 与 C++ 配合使用。

示例

  • winui-app：一个为 winapp ui 自动化设置了控件的打包 WinUI 应用
  • winui-unpackaged-app：在没有包标识的情况下运行的 WinUI 应用
  • winui-solution：显示 winapp run 如何选择应用项目的多项目解决方案
  • cpp-winui-app：打包的 C++/WinRT WinUI 应用（Visual Studio .vcxproj，带 XAML），通过 winapp run 运行

后续步骤

  • 上次更新时间为