Empacotamento de um executável CLI como MSIX

Este guia guia-o como empacotar um executável de linha de comandos existente como um pacote MSIX para distribuição via Windows Gestor de Pacotes (winget), a Microsoft Store ou distribuição direta.

Pré-requisitos

  • Um executável de CLI existente (.exe) que queres empacotar
  • Windows 10 versão 1809 ou posterior

Passos

1. Organize a sua candidatura à CLI

Coloque o executável da CLI e quaisquer dependências numa pasta dedicada. Esta pasta irá conter todos os ficheiros que devem estar incluídos no seu pacote MSIX.

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

2. Instalar a CLI do winapp

Instale a CLI do winapp via Windows Gestor de Pacotes, ou atualize para a versão mais recente se já a tiver:

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

3. Gerar o Package.appxmanifest

Gera um Package.appxmanifest base e os ativos necessários para o executável da sua CLI:

winapp manifest generate --executable .\yourcli.exe

Este comando cria um Package.appxmanifest ficheiro no diretório atual com valores predefinidos preenchidos a partir do seu executável.

4. Configurar o Manifesto

Edite o conteúdo gerado Package.appxmanifest para personalizar o seu pacote. Cada sub-passo abaixo explica o que mudar e porquê.

4.1 Adicionar espaço de nomes obrigatório

Adiciona o uap5 namespace ao Package elemento se ainda não estiver presente. Isto é necessário para o alias de execução no passo 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 Configurar o elemento de aplicação

No <uap:VisualElements> elemento, adicione AppListEntry="none" para esconder a aplicação no menu Iniciar. As ferramentas CLI são invocadas a partir do terminal, por isso não precisam de uma entrada no menu Iniciar:

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

4.3 Adicionar Extensão de Alias de Execução

Adicione um alias de execução para que os utilizadores possam executar a sua CLI pelo nome a partir de qualquer janela de terminal. Adicione isto dentro do <Application> elemento (depois <uap:VisualElements>):

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

Substitui yourcli.exe pelo nome de comando desejado para a tua CLI. Assim que um utilizador instala o MSIX, poderá invocar a sua CLI com este comando.

4.4 Atualizar Metadados da Aplicação

Atualize os campos seguintes para corresponder à sua aplicação de linha de comando (CLI).

Importante

O valor Publisher no seu manifesto tem de corresponder ao editor do seu certificado de assinatura. Se gerares um certificado mais tarde (passo 5), ele usará o editor do teu manifesto. Se mudares de editor depois de gerares um certificado, terás de regenerar o certificado para corresponder.

  • Identity: Atualização Name, Publisher e Version

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

  • Propriedades: Atualizar nome de apresentação, nome de apresentação do editor e descrição

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

  • VisualElements: Atualizar nome de exibição e referências de ativos

    <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>

Nota: Também deve adicionar os recursos de ícones adequados a uma Assets pasta no seu diretório do pacote. Embora a aplicação não apareça no menu Iniciar, os ícones continuam a ser necessários para submissão à Loja e podem aparecer noutros contextos.

5. (Opcional) Gerar um Certificado de Desenvolvimento

Para testes e distribuição locais fora da Microsoft Store, terá de assinar o seu pacote MSIX com um certificado.

Gere um certificado de desenvolvimento. Mantenha-o fora da sua pasta CLI para evitar inclui-lo acidentalmente no pacote:

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

Isto cria um devcert.pfx ficheiro no seu diretório pessoal (por exemplo, C:\Users\yourname\devcert.pfx).

Para confiar neste certificado na sua máquina de desenvolvimento, instale-o (requer privilégios de administrador):

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

6. Empacote o seu CLI

Agora está pronto para criar o pacote 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

Isto cria um .msix ficheiro no diretório atual.

7. Instalar e Verificar

Instale o pacote MSIX para verificar se tudo funciona:

Add-AppxPackage .\MyCliPackage.msix

Se adicionaste um alias de execução no passo 4.3, agora podes executar a tua CLI a partir de qualquer terminal:

yourcli --help

Para desinstalar mais tarde:

Get-AppxPackage *YourCLI* | Remove-AppxPackage

Tips

  1. Quando estiver pronto para a distribuição, pode assinar o seu MSIX com um certificado de assinatura de código de uma Autoridade Certificadora, para que os seus utilizadores não tenham de instalar um certificado autoassinado
  2. A Microsoft Store assina o MSIX por si, não precisa de assinar antes de submeter.
  3. Poderás precisar de criar vários pacotes MSIX, um para cada arquitetura que suportas (x64, Arm64)

Próximas Etapas

  • Distribua via winget: Submeta o seu MSIX ao Repositório Comunitário Windows Gestor de Pacotes
  • Publicar no Microsoft Store: Use winapp store para submeter o seu pacote
  • Configurar CI/CD: Use o GitHub Action para automatizar o empacotamento no seu pipeline
  • Last updated on