Uso della CLI di winapp con Tauri

Questa guida illustra come usare la CLI winapp con un'applicazione Tauri per eseguire il debug con l'identità del pacchetto e confezionare l'applicazione come MSIX.

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.

Per un esempio funzionante completo, vedere l'esempio Tauri in questo repository.

Prerequisiti

1. Windows 11
2. Node.js - winget install OpenJS.NodeJS --source winget
3. Toolchain Rust - Installare Rust usando rustup o winget install Rustlang.Rustup --source winget
4. Interfaccia della riga di comando di winapp - winget install microsoft.winappcli --source winget

1. Creare una nuova app Tauri

Inizia creando una nuova applicazione Tauri utilizzando lo strumento di scaffolding ufficiale:

npm create tauri-app@latest

Seguire le istruzioni:

• Project name: tauri-app (o il nome preferito)
• Linguaggio front-end: JavaScript
• Gestione pacchetti: npm
• Modello di interfaccia utente: Vanilla
• Sapore dell'interfaccia utente: JavaScript

Naviga nella directory del tuo progetto e installa le tue dipendenze.

cd tauri-app
npm install

Eseguire l'app per assicurarsi che tutto funzioni:

npm run tauri dev

2. Aggiornare il codice per controllare l'identità

Aggiorneremo l'app per verificare se è in esecuzione con l'identità del pacchetto. Si userà la "crate" nel backend di Rust per accedere alle API di Windows ed esporlo al frontend.

Modifiche Backend (Rust)

1. Aggiungi dipendenza: aprire src-tauri/Cargo.toml e aggiungere le righe seguenti alla fine del file. In questo modo vengono aggiunte le associazioni API Windows in modo da poter verificare l'identità del pacchetto:

   [target.'cfg(windows)'.dependencies]
   windows = { version = "0.58", features = ["ApplicationModel"] }
   

2. Aggiungi comando: aprire src-tauri/src/lib.rs e aggiungere la get_package_family_name funzione . Posizionarlo prima della pub fn run() funzione:

   #[tauri::command]
   fn get_package_family_name() -> String {
       #[cfg(target_os = "windows")]
       {
           use windows::ApplicationModel::Package;
           match Package::Current() {
               Ok(package) => {
                   match package.Id() {
                       Ok(id) => match id.FamilyName() {
                           Ok(name) => name.to_string(),
                           Err(_) => "Error retrieving Family Name".to_string(),
                       },
                       Err(_) => "Error retrieving Package ID".to_string(),
                   }
               }
               Err(_) => "No package identity".to_string(),
           }
       }
       #[cfg(not(target_os = "windows"))]
       {
           "Not running on Windows".to_string()
       }
   }
   

3. Comando Register: nello stesso file (src-tauri/src/lib.rs), aggiornare la run funzione per registrare il nuovo comando:

   pub fn run() {
       tauri::Builder::default()
           .plugin(tauri_plugin_opener::init())
           .invoke_handler(tauri::generate_handler![greet, get_package_family_name]) // Add get_package_family_name here
           .run(tauri::generate_context!())
           .expect("error while running tauri application");
   }
   

Modifiche front-end (JavaScript)

1. Aggiornare HTML: aprire src/index.html e aggiungere un paragrafo per visualizzare il risultato:

   <!-- ... inside <main> ... -->
   <p id="pfn-msg"></p>
   

2. Aggiorna logica: aprire src/main.js per richiamare il comando e visualizzare il risultato:

   const { invoke } = window.__TAURI__.core;
   
   // ... existing code ...
   
   async function checkPackageIdentity() {
     const pfn = await invoke("get_package_family_name");
     const pfnMsgEl = document.querySelector("#pfn-msg");
   
     if (pfn !== "No package identity" && !pfn.startsWith("Error")) {
       pfnMsgEl.textContent = `Package family name: ${pfn}`;
     } else {
       pfnMsgEl.textContent = `Not running with package identity`;
     }
   }
   
   window.addEventListener("DOMContentLoaded", () => {
     // ... existing code ...
     checkPackageIdentity();
   });
   

3. Eseguire ora l'app come di consueto:

   npm run tauri dev
   

   Nella finestra dell'app verrà visualizzato "Not running with package identity" (Non in esecuzione con l'identità del pacchetto). Ciò conferma che la compilazione di sviluppo standard è in esecuzione senza identità del pacchetto.

3. Inizializzare Project con la CLI 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 (tauri-app)
• Publisher nome: premere INVIO per accettare il valore predefinito o immettere il nome
• Versione: premere INVIO per accettare 1.0.0.0
• Punto di ingresso: premere INVIO per accettare il valore predefinito (tauri-app.exe)
• Configurazione SDK: selezionare "Non configurare gli SDK" (Tauri utilizza i crate di windows Rust, non le intestazioni dell'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à.

4. Eseguire il debug con l'identità

Per eseguire il debug utilizzando l'identità, è necessario costruire il back-end Rust ed eseguirlo con winapp run. Poiché npm run tauri dev gestisce il ciclo di vita del processo, è più difficile inserire l'identità. Verrà invece creato uno script personalizzato. Non è necessario alcun certificato o firma per il debug.

1. Aggiungi script: aprire package.json e aggiungere un nuovo script tauri:dev:withidentity:

   "scripts": {
     "tauri": "tauri",
     "tauri:dev:withidentity": "cargo build --manifest-path src-tauri/Cargo.toml && (if not exist dist mkdir dist) && copy /Y src-tauri\\target\\debug\\tauri-app.exe dist\\ >nul && winapp run .\\dist"
   }
   

   Cosa fa questo script:

   • cargo build ...: ricompila il back-end Rust.
   • copy ... dist\\: inserisce solo l'exe in una dist cartella (la target\debug cartella è molto grande e contiene artefatti di compilazione intermedi che non fanno parte dell'app).
   • winapp run .\\dist: registra un pacchetto di layout libero (proprio come un'installazione MSIX reale) e avvia l'app.

2. Eseguire lo script:

   npm run tauri:dev:withidentity
   

Dovresti ora vedere l'app aperta e un "Nome famiglia di pacchetti" viene visualizzato, confermando che è in esecuzione con l'identità verificata. È ora possibile iniziare a usare e eseguire il debug di API che richiedono l'identità del pacchetto, ad esempio Notifiche o le nuove API di intelligenza artificiale come Phi Silica.

5. Pacchetto con MSIX

Dopo aver distribuito l'app, è possibile crearne il pacchetto come MSIX che fornirà l'identità del pacchetto all'applicazione.

Per prima cosa, aggiungi uno pack:msix script a package.json:

"scripts": {
  "tauri": "tauri",
  "tauri:dev:withidentity": "...",
  "pack:msix": "npm run tauri -- build && (if not exist dist mkdir dist) && copy /Y src-tauri\\target\\release\\tauri-app.exe dist\\ >nul && winapp pack .\\dist --cert .\\devcert.pfx"
}

Cosa fa questo script:

• npm run tauri -- build: compila il back-end Rust in modalità di rilascio.
• copy ... dist\\: inserisce solo l'exe in una dist cartella (la target\release cartella è molto grande e contiene artefatti di compilazione intermedi che non fanno parte dell'app).
• winapp pack .\\dist --cert .\\devcert.pfx: crea pacchetti e firma l'app come MSIX.

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

Compilazione, fase e pacchetto

npm run pack:msix

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 usando PowerShell:

Add-AppxPackage .\tauri-app.msix

Dopo l'installazione, è possibile avviare l'app dal menu Start. Verrà visualizzata l'app in esecuzione con 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