Empacotando um executável da CLI como MSIX

Este guia orienta você pelo empacotamento de um executável de linha de comando existente como um pacote MSIX para distribuição por meio do Windows Gerenciador de Pacotes (winget), da Microsoft Store ou da distribuição direta.

Pré-requisitos

  • Um executável da CLI existente (.exe) que você deseja empacotar
  • Windows 10 versão 1809 ou posterior

Steps

1. Organizar seu aplicativo da CLI

Coloque o executável da CLI e as dependências em uma pasta dedicada. Essa pasta conterá todos os arquivos que devem ser incluídos no pacote MSIX.

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

2. Instalar a CLI do winapp

Instale a CLI do winapp por meio de Windows Gerenciador de Pacotes ou atualize para a versão mais recente se você já tiver:

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

3. Gerar o Package.appxmanifest

Gere um arquivo base Package.appxmanifest e os ativos necessários para o seu executável de linha de comando:

winapp manifest generate --executable .\yourcli.exe

Esse comando cria um Package.appxmanifest arquivo no diretório atual com valores padrão preenchidos do executável.

4. Configurar o manifesto

Edite o Package.appxmanifest gerado para customizar seu pacote. Cada sub-etapa abaixo explica o que mudar e por quê.

4.1 Adicionar namespace necessário

Adicione o uap5 namespace ao Package elemento se ele ainda não estiver presente. Isso é necessário para o alias de execução na etapa 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 application

<uap:VisualElements> No elemento, adicione AppListEntry="none" para ocultar o aplicativo no menu Iniciar. As ferramentas da CLI são invocadas do terminal, portanto, elas não precisam de uma entrada de 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 do alias de execução

Adicione um alias de execução para que os usuários possam executar sua CLI pelo nome em qualquer janela do terminal. Adicione isso 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>

Substitua yourcli.exe pelo nome de comando desejado para sua CLI. Depois que um usuário instalar o MSIX, ele poderá invocar a CLI com esse comando.

4.4 Atualizar metadados do aplicativo

Atualize os campos a seguir para corresponder ao aplicativo da CLI.

Importante

O valor Publisher em seu manifesto deve corresponder ao publicador no certificado de assinatura. Se você gerar um certificado posteriormente (etapa 5), ele usará o publicador do seu manifesto. Se você alterar o publicador depois de gerar um certificado, precisará regenerar o certificado para corresponder.

  • Identity: Atualizar Name, Publisher e Version

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

  • Propriedades: Atualizar nome de exibição, nome de exibiçã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 o nome de exibição e as 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>

Observação: você também deve adicionar ativos de ícone adequados a uma Assets pasta no diretório do pacote. Embora o aplicativo não apareça no menu Iniciar, os ícones ainda são necessários para submissão à Loja e podem aparecer em outros contextos.

5. (Opcional) Gerar um certificado de desenvolvimento

Para testes locais e distribuição fora do Microsoft Store, você precisará assinar seu pacote MSIX com um certificado.

Gerar um certificado de desenvolvimento. Mantenha-a fora da pasta da CLI para evitar incluí-la acidentalmente no pacote:

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

Isso cria um devcert.pfx arquivo no diretório inicial (por exemplo, C:\Users\yourname\devcert.pfx).

Para confiar nesse certificado em seu computador de desenvolvimento, instale-o (requer privilégios de administrador):

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

6. Empacotar sua CLI

Agora você 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

Isso cria um .msix arquivo no diretório atual.

7. Instalar e verificar

Instale o pacote MSIX para verificar se tudo funciona:

Add-AppxPackage .\MyCliPackage.msix

Se você adicionou um alias de execução na etapa 4.3, agora poderá executar a CLI de qualquer terminal:

yourcli --help

Para desinstalar mais tarde:

Get-AppxPackage *YourCLI* | Remove-AppxPackage

Dicas

  1. Quando estiver pronto para distribuição, você poderá assinar seu MSIX com um certificado de assinatura de código de uma Autoridade de Certificação para que os usuários não precisem instalar um certificado autoassinado
  2. O Microsoft Store assinará o MSIX para você, não é necessário assinar antes do envio.
  3. Talvez seja necessário criar vários pacotes MSIX, um para cada arquitetura compatível (x64, Arm64)

Próximas etapas

  • Distribute via winget: envie seu MSIX para o repositório da comunidade Windows Gerenciador de Pacotes
  • Publicar na Microsoft Store: use winapp store para enviar seu pacote
  • Set up CI/CD: Use a Ação do setup-WinAppCli GitHub para automatizar o empacotamento em seu pipeline
  • Last updated on