CLI 文档和用法

Shell 完成

为命令、选项和值启用选项卡完成。 有关设置说明，请参阅 Shell 完成指南 。

# Quick setup for PowerShell (permanent — add to profile)
winapp complete --setup powershell >> $PROFILE

# Or try it in the current session only
winapp complete --setup powershell | Out-String | Invoke-Expression

初始化

使用 Windows SDK、Windows 应用 SDK 以及新式 Windows 开发所需的资源来初始化目录。

winapp init [base-directory] [options]

参数：

  • base-directory - 应用/工作区的基/根目录（默认值：当前目录）

选项：

  • --config-dir <path> - 要读取/存储配置的目录（默认值：当前目录）
  • --setup-sdks - SDK 安装模式：“stable”（默认值）、“预览”、“实验”或“none”（跳过 SDK 安装）
  • --ignore-config， --no-config - 不要将配置文件用于版本管理
  • --no-gitignore - 不更新 .gitignore 文件
  • --use-defaults， --no-prompt - 不提示并使用所有提示的默认值
  • --config-only - 仅处理配置文件操作，跳过包安装

功能：

  • winapp.yaml创建配置文件（仅当管理 SDK 包时;跳过时--setup-sdks none）
  • 下载 Windows SDK 和 Windows 应用 SDK 包
  • 生成 C++/WinRT 标头和二进制文件
  • 创建 Package.appxmanifest
  • 设置生成工具并启用开发人员模式
  • 更新 .gitignore 以排除生成的文件
  • 将可共享文件存储在全局缓存目录中

自动 .NET 项目检测：

在目标目录中找到 .csproj 文件时，init 使用简化的 .NET 特定流程：

  • 验证并更新与Windows兼容的 TFM 的 TargetFramework（例如，net10.0-windows10.0.26100.0）
  • 直接在 Microsoft.WindowsAppSDK 中将 Microsoft.Windows.SDK.BuildTools 和 PackageReference 添加为 NuGet .csproj 条目。
  • 生成Package.appxmanifest、资产和开发证书
  • 不创建winapp.yaml或下载 C++ 投射（请使用 dotnet restore 处理 NuGet 包）

示例：

# Initialize current directory
winapp init

# Initialize with experimental packages
winapp init --setup-sdks experimental

# Initialize specific directory without prompts
winapp init ./my-project --use-defaults

# Initialize a .NET project (auto-detected from .csproj)
cd my-dotnet-app
winapp init

提示：在初始设置后安装 SDK

如果使用（或跳过的 SDK 安装）运行 init--setup-sdks none ，以后需要 SDK：

# Re-run init to install SDKs - preserves existing files (manifest, etc.)
winapp init --use-defaults --setup-sdks stable

使用 --setup-sdks preview 或 --setup-sdks experimental 用于预览/实验版 SDK 版本。

恢复

根据现有 winapp.yaml 配置还原包并重新生成文件。

winapp restore [options]

选项：

  • --config-dir <path> - 包含 winapp.yaml 的目录（默认值：当前目录）

功能：

  • 读取现有 winapp.yaml 配置
  • 将 SDK 包下载/更新到指定版本
  • 重新生成 C++/WinRT 标头和二进制文件
  • 将可共享文件存储在全局缓存目录中

注释

对于使用 winapp init 初始化的.NET项目，没有 winapp.yaml。 请使用 dotnet restore 来还原 NuGet 包。

示例：

# Restore from winapp.yaml in current directory
winapp restore

更新

将包更新到其最新版本并更新配置文件。

winapp update [options]

选项：

  • --setup-sdks <stable|preview|experimental|none>- SDK 安装模式： stable （默认）、preview或 experimentalnone （跳过 SDK 安装）

功能：

  • 读取当前目录中的现有 winapp.yaml 配置
  • 将所有包更新到其最新可用版本
  • 使用新的版本号更新winapp.yaml文件
  • 重新生成 C++/WinRT 标头和二进制文件

示例：

# Update packages to latest versions
winapp update

# Update including experimental packages
winapp update --setup-sdks experimental

pack

从准备好的应用程序目录创建 MSIX 包。 要求清单文件（Package.appxmanifest 首选， appxmanifest.xml 也受支持）存在于目标目录中、当前目录中或随选项一起 --manifest 传递。 （运行 init 或 manifest generate 创建清单）

winapp pack <input-folder> [options]

参数：

  • input-folder - 包含要打包的应用程序文件的目录

选项：

  • --output <filename>- 输出 MSIX 文件名（默认值：<name>_<version>_<arch>.msix、回退到<name>_<version>.msix或<name>_<arch>.msix<name>.msix无法确定版本/拱形时）
  • --name <name> - 包名称（默认值：清单中）
  • --manifest <path> - 清单文件的路径（Package.appxmanifest 首选， appxmanifest.xml 也受支持;默认值：自动检测）
  • --cert <path> - 签名证书的路径（启用自动签名）
  • --cert-password <password> - 证书密码（默认值：“password”）
  • --generate-cert - 生成新的开发证书
  • --install-cert - 将证书安装到计算机
  • --publisher <name> - 证书生成Publisher名称
  • --self-contained - 捆绑Windows 应用 SDK运行时
  • --skip-pri - 跳过 PRI 文件生成
  • --executable <path> - 相对于输入文件夹的可执行文件的路径（也 --exe）。 用于解析 $targetnametoken$ 清单文件中的占位符。

功能：

  • 验证并处理 Package.appxmanifest 文件
  • $placeholder$解析清单中的令牌（请参阅下面的清单占位符）
  • 确保合理的框架依赖项
  • 使用注册信息更新并行清单
  • 自动发现第三方 WinRT 组件并注册其可激活类（请参阅下面的 WinRT 组件发现 ）
  • 处理独立 WinAppSDK 部署
  • 如果提供证书，请对包进行签名

WinRT 组件发现

打包时，winapp pack自动扫描在或*.csproj针对第三方 WinRT 组件（例如 Win2D）中winapp.yaml定义的 NuGet 包。 它分析 .winmd 文件以提取可激活的类名并查找其实现 DLL。 发现的条目注册如下：

  • 依赖于框架的类（默认值）：可激活类作为条目添加到<InProcessServer>Package.appxmanifest
  • 自包含 类：--self-contained可激活类嵌入可执行文件中的并行清单（SxS）

打包期间的占位符分辨率：

如果清单包含在 $targetnametoken$ 属性中 Executable ：

  1. 如果 --executable 提供（相对于输入文件夹的路径），则占位符将替换为指定的值
  2. 否则， winapp pack 扫描输入文件夹根 .exe 文件 - 如果正好找到一个文件，则会自动使用它
  3. 如果找到零个或多个 .exe 文件，则会显示一个错误，要求你指定 --executable

示例：

# Package directory with auto-detected manifest
winapp pack ./dist

# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx

# Package with generated and installed certificate and self-contained WinAppSDK runtime
winapp pack ./dist --generate-cert --install-cert --self-contained

# Package with explicit executable (resolves $targetnametoken$ in manifest)
winapp pack ./dist --executable MyApp.exe

创建调试身份

使用 稀疏打包创建用于调试的应用标识。 exe 保留在其原始位置 ， Windows通过 Add-AppxPackage -ExternalLocation 将其与它相关联。

何时使用此与winapp run：当 create-debug-identity exe 与应用代码（例如位于何处electron.exenode_modules的 Electron 应用）分开时使用，或专门测试稀疏包行为时使用。 对于大多数可执行文件位于生成输出文件夹中的框架，请改用 winapp run — 它注册完整的松散布局包并启动应用。 有关完整比较，请参阅 调试指南 。

winapp create-debug-identity [entrypoint] [options]

参数：

  • entrypoint - 可执行文件（.exe）或需要标识的脚本的路径

选项：

  • --manifest <path> - 应用清单文件的路径（ Package.appxmanifestappxmanifest.xml 默认值：自动检测 Package.appxmanifest 或 appxmanifest.xml 当前目录中）
  • --no-install - 创建后不要安装包
  • --keep-identity - 保留清单标识 as-is，而不追加 .debug 到包名称和应用程序 ID

功能：

  • 修改可执行文件的并行清单
  • 为身份注册稀疏包
  • 启用对需要身份验证的 API 进行调试

示例：

# Add identity to executable using local manifest
winapp create-debug-identity ./bin/MyApp.exe

# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml

# Create identity for hosted app script
winapp create-debug-identity app.py

清单

生成和管理 Package.appxmanifest 文件。

清单生成

从模板生成 Package.appxmanifest。

winapp manifest generate [directory] [options]

参数：

  • directory - 要在其中生成清单的目录（默认值：当前目录）

选项：

  • --package-name <name> - 包名称（默认值：文件夹名称）
  • --publisher-name <name> - Publisher CN （默认值： CN=<current 用户>）
  • --version <version> - 版本（默认值：“1.0.0.0”）
  • --description <text> - 说明（默认值：“我的应用程序”）
  • --entrypoint <path> - 入口点可执行文件或脚本
  • --template <type> - 模板类型： packaged （默认值） 或 sparse
  • --logo-path <path> - 徽标图像文件的路径
  • --if-exists <Error|Overwrite|Skip> - 当清单文件已存在于目标路径（默认值： Error） 时的行为

模板：

清单占位符

生成的清单使用 $placeholder$ 标记，这些标记在打包时由美元符号分隔并自动解析。

占位符 已解析为 示例
$targetnametoken$ 不带扩展名的可执行文件名称 Executable="$targetnametoken$.exe" → Executable="MyApp.exe"
$targetentrypoint$ Windows.FullTrustApplication 始终自动解决

这遵循Visual Studio项目模板使用的相同约定，因此清单可移植到工具中。

如何解析占位符：

  • winapp pack — 在打包过程中， $targetnametoken$ 使用 --executable 选项或自动检测输入文件夹中的单个 .exe 来解析。 如果找到多个（或零） .exe 文件且 --executable 未指定，则会显示错误。
  • winapp create-debug-identity — 提供入口点参数时， $targetnametoken$ 将从中解析。 如果没有入口点，必须在清单中解析可执行占位符。
  • winapp manifest generate --executable - 提供时 --executable ，清单元数据（版本、说明）和图标将从可执行文件中提取，但生成的清单仍使用 $targetnametoken$.exe;稍后会解析此占位符（例如 winapp pack 或 winapp create-debug-identity）。

PS：在签入清单中保留 $targetnametoken$可避免硬编码可执行文件名称，并且适用于 winapp pack 和Visual Studio内部版本。

示例：

# Generate standard manifest interactively
winapp manifest generate

# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite

manifest add-alias

将执行别名 （uap5:AppExecutionAlias） 添加到 Package.appxmanifest。 这允许通过键入别名从命令行启动打包的应用。

winapp manifest add-alias [options]

选项：

  • --name <alias> - 别名（例如 myapp.exe）。 默认值：从 Executable 清单中的属性推断。
  • --manifest <path> - Package.appxmanifest 的路径（默认值：搜索当前目录）
  • --app-id <id> - 将别名添加到的应用程序 ID（默认值：第一个应用程序元素）

功能：

  • 读取清单并从属性推断别名 Executable （保留类似 $targetnametoken$.exe占位符）
  • uap5添加命名空间声明（如果尚不存在）
  • 在目标 Application 元素中添加一<uap5:AppExecutionAlias>个<Extensions>块
  • 如果该别名已存在，请报告该别名并成功退出

示例：

# Add alias inferred from Executable attribute (e.g. $targetnametoken$.exe)
winapp manifest add-alias

# Add alias with explicit name
winapp manifest add-alias --name myapp.exe

# Add alias to specific manifest
winapp manifest add-alias --manifest ./dist/Package.appxmanifest

清单 更新资源

从单个源映像生成所有必需的 MSIX 映像资产。

winapp manifest update-assets <image-path> [options]

参数：

  • image-path - 源图像文件的路径（PNG、JPG、SVG、ICO、GIF、BMP 等）

选项：

  • --manifest <path> - Package.appxmanifest 文件的路径（默认值：搜索当前目录）
  • --light-image <path> - 浅色主题变体的单独源图像的路径

Description:

获取单个源映像，并根据清单的资产引用生成一组全面的 MSIX 映像资产：

对于清单中引用的每个资产：

  • 5 个缩放变体 - base （无后缀）、.scale-125、、.scale-150、 .scale-200.scale-400

对于应用图标（Square44x44Logo / AppList，44×44 base）：

  • 14 个板化目标变体 - .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
  • 14 个未打板的目标化变体 — .targetsize-{size}_altform-unplated

此外：

  • app.ico — 用于 shell 集成的多分辨率 ICO 文件（16、24、32、48、256）。 如果在资产目录中找到现有 .ico 文件（例如 AppIcon.ico 从项目模板），则会就地替换它，而不是创建重复文件

使用 --light-image：

  • 浅色主题目标化变体 - .targetsize-{size}_altform-lightunplated （应用图标）
  • 浅色主题缩放变体 - .scale-{factor}_altform-colorful_theme-light （磁贴，应用商店徽标）

SVG 支持： SVG 文件作为源图像完全受支持。 它们直接在每个目标大小上呈现为矢量，在所有分辨率上生成像素完美结果。

该命令在保持纵横比的同时按比例缩放图像，并在需要时将其与透明背景居中。 资产将被保存到相对于清单位置的Assets目录。

示例：

# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png

# Use an SVG source for best quality at all sizes
winapp manifest update-assets mylogo.svg

# Specify manifest location explicitly
winapp manifest update-assets mylogo.png --manifest ./dist/Package.appxmanifest

# Generate light theme variants from a separate image
winapp manifest update-assets mylogo.png --light-image mylogo-light.png

# Use the same image for both (generates all MRT light theme qualifiers)
winapp manifest update-assets mylogo.png --light-image mylogo.png

# With verbose output
winapp manifest update-assets mylogo.png --verbose

运行

从生成输出文件夹创建松散布局包，使用 Windows.Management.Deployment.PackageManager API 将其注册到 Windows，并启动应用程序 - 模拟完整的 MSIX 安装进行调试。 返回调试器附件的进程 ID。

对于大多数框架（.NET、C++、Rust、Flutter、Tauri）来说，这是使用包标识进行调试的首选命令。 与为单个 exe 注册稀疏包不同 create-debug-identity ， winapp run 请将整个文件夹注册为松散布局包，就像真正的 MSIX 安装一样。 请参阅常见调试工作流 的调试指南 。

winapp run <input-folder> [options]

参数：

  • input-folder - 包含要运行的应用的目录（必需）

选项：

  • --manifest <path> - Package.appxmanifest 的路径（默认值：从输入文件夹或当前目录自动检测）
  • --output-appx-directory <path> - 松散布局包的输出目录（默认值： AppX 输入文件夹目录中）
  • --args <string> - 要传递给应用程序的命令行参数。 或者，使用 -- 后跟参数以避免转义（例如， winapp run . -- --flag value）。
  • --no-launch - 仅创建调试标识并注册包而不启动应用程序
  • --with-alias - 使用其执行别名（而不是 AUMID 激活）启动应用。 应用在当前终端中运行，其中包含继承的 stdin/stdout/stderr。 清单中需要一个 uap5:ExecutionAlias （用于 winapp manifest add-alias 添加清单）。 不能与 --no-launch.. 不能与 --json..
  • --debug-output - 从启动的应用程序捕获 OutputDebugString 消息和首次机会异常。 框架干扰 （WinUI， COM， DirectX） 从控制台输出中筛选;完整日志文件捕获所有内容。 如果应用崩溃，请自动捕获小型转储并对其进行分析，以显示包含源文件：行号的异常类型、消息和堆栈跟踪（从生成输出文件夹中的 PDB 解析）。 在没有外部工具的情况下，立即分析托管的（.NET）崩溃。 本机 （C++/WinRT） 崩溃显示模块名称和偏移量。 一次只能有一个调试器附加到进程，因此不能同时使用其他调试器（Visual Studio，VS Code）。 如果需要附加其他调试器，请 --no-launch 改用。 不能与 --no-launch.. 不能与 --json..
  • --symbols - 从 Microsoft Symbol Server 下载 PDB 符号，以便使用解析的函数名称进行更丰富的本机崩溃分析。 只能与 --debug-output 配合使用。 如果省略并发生本机崩溃，输出将建议添加此标志。 首先运行下载符号并将其缓存在本地;后续运行使用缓存。
  • --unregister-on-exit - 在应用程序退出后注销开发包。 仅删除在开发模式下注册的包。 不能与 --no-launch..
  • --detach - 启动应用程序并立即返回，而无需等待它退出。 在启动后需要与应用交互的 CI/自动化非常有用。 将 PID 打印到 stdout（或 JSON 中带有 --json）。 不能与 --no-launch、 --debug-output、 --with-alias或 --unregister-on-exit.
  • --clean - 在重新部署之前删除现有包的应用程序数据（LocalState、设置等）。 默认情况下，应用程序数据会在重新部署之间保留。
  • --json - 将输出格式化为 JSON 以编程方式使用（例如 CI/自动化）。 --detach可用于捕获 PID。 不能与 --with-alias 或 --debug-output.

应用程序数据持久性：

默认情况下，重新部署时保留winapp run应用程序的数据（LocalState、RoamingStateSettings等）。 如果应用将数据 ApplicationData.Current.LocalFolder 写入包上下文或 Environment.GetFolderPath(SpecialFolder.LocalApplicationData) 包上下文中，该数据会在调用中 winapp run 幸存下来。

需要全新启动时使用 --clean （例如重置损坏的状态或测试首次运行行为）。

功能：

  • 查找或生成 Package.appxmanifest
  • 使用松散布局包创建和注册调试标识
  • 计算应用程序用户模型 ID （AUMID）
  • 使用已注册的标识启动应用程序（除非 --no-launch 指定）
  • 打印调试器附件的进程 ID （PID）

示例：

# Register debug identity and launch app from build output
winapp run ./bin/Debug

# Launch with custom manifest and arguments
winapp run ./dist --manifest ./out/Package.appxmanifest --args "--my-flag value"

# Pass arguments after -- to avoid escaping (equivalent to --args)
winapp run ./bin/Debug -- --my-flag value

# Specify output directory for loose layout package
winapp run ./bin/Release --output-appx-directory ./AppXDebug

# Register identity without launching
winapp run ./bin/Debug --no-launch

# Launch via execution alias (console apps run in current terminal)
winapp run ./bin/Debug --with-alias

# Launch and capture OutputDebugString messages and crash diagnostics
winapp run ./bin/Debug --debug-output

# Download native symbols for richer crash analysis (C++/WinRT crashes)
winapp run ./bin/Debug --debug-output --symbols

# Combine with execution alias to debug console apps inline
winapp run ./bin/Debug --with-alias --debug-output

# Run and automatically clean up registration on exit
winapp run ./bin/Debug --with-alias --unregister-on-exit

# Launch and detach immediately (useful for CI/automation)
winapp run ./bin/Debug --detach

# Detach with JSON output (returns PID for scripting)
winapp run ./bin/Debug --detach --json

# Wipe application data (LocalState, settings) and start fresh
winapp run ./bin/Debug --clean

MSBuild 属性（NuGet 包）：

使用 Microsoft.Windows.SDK.BuildTools.WinApp NuGet 包时，dotnet run会自动调用 winapp run。 可以在控件 .csproj 行为中设置以下 MSBuild 属性：

财产 违约 说明
EnableWinAppRunSupport true 启用/禁用运行支持功能
WinAppLaunchArgs （空） 在启动时传递给应用的参数
WinAppRunUseExecutionAlias false 通过执行别名而不是 AUMID 激活启动
WinAppRunNoLaunch false 仅注册标识而不启动
WinAppRunDebugOutput false 捕获 OutputDebugString 消息和第一机会异常。 一次只能附加一个调试器（防止 VS/VS Code）。 请 WinAppRunNoLaunch 改为附加其他调试器。 
<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

注销

取消注册旁加载的开发包。 仅删除在开发模式下注册的包（例如，通过 winapp run 或 create-debug-identity）。 从不删除应用商店安装的或 MSIX 安装的包。

winapp unregister [options]

选项：

  • --manifest <path> - Package.appxmanifest 的路径（默认值：从当前目录自动检测）
  • --force - 跳过安装位置目录检查并取消注册，即使包是从其他项目树注册的也是如此
  • --json - 将输出格式设置为 JSON

功能：

  • 从清单中读取包名称
  • 搜索和{name}{name}.debug包（调试变体由 ）create-debug-identity
  • 验证是否已在开发模式下注册每个包（IsDevelopmentMode == true）
  • 验证包的安装位置是否位于当前目录树下（除非 --force）
  • 取消注册匹配的包

示例：

# Unregister from current directory (auto-detects manifest)
winapp unregister

# Unregister with explicit manifest
winapp unregister --manifest ./Package.appxmanifest

# Force unregister even if registered from a different project tree
winapp unregister --force

# JSON output for scripting
winapp unregister --json

cert

生成、检查和安装开发证书。

证书生成

生成用于包签名的开发证书。

winapp cert generate [options]

选项：

  • --manifest <Package.appxmanifest> - 从 Package.appxmanifest 中提取发布者信息
  • --publisher <name> - 证书Publisher名称
  • --output <path> - 输出证书文件路径（支持绝对路径和相对路径）
  • --password <password> - 证书密码（默认值：“password”）
  • --valid-days <valid-days> - 证书有效天数（默认值：365）
  • --install - 生成后将证书安装到本地计算机存储
  • --if-exists <Error|Overwrite|Skip> - 如果证书文件已存在，请设置行为（默认值：错误）
  • - 与 <a0/> 一起导出文件（仅限公钥）。 用于单独分发公共证书以用于信任安装。
  • --json - 将输出格式设置为 JSON，以便以编程方式使用。 错误也返回为 JSON （{"error": "..."}）。

证书信息

显示 PFX 文件中的证书详细信息。 在签名之前验证证书与清单匹配非常有用。

winapp cert info <cert-path> [options]

参数：

  • cert-path - 证书文件的路径（PFX）

选项：

  • --password <password> - PFX 文件的密码（默认值：“password”）
  • --json - 将输出格式设置为 JSON

证书安装

将证书安装到计算机证书存储。

winapp cert install <cert-path> [options]

参数：

  • cert-path - 要安装的证书文件的路径

示例：

# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx

# Generate certificate and export public key .cer file
winapp cert generate --publisher "CN=My Company" --export-cer

# Generate certificate with JSON output (for scripting)
winapp cert generate --publisher "CN=My Company" --json

# View certificate details
winapp cert info ./mycert.pfx

# View certificate details as JSON
winapp cert info ./mycert.pfx --json

# Install certificate to machine
winapp cert install ./mycert.pfx

标识

使用证书对 MSIX 包和可执行文件进行签名。

winapp sign <file-path> [options]

参数：

  • file-path - MSIX 包的路径或要签名的可执行文件

选项：

  • --cert <path> - 签名证书的路径
  • --cert-password <password> - 证书密码（默认值：“password”）

示例：

# Sign MSIX package
winapp sign MyApp.msix --cert ./mycert.pfx

# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-password mypassword

create-external-catalog

生成包含 CodeIntegrityExternal.cat 指定目录中可执行文件哈希的目录文件。 此目录与 MSIX 稀疏包清单（AllowExternalContent）中的 TrustedLaunch 标志一起使用，以允许执行包本身不包含的外部文件。

这类似于在对 MSIX 包进行签名时创建AppxMetadata\CodeIntegrity.cat的方式signtool.exe，但生成用于稀疏/外部位置打包的外部目录。

winapp create-external-catalog <input-folder> [options]

参数：

  • input-folder - 包含要处理的可执行文件的一个或多个目录。 使用分号分隔多个目录（例如） "dir1;dir2"

选项：

  • --recursive， -r - 包括子目录中的文件
  • --use-page-hashes - 生成目录时包括页哈希（生成包含每页哈希数据的较大目录）
  • --compute-flat-hashes - 生成目录时包括平面文件哈希
  • --if-exists <Error|Overwrite|Skip>- 输出文件已存在时的行为（默认值： Error
  • --output， -o - 输出目录文件路径。 如果未指定， CodeIntegrityExternal.cat 则会在当前目录中创建。 如果指定了目录，则会追加默认文件名。

功能：

  • 扫描指定目录以获取可执行文件（包含代码部分的 PE 二进制文件）
  • 生成目录定义文件（CDF），其中包含所有找到的可执行文件的哈希
  • 使用 Windows CryptoCAT API 生成 .cat 目录文件
  • 自动跳过非可执行文件（例如，.txt.dll不带代码部分）

示例：

# Generate catalog for all executables in a directory
winapp create-external-catalog ./bin

# Include files in subdirectories
winapp create-external-catalog ./bin --recursive

# Specify a custom output path
winapp create-external-catalog ./bin --output ./dist/CodeIntegrityExternal.cat

# Overwrite existing catalog
winapp create-external-catalog ./bin --if-exists Overwrite

# Skip generation if catalog already exists
winapp create-external-catalog ./bin --if-exists Skip

# Include page hashes (for stricter code integrity validation)
winapp create-external-catalog ./bin --use-page-hashes

# Process multiple directories
winapp create-external-catalog "./bin;./lib" --recursive

# Combine multiple options
winapp create-external-catalog ./bin --recursive --use-page-hashes --compute-flat-hashes --output ./dist/CodeIntegrityExternal.cat --if-exists Overwrite

何时使用：

生成使用 TrustedLaunch 验证外部可执行文件的稀疏 MSIX 包时，请使用此命令。 典型的工作流为：

  1. winapp manifest generate --template sparse — 使用 创建稀疏清单 AllowExternalContent
  2. winapp create-external-catalog ./bin - 为应用的可执行文件生成代码完整性目录
  3. winapp pack — 将清单、资产和目录打包到 MSIX 中

工具

直接访问Windows SDK工具。 使用 Microsoft.Windows 中提供的工具。Sdk。BuildTools

winapp tool <tool-name> [tool-arguments]

可用工具：

示例：

# Use signtool to verify signature
winapp tool signtool verify /pa MyApp.msix

存储

运行 Microsoft Store 开发人员 CLI 命令。 此命令将下载Microsoft Store开发人员 CLI（如果尚未下载）。 详细了解 Microsoft Store 开发人员 CLI。

winapp store [args...]

参数：

  • args... – 要直接传递到 msstore CLI 的参数。 有关可用命令和选项，请参阅 MSStore CLI 文档 。

功能：

  • 确保下载Microsoft Store开发人员 CLI（msstore），并在系统上可用。
  • 将所有参数转发到 msstore CLI。
  • 直接在终端中运行显示输出的命令。

示例：

# List all apps in your Microsoft Partner Center account
winapp store app list

# Publish a package to the Microsoft Store
winapp store publish ./myapp.msix --appId <your-app-id>

get-winapp-path

获取安装 Windows SDK 组件的路径。

winapp get-winapp-path [options]

它返回的内容：

  • .winapp工作区目录的路径
  • 包安装目录
  • 生成的标头位置

node 创建插件

（仅在 NPM 包中可用）使用 Windows SDK 和Windows 应用 SDK集成生成本机 C++ 或 C# 加载项模板。

npx winapp node create-addon [options]

选项：

  • --name <name> - Addon name （default： “nativeWindowsAddon”）
  • --template - 选择加载项的类型。 选项为 cs 或 cpp （默认值： cpp）
  • --verbose - 启用详细输出

功能：

  • 创建带有模板文件的插件目录
  • 使用 Windows SDK 示例生成 binding.gyp 和 addon.cc
  • 安装所需的 npm 依赖项（nan、node-addon-api、node-gyp）
  • 将生成脚本添加到 package.json

示例：

# Generate addon with default name
npx winapp node create-addon

# Generate custom named addon
npx winapp node create-addon --name myWindowsAddon

节点 添加 Electron 调试 身份

（仅在 NPM 包中可用） 使用稀疏打包将应用标识添加到 Electron 开发过程。 需要 Package.appxmanifest（创建一个包含 winapp init 或 winapp manifest generate 如果没有 Package.appxmanifest）。

重要

稀疏打包 Electron 应用程序存在一个已知问题，导致应用在启动时崩溃或不呈现 Web 内容。 此问题已在Windows中修复，但尚未传播到外部Windows设备。 如果在调用 add-electron-debug-identity后看到此问题，可以在 Electron 应用中禁用沙盒 ，以便使用 --no-sandbox 标志进行调试。 此问题不会影响完整的 MSIX 打包。

若要撤消 Electron 调试标识，请使用 winapp node clear-electron-debug-identity。

npx winapp node add-electron-debug-identity [options]

选项：

选项 说明
--manifest <path> 自定义 Package.appxmanifest 的路径（默认值：当前目录中的 Package.appxmanifest）
--no-install 不要安装或修改依赖项;仅配置 Electron 调试标识
--keep-identity 保留清单标识原样，而不附加 .debug 到包名称和应用程序 ID
--verbose 启用详细输出

功能：

  • 为 electron.exe 进程注册调试标识
  • 在电子开发中启用测试需要标识的 API
  • 将现有的 Package.appxmanifest 用于标识配置

示例：

# Add identity to Electron development process
npx winapp node add-electron-debug-identity

# Use a custom manifest file
npx winapp node add-electron-debug-identity --manifest ./custom/Package.appxmanifest

节点清除电子调试身份指令 (node clear-electron-debug-identity)

（仅在 NPM 包中可用） 通过从备份还原原始 electron.exe，从 Electron 调试过程中删除包标识。

npx winapp node clear-electron-debug-identity [options]

选项：

选项 说明
--verbose 启用详细输出

功能：

  • 从创建的备份还原 electron.exe add-electron-debug-identity
  • 还原后删除备份文件
  • 将 Electron 返回到其原始状态而不使用包标识

示例：

# Remove identity from Electron development process
npx winapp node clear-electron-debug-identity

全局选项

所有命令都支持以下全局选项：

  • --verbose， -v - 启用详细日志记录的详细输出
  • --quiet， -q - 取消进度消息
  • --help， -h - 显示命令帮助

全局缓存目录

Winapp 创建一个目录来缓存可在多个项目之间共享的文件。

默认情况下，winapp 将创建一个目录 $UserProfile/.winapp 作为全局缓存目录。

若要使用不同的位置，请设置 WINAPP_CLI_CACHE_DIRECTORY 环境变量。

在 cmd 中：

REM Set a custom location for winapp's global cache
set WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

在 PowerShell 和 pwsh 中：

# Set a custom location for winapp's global cache
$env:WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

运行类似 init 或 restore以下命令时，Winapp 将自动创建此目录。

ui

使用 UI 自动化 （UIA） 检查并与其运行Windows应用 UI 进行交互。

winapp ui [command] [options]

命令：

  • status - 连接到应用并显示信息
  • inspect - 查看元素树
  • search - 按选择器查找元素
  • get-property - 读取元素属性
  • get-text / get-value - 从元素读取值/文本（TextPattern、ValuePattern 或 Name）
  • screenshot - 将窗口/元素捕获为 PNG（单独自动捕获对话）
  • invoke - 激活元素（单击、切换、展开）
  • click - 通过鼠标模拟单击元素（对于不支持调用的控件）
  • set-value - 在可编辑元素上设置值（文本、数字）
  • focus - 移动键盘焦点
  • scroll-into-view - 滚动元素可见
  • wait-for - 等待元素状态
  • list-windows - 列出应用的所有窗口
  • get-focused - 报告当前聚焦的元素

选项：

  • -a, --app <app> - 目标应用（名称、标题或 PID）
  • -w, --window <hwnd> - HWND 的目标窗口（稳定）

有关完整文档，请参阅 docs/ui-automation.md。

  • Last updated on