Creazione del pacchetto di un eseguibile dell'interfaccia della riga di comando come MSIX

Questa guida ti guida su come impacchettare un eseguibile della riga di comando esistente come pacchetto MSIX per la distribuzione tramite Windows Gestione pacchetti (winget), Microsoft Store o direttamente.

Prerequisiti

• Eseguibile esistente dell'interfaccia della riga di comando (.exe) che si desidera confezionare
• Windows 10 versione 1809 o successiva

Steps

1. Organizzare l'applicazione CLI

Posizionare l'eseguibile CLI e tutte le dipendenze in una cartella dedicata. Questa cartella conterrà tutti i file che devono essere inclusi nel pacchetto MSIX.

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

2. Installare il CLI di winapp

Installare l'interfaccia della riga di comando di winapp tramite Windows Gestione pacchetti o eseguire l'aggiornamento alla versione più recente se è già disponibile:

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

3. Generare Package.appxmanifest

Generare un Package.appxmanifest di base e gli asset necessari per l'eseguibile dello strumento da riga di comando:

winapp manifest generate --executable .\yourcli.exe

Questo comando crea un Package.appxmanifest file nella directory corrente con i valori predefiniti popolati dal file eseguibile.

4. Configurare il manifesto

Modifica l'elemento generato Package.appxmanifest per personalizzare il pacchetto. Ogni passaggio secondario seguente illustra cosa modificare e perché.

4.1 Aggiungere lo spazio dei nomi obbligatorio

Aggiungi lo spazio dei nomi uap5 all'elemento Package se non è già presente. Questa operazione è necessaria per l'alias di esecuzione nel passaggio 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 Configurare l'elemento Application

Nell'elemento <uap:VisualElements> aggiungere AppListEntry="none" per nascondere l'app dal menu Start. Gli strumenti dell'interfaccia della riga di comando vengono richiamati dal terminale, quindi non necessitano di una voce di menu Start:

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

4.3 Aggiungere l'estensione alias di esecuzione

Aggiungere un alias di esecuzione in modo che gli utenti possano eseguire la CLI per nome da qualsiasi finestra del terminale. Aggiungerlo all'interno dell'elemento <Application> (dopo <uap:VisualElements>):

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

Sostituire yourcli.exe con il nome del comando desiderato per la CLI. Dopo che un utente installa MSIX, sarà in grado di richiamare l'interfaccia della riga di comando con questo comando.

4.4 Aggiornare i metadati dell'applicazione

Aggiornare i campi seguenti in modo che corrispondano all'applicazione CLI.

• Identity: Aggiorna Name, Publisher e Version

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

• Proprietà: aggiornare il nome visualizzato, il nome visualizzato dell'editore e la descrizione

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

• VisualElements: aggiornare il nome visualizzato e i riferimenti agli asset

  <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: è anche necessario aggiungere risorse icone appropriate nella Assets cartella nella directory del pacchetto. Anche se l'app non verrà visualizzata nel menu Start, le icone sono ancora necessarie per l'invio nello Store e potrebbero essere visualizzate in altri contesti.

5. (Facoltativo) Generare un certificato di sviluppo

Per i test e la distribuzione locali all'esterno del Microsoft Store, è necessario firmare il pacchetto MSIX con un certificato.

Generare un certificato di sviluppo. Conservarlo all'esterno della cartella dell'interfaccia della riga di comando per evitare di includerlo accidentalmente nel pacchetto:

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

In questo modo viene creato un devcert.pfx file nella home directory ,ad esempio C:\Users\yourname\devcert.pfx.

Per considerare attendibile questo certificato nel computer di sviluppo, installarlo (richiede privilegi di amministratore):

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

6. Creare un pacchetto dell'interfaccia della riga di comando

A questo momento è possibile creare il pacchetto 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

Verrà creato un .msix file nella directory corrente.

7. Installare e verificare

Installare il pacchetto MSIX per verificare che tutto funzioni:

Add-AppxPackage .\MyCliPackage.msix

Se è stato aggiunto un alias di esecuzione nel passaggio 4.3, è ora possibile eseguire l'interfaccia della riga di comando da qualsiasi terminale:

yourcli --help

Per disinstallare in un secondo momento:

Get-AppxPackage *YourCLI* | Remove-AppxPackage

Tips

1. Quando si è pronti per la distribuzione, è possibile firmare MSIX con un certificato di firma del codice da un'autorità di certificazione in modo che gli utenti non devono installare un certificato autofirmato
2. Il Microsoft Store firmerà MSIX per te, non è necessario firmare prima dell'invio.
3. Potrebbe essere necessario creare più pacchetti MSIX, uno per ogni architettura supportata (x64, Arm64)

Operazioni successive

• Distribute tramite winget: Presenta il tuo MSIX al Windows Gestione pacchetti Community Repository
• Pubblica al Microsoft Store: Utilizzare winapp store per inviare il pacchetto
• Configura CI/CD: utilizza l'azione setup-WinAppCli GitHub per automatizzare il confezionamento nella pipeline