将 winapp CLI 与 Rust 配合使用

本指南演示如何将 winapp CLI 与 Rust 应用程序配合使用，以包标识进行调试，并将应用程序打包为 MSIX。

有关完整的工作示例，请查看此存储库中的 Rust 示例 。

包标识是Windows app模型中的核心概念。 它允许应用程序访问特定的Windows API（例如通知、安全、AI API 等），具有干净的安装/卸载体验等。

标准可执行文件（如使用 cargo build创建的可执行文件）没有包标识。 本指南演示如何添加它进行调试，然后将其打包以供分发。

先决条件

  1. Rust 工具链：使用 rustup 或 winget 安装 Rust（或更新（如果已安装）：

    winget install Rustlang.Rustup --source winget

  2. winapp CLI：通过 winget 安装或更新 winapp 工具（如果已安装）。

    winget install microsoft.winappcli --source winget

1.创建新的 Rust 应用

首先创建简单的 Rust 应用程序：

cargo new rust-app
cd rust-app

运行它以确保一切正常工作：

cargo run

输出应为“Hello， world！”

2. 更新代码以检查标识

我们将更新应用，以检查它是否使用包标识运行。 这将帮助我们验证标识在后续步骤中是否正常工作。 我们将使用 windows crate 访问 Windows API。

首先，通过运行以下命令将 windows 依赖项添加到你 Cargo.toml ：

cargo add windows --features ApplicationModel

这会添加具有 ApplicationModel 功能的 Windows API 绑定，这使我们可以访问用于检查标识的 Package API。

接下来，将整个内容 src/main.rs 替换为以下代码。 此代码尝试检索当前包标识。 如果成功，则会打印包系列名称;否则，它将打印“未打包”。

注释

完整示例还包括代码，以在身份存在时显示 Windows 通知，但在本指南中，我们将重点介绍身份检查。

use windows::ApplicationModel::Package;

fn main() {
    match Package::Current() {
        Ok(package) => {
            match package.Id() {
                Ok(id) => match id.FamilyName() {
                    Ok(name) => println!("Package Family Name: {}", name),
                    Err(e) => println!("Error getting family name: {}", e),
                },
                Err(e) => println!("Error getting package ID: {}", e),
            }
        }
        Err(_) => println!("Not packaged"),
    }
}

3.在没有标识的情况下运行

现在，像往常一样生成并运行应用：

cargo run

应会看到输出“未打包”。 这确认标准可执行文件在没有任何包标识的情况下正在运行。

4.使用 winapp CLI 初始化Project

该 winapp init 命令一次性设置所需的一切：应用清单和资产。 清单定义应用的标识（名称、发布者、版本），Windows用于授予 API 访问权限。

运行以下命令并按照提示操作：

winapp init

出现提示时：

  • 包名称：按 Enter 接受默认 （rust-app）
  • 发布者名称：按 Enter 接受默认值或输入名称
  • 版本：按 Enter 接受 1.0.0.0
  • 说明：按 Enter 接受默认值或输入说明
  • 设置 SDK：选择“不设置 SDK”（Rust 使用自己的 windows 箱而不是 C++ SDK 标头）

此命令将：

  • 创建 Package.appxmanifest — 定义您应用身份的清单
  • 创建 Assets 文件夹 - MSIX 打包和应用商店提交所需的图标

注释

由于没有管理 SDK 包，因此不会创建任何winapp.yaml — Rust 通过 Cargo 使用windowscrate，因此winapp restore/update 无需跟踪任何内容。

可以打开 Package.appxmanifest 以进一步自定义属性，如显示名称、发布者和功能。

添加执行别名（适用于控制台应用）

由于 cargo new 创建控制台应用，因此需要向清单添加执行别名。 如果没有它， winapp run 则通过 AUMID 激活启动应用，这会打开一个新窗口，当控制台应用完成时，该窗口会立即关闭，吞没任何输出。

该别名还允许用户在安装 MSIX 后按名称从任何终端运行应用。 清单中注册了一个别名，例如 rust-app.exe（默认为项目的 exe 名称），用户可以将其作为 rust-app 或 rust-app.exe 进行调用。

如果要生成 UI 应用 （呈现其自己的窗口的 Rust 应用），请跳过此步骤。 这些应用在默认的 AUMID 启动下运行良好。

添加别名：

winapp manifest add-alias

这会向uap5:ExecutionAlias添加一个Package.appxmanifest条目。

使用身份进行调试

若要测试需要标识（如通知）且未完全打包应用的功能，请使用 winapp run。 这会将整个生成输出文件夹注册为松散布局包（就像真正的 MSIX 安装一样），并启动应用。 调试不需要证书或签名。

  1. 生成可执行文件：

    cargo build

  2. 使用标识运行：

    winapp run .\target\debug --with-alias

该 --with-alias 标志通过其执行别名启动应用，以便控制台输出保留在当前终端中。 这需要我们在步骤 4 中添加的 uap5:ExecutionAlias。

注释

winapp run 还会在您的系统中注册该软件包。 这就是为什么在步骤 6 的后面尝试安装 MSIX 时，MSIX 可能显示为“已安装”。 使用 winapp unregister 清理开发包以完成工作。

现在应会看到类似于以下内容的输出：

Package Family Name: rust-app_12345abcde

这确认你的应用正在运行，并具有有效的包标识！

小窍门

有关高级调试工作流（附加调试器、IDE 设置、启动调试），请参阅 调试指南。

6. 使用 MSIX 打包

准备好分发应用后，可以使用同一清单将其打包为 MSIX。 MSIX 提供干净安装/卸载、自动更新和受信任的安装体验。

准备好包目录

首先，在发布模式下生成应用程序以实现最佳性能：

cargo build --release

然后，创建一个目录，其中包含分发所需的文件。 该 target\release 文件夹包含不属于应用的生成项目 ， 我们只需要可执行文件：

mkdir dist
copy .\target\release\rust-app.exe .\dist\

生成开发证书

必须对 MSIX 包进行签名。 对于本地测试，请生成自签名开发证书：

winapp cert generate --if-exists skip

Important

证书的发布者必须与 Package.appxmanifest 中的 Publisher相匹配。 该 cert generate 命令会自动从清单中读取此内容。

签名和打包

现在可以在一步中完成打包和签名：

winapp pack .\dist --cert .\devcert.pfx

注意：此命令 pack 会自动使用当前目录中的 Package.appxmanifest，并在打包之前将其复制到目标文件夹。 生成的 .msix 文件将位于当前目录中。

安装证书

在安装 MSIX 包之前，需要信任计算机上的开发证书。 以管理员身份运行此命令（每个证书只需执行此操作一次）：

winapp cert install .\devcert.pfx

安装和运行

注释

如果在步骤 5 中使用 winapp run ，则可能已在系统上注册包。 首先使用 winapp unregister 删除开发注册，然后安装发布包。

双击生成的 .msix 文件或通过 PowerShell 安装包：

Add-AppxPackage .\rust-app.msix

现在，可以通过键入以下内容从终端中的任意位置运行应用：

rust-app

应该看到“程序包系列名称”输出，以确认它已安装并以标识运行。

小窍门

如果需要重新打包应用（例如代码更改后），请在再次运行winapp pack之前，在Package.appxmanifest中递增Version。 Windows需要更高的版本号才能更新已安装的包。

提示

  1. 准备好分发后，可以使用证书颁发机构的代码签名证书对 MSIX 进行签名，以便用户无需安装自签名证书
  2. Microsoft Store将为你签名 MSIX，无需在提交之前进行签名。
  3. 可能需要创建多个 MSIX 包，一个用于支持的每个体系结构（x64，Arm64）

后续步骤

  • 通过 winget 分发：将 MSIX 提交到 Windows 程序包管理器 社区存储库
  • 发布到 Microsoft Store：使用 winapp store 提交包
  • 设置 CI/CD：使用 GitHub Action 在流水线中自动打包
  • 探索 Windows APIs：使用包标识，现在可以使用通知、设备端 AI和其他身份依赖的 API
  • Last updated on