Uso dell'interfaccia della riga di comando di Winapp con Rust

Questa guida illustra come usare l'interfaccia a riga di comando winapp con un'applicazione Rust per eseguire il debug utilizzando l'identità del pacchetto e per impacchettare l'applicazione nel formato MSIX.

Per un esempio funzionante completo, consulta l'esempio Rust in questo repository.

L'identità del pacchetto è un concetto di base nel modello di Windows app. Consente all'applicazione di accedere a API di Windows specifiche (ad esempio Notifiche, Sicurezza, API di intelligenza artificiale e così via), avere un'esperienza di installazione/disinstallazione pulita e altro ancora.

Un eseguibile standard (come quello creato con cargo build) non ha un'identità del pacchetto. Questa guida illustra come aggiungerlo per il debug e quindi crearne il pacchetto per la distribuzione.

Prerequisiti

1. Toolchain Rust: installare Rust usando rustup o winget (o aggiornare se già installato):

   winget install Rustlang.Rustup --source winget
   

2. CLI di Winapp: installare lo strumento tramite winget (o aggiornare se già installato):

   winget install microsoft.winappcli --source winget
   

1. Creare una nuova app Rust

Per iniziare, creare una semplice applicazione Rust:

cargo new rust-app
cd rust-app

Eseguirlo per verificare che tutto funzioni:

cargo run

L'output deve essere "Hello, world!"

2. Aggiornare il codice per controllare l'identità

Aggiorneremo l'app per verificare se è in esecuzione con l'identità del pacchetto. Ciò consentirà di verificare che l'identità funzioni correttamente nei passaggi successivi. Useremo il modulo windows per accedere alle API di Windows.

Aggiungere anzitutto la dipendenza windows al tuo Cargo.toml eseguendo:

cargo add windows --features ApplicationModel

In questo modo vengono aggiunte le associazioni API Windows con la funzionalità ApplicationModel, che consente di accedere all'API Package per verificare l'identità.

Sostituire quindi l'intero contenuto di src/main.rs con il codice seguente. Questo codice tenta di recuperare l'identità del pacchetto corrente. Se ha esito positivo, stampa il nome della famiglia di pacchetti; in caso contrario, stampa "Non in pacchetto".

use windows::ApplicationModel::Package;

fn main() {
    match Package::Current() {
        Ok(package) => {
            match package.Id() {
                Ok(id) => match id.FamilyName() {
                    Ok(name) => println!("Package Family Name: {}", name),
                    Err(e) => println!("Error getting family name: {}", e),
                },
                Err(e) => println!("Error getting package ID: {}", e),
            }
        }
        Err(_) => println!("Not packaged"),
    }
}

3. Eseguire senza identità

A questo momento, compilare ed eseguire l'app come di consueto:

cargo run

Verrà visualizzato l'output "Non incluso nel pacchetto". Ciò conferma che l'eseguibile standard è in esecuzione senza alcuna identità del pacchetto.

4. Inizializzare il progetto con l'interfaccia della riga di comando di winapp

Il winapp init comando configura tutti gli elementi necessari in un'unica operazione: manifesto dell'app e asset. Il manifesto definisce l'identità dell'app (nome, editore, versione) che Windows usa per concedere l'accesso all'API.

Eseguire il comando seguente e seguire i prompt:

winapp init

Quando richiesto:

• Nome pacchetto: premere INVIO per accettare il valore predefinito (rust-app)
• Publisher nome: premere INVIO per accettare il valore predefinito o immettere il nome
• Versione: premere INVIO per accettare 1.0.0.0
• Descrizione: premere INVIO per accettare l'impostazione predefinita o immettere una descrizione
• Configurazione SDK: selezionare "Non configurare gli SDK" (Rust usa il proprio windows crate, non le intestazioni SDK C++)

Questo comando consentirà di:

• Crea Package.appxmanifest : manifesto che definisce l'identità dell'app
• Crea Assets cartella : icone necessarie per l'invio di pacchetti MSIX e dello Store

È possibile aprire Package.appxmanifest per personalizzare ulteriormente le proprietà, ad esempio il nome visualizzato, l'editore e le funzionalità.

Aggiungere alias di esecuzione (per le app console)

Poiché cargo new crea un'app console, è necessario aggiungere un alias di esecuzione al manifesto. Senza di esso, winapp run avvia l'app tramite l'attivazione AUMID, che apre una nuova finestra, e tale finestra si chiude immediatamente al termine di un'app console, ingoiando qualsiasi output.

L'alias consente anche agli utenti di eseguire l'app in base al nome da qualsiasi terminale dopo aver installato MSIX. Il manifesto registra un alias come rust-app.exe che per impostazione predefinita corrisponde al nome exe del progetto, che gli utenti possono richiamare come rust-app o rust-app.exe.

Ignorare questo passaggio se si sta creando un'app dell'interfaccia utente (un'app Rust che esegue il rendering della propria finestra). Queste app funzionano correttamente con l'avvio AUMID predefinito.

Aggiungere l'alias:

winapp manifest add-alias

In questo modo viene aggiunta una uap5:ExecutionAlias voce a Package.appxmanifest.

5. Eseguire il debug con l'identità

Per testare le funzionalità che richiedono identità (ad esempio Notifiche) senza creare pacchetti completi dell'app, usare winapp run. Questa operazione registra l'intera cartella di output di compilazione come pacchetto di layout libero, proprio come un'installazione MSIX reale, e avvia l'app. Non è necessario alcun certificato o firma per il debug.

1. Compilare il file eseguibile:

   cargo build
   

2. Esegui con privilegi di identità:

   winapp run .\target\debug --with-alias
   

L'opzione --with-alias avvia l'app utilizzando il suo alias di esecuzione in modo che l'output della console rimanga nel terminale corrente. Questo richiede l'aggiunta uap5:ExecutionAlias nel passaggio 4.

Verrà ora visualizzato un output simile al seguente:

Package Family Name: rust-app_12345abcde

Ciò conferma che l'app è in esecuzione con un'identità del pacchetto valida.

6. Pacchetto con MSIX

Quando si è pronti per distribuire l'app, è possibile crearne il pacchetto come MSIX usando lo stesso manifesto. MSIX offre installazione/disinstallazione pulita, aggiornamenti automatici e un'esperienza di installazione attendibile.

Preparare la directory del pacchetto

Prima di tutto, compilare l'applicazione in modalità di rilascio per ottenere prestazioni ottimali:

cargo build --release

Creare quindi una directory con solo i file necessari per la distribuzione. La target\release cartella contiene artefatti di compilazione che non fanno parte dell'app, ma è necessario solo il file eseguibile:

mkdir dist
copy .\target\release\rust-app.exe .\dist\

Generare un certificato di sviluppo

I pacchetti MSIX devono essere firmati. Per i test locali, generare un certificato di sviluppo autofirmato:

winapp cert generate --if-exists skip

Firma e pacchetto

Ora è possibile creare un pacchetto e firmarlo digitalmente in un unico passaggio.

winapp pack .\dist --cert .\devcert.pfx 

Nota: Il pack comando usa automaticamente il file Package.appxmanifest dalla directory corrente e lo copia nella cartella di destinazione prima del confezionamento. Il file con estensione msix generato si troverà nella directory corrente.

Installare il certificato

Prima di poter installare il pacchetto MSIX, è necessario considerare attendibile il certificato di sviluppo nel computer. Eseguire questo comando come amministratore (è necessario eseguire questa operazione una sola volta per ogni certificato):

winapp cert install .\devcert.pfx

Installare ed eseguire

Installare il pacchetto facendo doppio clic sul file generato .msix o tramite PowerShell:

Add-AppxPackage .\rust-app.msix

È ora possibile eseguire l'app da qualsiasi punto del terminale digitando:

rust-app

Verrà visualizzato l'output "Package Family Name", che conferma che è installato e in esecuzione con l'identità.

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
• API Explore Windows: Con l'identità del pacchetto, è ora possibile usare Notifications, on-device AI e altre API dipendenti da identity