Упаковка исполняемого файла CLI как MSIX

В этом руководстве описывается упаковка существующего исполняемого файла командной строки в виде пакета MSIX для распространения с помощью Windows диспетчер пакетов (winget), Microsoft Store или прямого распространения.

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

• Существующий исполняемый файл CLI (.exe), который требуется упаковать
• Windows 10 версии 1809 или более поздней

Шаги

1. Упорядочение приложения CLI

Поместите исполняемый файл CLI и все зависимости в выделенную папку. Эта папка будет содержать все файлы, которые должны быть включены в пакет MSIX.

mkdir MyCliPackage
cd MyCliPackage
# Copy your CLI executable and dependencies here

2. Установка winapp CLI

Установите winapp CLI с помощью Windows диспетчер пакетов или обновите до последней версии, если у вас уже есть:

# Install (or update if already installed)
winget install microsoft.winappcli --source winget

3. Создание Package.appxmanifest

Создайте базовый пакет.appxmanifest и необходимые ресурсы для исполняемого файла CLI:

winapp manifest generate --executable .\yourcli.exe

Эта команда создает Package.appxmanifest файл в текущем каталоге со значениями по умолчанию, заполненными исполняемым файлом.

4. Настройка манифеста

Измените созданный Package.appxmanifest код, чтобы настроить пакет. Каждый из подшагов ниже объясняет, что следует изменить и почему.

4.1. Добавление обязательного пространства имен

Добавьте пространство имен uap5 к элементу Package, если его еще нет. Это необходимо для псевдонима выполнения на шаге 4.3.

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  ...
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap5="http://schemas.microsoft.com/appx/manifest/uap/windows10/5"
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  IgnorableNamespaces="uap uap5 rescap">

4.2 Настройка элемента Application

В элементе <uap:VisualElements> добавьте AppListEntry="none" , чтобы скрыть приложение из меню "Пуск". Средства командной строки вызываются из терминала, поэтому им не требуется отображение в меню "Пуск".

<uap:VisualElements
    DisplayName="YourApp"
    Description="My Application"
    BackgroundColor="transparent"
    Square150x150Logo="Assets\Square150x150Logo.png"
    Square44x44Logo="Assets\Square44x44Logo.png"
    AppListEntry="none">
</uap:VisualElements>

4.3. Добавление расширения для псевдонима выполнения

Добавьте псевдоним выполнения, чтобы пользователи могли запускать интерфейс командной строки по имени из любого окна терминала. Добавьте это в <Application> элемент (после <uap:VisualElements>):

<Extensions>
  <uap5:Extension Category="windows.appExecutionAlias">
    <uap5:AppExecutionAlias>
      <uap5:ExecutionAlias Alias="yourcli.exe" />
    </uap5:AppExecutionAlias>
  </uap5:Extension>
</Extensions>

Замените yourcli.exe нужным именем команды для интерфейса командной строки. После установки MSIX пользователь сможет вызвать интерфейс командной строки с помощью этой команды.

4.4 Обновление метаданных приложения

Обновите следующие поля, чтобы соответствовать приложению CLI.

Это важно

Значение Publisher в манифесте должно соответствовать издателю в сертификате подписи. Если вы создаете сертификат позже (шаг 5), он будет использовать издателя из манифеста. При изменении издателя после создания сертификата необходимо повторно создать сертификат для сопоставления.

• Identity: обновление Name, Publisher и Version

  <Identity
    Name="YourCompany.YourCLI"
    Publisher="CN=Your Company"
    Version="1.0.0.0" />
  

• Свойства: обновить отображаемое имя, отображаемое имя издателя и описание

  <Properties>
    <DisplayName>Your CLI Tool</DisplayName>
    <PublisherDisplayName>Your Company</PublisherDisplayName>
    <Description>Description of your CLI tool</Description>
    <Logo>Assets\StoreLogo.png</Logo>
  </Properties>
  

• VisualElements: обновление отображаемого имени и ссылок на ресурсы

  <uap:VisualElements
    DisplayName="Your CLI Tool"
    Description="Description of your CLI tool"
    BackgroundColor="transparent"
    Square150x150Logo="Assets\Square150x150Logo.png"
    Square44x44Logo="Assets\Square44x44Logo.png">
    <uap:DefaultTile Wide310x150Logo="Assets\Wide310x150Logo.png" />
    <uap:SplashScreen Image="Assets\SplashScreen.png" />
  </uap:VisualElements>
  

Примечание. Вы также должны добавить соответствующие иконки в папку Assets в каталоге вашего пакета. Хотя приложение не появится в меню "Пуск", значки по-прежнему требуются для отправки в Магазин и могут появляться в других контекстах.

5. (Необязательно) Создание сертификата разработки

Для локального тестирования и распространения за пределами Microsoft Store необходимо подписать пакет MSIX с помощью сертификата.

Создайте сертификат разработки. Держите его вне папки CLI, чтобы избежать случайного включения в пакет.

# Navigate to a location outside your CLI folder (e.g., your home directory)
cd ~
winapp cert generate

При этом создается файл в домашнем devcert.pfx каталоге (например, C:\Users\yourname\devcert.pfx).

Чтобы доверять этому сертификату на компьютере разработки, установите его (требуются права администратора):

# Run PowerShell as Administrator
winapp cert install ~\devcert.pfx

6. Упаковка интерфейса командной строки

Теперь вы готовы создать пакет MSIX:

# Navigate back outside of your project folder
# Package with dev certificate (for local testing/distribution)
winapp pack .\path\to\MyCliPackage --cert .\path\to\devcert.pfx

При этом создается .msix файл в текущем каталоге.

7. Установка и проверка

Установите пакет MSIX, чтобы убедиться, что все работает:

Add-AppxPackage .\MyCliPackage.msix

Если вы добавили псевдоним выполнения на шаге 4.3, теперь вы можете запустить интерфейс командной строки из любого терминала:

yourcli --help

Чтобы удалить позже, выполните приведенные ниже действия.

Get-AppxPackage *YourCLI* | Remove-AppxPackage

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 для автоматизации упаковки в конвейере.