Использование интерфейса командной строки winapp с Rust

В этом руководстве показано, как использовать winapp CLI с приложением Rust для отладки с удостоверением пакета и упаковки приложения в виде MSIX.

Полный рабочий пример см. в примере Rust в этом репозитории.

Идентификатор пакета — это основная концепция модели приложений Windows. Это позволяет приложению получать доступ к определенным API-интерфейсам Windows (например, уведомлениям, безопасности, API ИИ и т. д.), иметь чистый интерфейс установки и удаления и многое другое.

Стандартный исполняемый файл (например, созданный с cargo build) не имеет удостоверения пакета. В этом руководстве показано, как добавить его для отладки, а затем упаковать его для распространения.

Необходимые условия

1. Цепочка инструментов Rust: установите Rust с помощью rustup или winget (или обновления, если оно уже установлено):

   winget install Rustlang.Rustup --source winget
   

2. winapp CLI: установите winapp средство с помощью winget (или обновите, если оно уже установлено):

   winget install microsoft.winappcli --source winget
   

1. Создание нового приложения Rust

Начните с создания простого приложения Rust:

cargo new rust-app
cd rust-app

Запустите его, чтобы убедиться, что все работает:

cargo run

Выходные данные должны быть "Hello, world!"

2. Обновление кода для проверки удостоверения

Мы обновим приложение, чтобы проверить, работает ли оно с идентификацией пакета. Это поможет нам удостовериться в правильной работе идентификации на следующих этапах. Мы будем использовать windows crate для доступа к API Windows.

Сначала добавьте windows зависимость в свою Cargo.toml , выполнив следующую команду:

cargo add windows --features ApplicationModel

Это добавляет привязки API Windows с функцией ApplicationModel, которая предоставляет нам доступ к API Package для проверки удостоверения.

Затем замените всё содержимое 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

Команда winapp init настраивает все, что вам нужно в один заход: манифест приложения и ресурсы. Манифест определяет удостоверение приложения (имя, издатель, версия), которое Windows используется для предоставления доступа к API.

Выполните следующую команду и следуйте подсказкам.

winapp init

Когда появится запрос:

• Имя пакета: нажмите Enter, чтобы принять значение по умолчанию (rust-app)
• Имя издателя: нажмите клавишу Enter, чтобы принять значение по умолчанию или введите своё имя.
• Версия: нажмите клавишу ВВОД, чтобы принять 1.0.0.0
• Описание: нажмите Enter, чтобы принять параметр по умолчанию или ввести описание
• Пакеты SDK для установки. Выберите "Не настраивать пакеты SDK" (Rust использует свой собственный windows контейнер, а не заголовки пакета SDK для C++)

Эта команда выполнит следующее действие:

• Создайте Package.appxmanifest — манифест, определяющий идентичность вашего приложения.
• Создание Assets папки — значки, необходимые для упаковки MSIX и отправки в Магазин

Замечание

Так как пакеты SDK не управляются, не создается winapp.yaml. Rust использует windows крейт через Cargo, поэтому winapp restore/update нечего отслеживать.

Вы можете открыть Package.appxmanifest, чтобы дополнительно настроить такие свойства, как отображаемое имя, издатель и возможности.

Добавление псевдонима запуска (для консольных приложений)

Поскольку cargo new создаёт консольное приложение, необходимо добавить алиас выполнения в манифест. Без него winapp run запускает приложение с помощью активации AUMID, которая открывает новое окно, и это окно закрывается сразу после завершения консольного приложения, проглотив все выходные данные.

Псевдоним также позволяет пользователям запускать приложение по имени из любого терминала после установки MSIX. Манифест регистрирует псевдоним, например rust-app.exe (по умолчанию имя exe проекта), который пользователи могут вызывать как rust-app или rust-app.exe.

Пропустите этот шаг, если вы создаете приложение пользовательского интерфейса (приложение Rust, которое отображает собственное окно). Эти приложения хорошо работают с запуском AUMID по умолчанию.

Добавьте псевдоним:

winapp manifest add-alias

При этом к Package.appxmanifest добавляется запись uap5:ExecutionAlias.

5. Отладка с помощью идентификации

Чтобы протестировать функции, требующие удостоверения (например, уведомления) без полной упаковки приложения, используйте winapp run. Это регистрирует всю папку выходных данных сборки как развернутый пакет макета, аналогично реальной установке MSIX, и запускает приложение. Для отладки не требуется сертификат или подпись.

1. Создайте исполняемый файл:

   cargo build
   

2. Запустите с идентификацией:

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

Флаг --with-alias запускает приложение с помощью псевдонима выполнения, чтобы выходные данные консоли оставались в текущем терминале. Для этого требуется uap5:ExecutionAlias, который мы добавили на шаге 4.

Замечание

winapp run также регистрирует пакет в системе. Поэтому MSIX может отображаться как "уже установлен" при попытке установить его позже на шаге 6. Используйте winapp unregister для очистки пакетов разработки по завершении.

Теперь вы увидите выходные данные, аналогичные следующим:

Package Family Name: rust-app_12345abcde

Это подтверждает, что ваше приложение работает с действительным удостоверением пакета!

Подсказка

Дополнительные рабочие процессы отладки (присоединение отладчиков, настройка интегрированной среды разработки, отладка запуска) см. в руководстве по отладке.

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

Это важно

Издатель сертификата должен соответствовать Publisher в Package.appxmanifest. Команда cert generate автоматически считывает это из манифеста.

Подписание и упаковка

Теперь вы можете упаковывать и подписывать за один шаг:

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

Примечание. Команда pack автоматически использует Package.appxmanifest из текущего каталога и копирует ее в целевую папку перед упаковкой. Созданный MSIX-файл будет находиться в текущем каталоге.

Установка сертификата

Прежде чем установить пакет MSIX, необходимо доверять сертификату разработки на компьютере. Выполните эту команду от имени администратора (для каждого сертификата необходимо выполнить только один раз):

winapp cert install .\devcert.pfx

Установка и запуск

Замечание

Если вы использовали winapp run на шаге 5, пакет уже может быть зарегистрирован в вашей системе. winapp unregister Сначала следует удалить регистрацию разработки, а затем установить финальный пакет.

Установите пакет, дважды щелкнув созданный .msix файл или с помощью PowerShell:

Add-AppxPackage .\rust-app.msix

Теперь вы можете запустить приложение из любого места в терминале, введя следующее:

rust-app

Вы должны увидеть вывод "Package Family Name", подтверждающий его установку и запуск с удостоверением.

Подсказка

Если вам нужно перепаковать приложение (например, после изменения кода), увеличьте Version в вашем Package.appxmanifest перед выполнением winapp pack еще раз. Windows требуется более высокий номер версии для обновления установленного пакета.

Tips

1. Когда вы будете готовы к распространению, вы можете подписать MSIX с помощью сертификата подписи кода из центра сертификации, чтобы пользователи не должны устанавливать самозаверяющий сертификат.
2. Microsoft Store подпишет MSIX за вас, так что нет необходимости подписывать его перед отправкой.
3. Может потребоваться создать несколько пакетов MSIX, по одному для каждой поддерживаемой архитектуры (x64, Arm64)

Дальнейшие шаги

• Распространите с помощью winget: отправьте MSIX в репозиторий сообщества Windows диспетчер пакетов
• Опубликовать в Microsoft Store: используйте winapp store для отправки пакета.
• Set up CI/CD. Используйте действие setup-WinAppCli GitHub для автоматизации упаковки в конвейере.
• Ознакомьтесь с Windows API: Теперь, с удостоверением пакета, вы можете использовать Уведомления, встроенный ИИ, и другие API-интерфейсы, зависящие от удостоверения