Empaquetado de un ejecutable de la CLI como MSIX

En esta guía se explica cómo empaquetar un archivo ejecutable de línea de comandos existente como un paquete MSIX para su distribución a través de Windows Administrador de paquetes (winget), Microsoft Store o distribución directa.

Prerrequisitos

  • Un ejecutable de la CLI existente (.exe) que desea empaquetar
  • Windows 10 versión 1809 o posterior

Pasos

1. Organizar la aplicación de la CLI

Coloque el ejecutable de la CLI y las dependencias en una carpeta dedicada. Esta carpeta contendrá todos los archivos que se deben incluir en el paquete MSIX.

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

2. Instalación de la CLI de winapp

Instale la CLI de winapp a través de Windows Administrador de paquetes o actualice a la versión más reciente si ya la tiene:

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

3. Generar el Package.appxmanifest

Genere un Package.appxmanifest base y los recursos necesarios para el ejecutable de CLI.

winapp manifest generate --executable .\yourcli.exe

Este comando crea un Package.appxmanifest archivo en el directorio actual con valores predeterminados rellenados desde el archivo ejecutable.

4. Configurar el manifiesto

Edite el Package.appxmanifest generado para personalizar el paquete. Cada subproceso siguiente explica qué cambiar y por qué.

4.1 Agregar espacio de nombres necesario

Agregue el espacio de nombres uap5 al elemento Package si aún no está presente. Esto es necesario para el alias de ejecución en el paso 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 el elemento Application

En el <uap:VisualElements> elemento , agregue AppListEntry="none" para ocultar la aplicación en el menú Inicio. Las herramientas de la CLI se invocan desde el terminal, por lo que no necesitan una entrada de menú Inicio:

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

4.3 Agregar extensión de alias de ejecución

Agregue un alias de ejecución para que los usuarios puedan ejecutar la CLI por su nombre desde cualquier ventana de terminal. Agregue esto dentro del elemento <Application> (después de <uap:VisualElements>):

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

Reemplace por yourcli.exe el nombre del comando deseado para la CLI. Una vez que un usuario instala MSIX, podrá invocar la CLI con este comando.

4.4 Actualizar metadatos de aplicación

Actualice los siguientes campos para que coincidan con la aplicación de la CLI.

Importante

El valor Publisher del manifiesto debe coincidir con el editor del certificado de firma. Si genera un certificado más adelante (paso 5), usará el editor del manifiesto. Si cambia el publicador después de generar un certificado, deberá volver a generar el certificado para que coincida.

  • Identity: Actualizar Name, Publisher y Version

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

  • Propiedades: actualizar el nombre para mostrar, el nombre para mostrar del publicador y la descripción

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

  • VisualElements: actualización del nombre para mostrar y las referencias de recursos

    <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: También debe agregar los recursos de icono adecuados a una Assets carpeta del directorio del paquete. Aunque la aplicación no aparecerá en el menú Inicio, los iconos siguen siendo necesarios para el envío en la Tienda de Windows y pueden aparecer en otros contextos.

5. (Opcional) Generar un certificado de desarrollo

Para las pruebas y la distribución locales fuera del Microsoft Store, deberá firmar el paquete MSIX con un certificado.

Genere un certificado de desarrollo. Manténgalo fuera de la carpeta de la CLI para evitar incluirlo accidentalmente en el paquete:

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

Esto crea un devcert.pfx archivo en el directorio principal (por ejemplo, C:\Users\yourname\devcert.pfx).

Para confiar en este certificado en la máquina de desarrollo, instálelo (requiere privilegios de administrador):

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

6. Empaquetar la CLI

Ahora está listo para crear el paquete 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

Esto crea un .msix archivo en el directorio actual.

7. Instalar y comprobar

Instale el paquete MSIX para comprobar que todo funciona:

Add-AppxPackage .\MyCliPackage.msix

Si agregó un alias de ejecución en el paso 4.3, ahora puede ejecutar la CLI desde cualquier terminal:

yourcli --help

Para desinstalarlo más adelante:

Get-AppxPackage *YourCLI* | Remove-AppxPackage

Tips

  1. Una vez que esté listo para su distribución, puede firmar su MSIX con un certificado de firma de código de una entidad de certificación para que los usuarios no tengan que instalar un certificado autofirmado.
  2. El Microsoft Store firmará el MSIX por usted, no es necesario firmar antes del envío.
  3. Es posible que tenga que crear varios paquetes MSIX, uno para cada arquitectura que admita (x64, Arm64)

Pasos siguientes

  • Distribute a través de winget: Envíe su MSIX al repositorio Windows Administrador de paquetes Community
  • Publicar en Microsoft Store: Utilice winapp store para enviar su paquete
  • Configurar CI/CD: Usa la acción de GitHub para automatizar el empaquetado en la tubería
  • Last updated on