Utilisation de winapp CLI avec Tauri

Ce guide montre comment utiliser l'interface winapp CLI avec une application Tauri pour déboguer avec l'identité de package et empaqueter votre application au format MSIX.

L’identité de package est un concept de base dans le modèle Windows app. Elle permet à votre application d’accéder à des API Windows spécifiques (telles que notifications, sécurité, API IA, etc.), d’avoir une expérience d’installation/désinstallation propre, etc.

Pour obtenir un exemple de travail complet, consultez l’exemple Tauri dans ce référentiel.

Prerequisites

  1. Windows 11
  2. Node.js - winget install OpenJS.NodeJS --source winget
  3. Chaîne d’outils Rust - Installer Rust à l’aide de rustup ou winget install Rustlang.Rustup --source winget
  4. winapp CLI - winget install microsoft.winappcli --source winget

Tip

Si ces éléments sont déjà installés, exécutez les winget install commandes de toute façon pour rechercher les mises à jour.

1. Créer une application Tauri

Commencez par créer une nouvelle application Tauri en utilisant l'outil officiel de scaffolding.

npm create tauri-app@latest

Suivez les instructions :

  • Project name : tauri-app (ou votre nom préféré)
  • Langage côté client : JavaScript
  • Gestionnaire de package : npm
  • Modèle d’interface utilisateur : Vanilla
  • Aspect de l’interface utilisateur : JavaScript

Accédez à votre répertoire project et installez les dépendances :

cd tauri-app
npm install

Exécutez l’application pour vous assurer que tout fonctionne :

npm run tauri dev

2. Mettre à jour le code pour vérifier l’identité

Nous allons mettre à jour l’application pour vérifier si elle s’exécute avec l’identité du package. Nous allons utiliser un windows crate dans le back-end Rust pour accéder aux APIs Windows et les exposer sur le front-end.

Modifications du back-end (Rust)

  1. Ajouter une dépendance : ouvrez src-tauri/Cargo.toml et ajoutez les lignes suivantes à la fin du fichier. Cela ajoute les liaisons d’API Windows afin que nous puissions rechercher l’identité du package :

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

  2. Ajouter une commande : ouvrez src-tauri/src/lib.rs et ajoutez la get_package_family_name fonction. Placez-la avant la pub fn run() fonction :

    #[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. Inscrire la commande : dans le même fichier (src-tauri/src/lib.rs), mettez à jour la run fonction pour inscrire la nouvelle commande :

    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");
}

Modifications frontales (JavaScript)

  1. Mettre à jour HTML : Ouvrez src/index.html et ajoutez un paragraphe pour afficher le résultat :

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

  2. Mettre à jour la logique : Ouvrez src/main.js pour appeler la commande et affichez le résultat :

    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. À présent, exécutez l’application comme d’habitude :

    npm run tauri dev

    Vous devriez voir « Pas en cours d'exécution avec l'identité du package » dans la fenêtre de l'application. Cela confirme que la build de développement standard s’exécute sans identité de package.

3. Initialisez le projet avec l’interface en ligne de commande winapp

La winapp init commande configure tout ce dont vous avez besoin en une seule fois : manifeste d’application et ressources. Le manifeste définit l'identité de votre application (nom, éditeur, version) que Windows utilise pour accorder l'accès à l'API.

Exécutez la commande suivante et suivez les instructions :

winapp init

Lorsque vous y êtes invité :

  • Nom du package : appuyez sur Entrée pour accepter la valeur par défaut (tauri-app)
  • Publisher nom : appuyez sur Entrée pour accepter la valeur par défaut ou entrer votre nom
  • Version : appuyez sur Entrée pour accepter la version 1.0.0.0
  • Point d’entrée : appuyez sur Entrée pour accepter la valeur par défaut (tauri-app.exe)
  • Kits de développement logiciel (SDK) : sélectionnez « Ne pas configurer les kits SDK » (Tauri utilise le crate windows de Rust, pas les en-têtes SDK C++)

Cette commande va :

  • Créer Package.appxmanifest : manifeste qui définit l’identité de votre application
  • Créer un Assets dossier : icônes requises pour l’empaquetage MSIX et la soumission du Windows Store

Note

Étant donné qu'aucun package SDK n'est géré, winapp.yaml n'est pas créé — Tauri utilise le crate de windows Rust via Cargo, il n'y a donc rien à winapp restore/update suivre.

Vous pouvez ouvrir Package.appxmanifest pour personnaliser davantage les propriétés telles que le nom d’affichage, l’éditeur et les fonctionnalités.

4. Déboguer avec l'identité

Pour déboguer avec l’identité, nous devons construire le back-end Rust et l’exécuter avec winapp run. Étant donné que npm run tauri dev gère le cycle de vie du processus, il est plus difficile d’injecter l’identité là-bas. Au lieu de cela, nous allons créer un script personnalisé. Aucun certificat ou signature n’est nécessaire pour le débogage.

  1. Ajouter un script : Ouvrir package.json et ajouter un nouveau 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"
}

    Ce que fait ce script :

    • cargo build ...: recompile le back-end Rust.
    • copy ... dist\\: Met en scène uniquement l’exe dans un dist dossier (le target\debug dossier est très volumineux et contient des artefacts de build intermédiaires qui ne font pas partie de votre application).
    • winapp run .\\dist: Inscrit un package de disposition libre (comme une véritable installation MSIX) et lance l'application.

  2. Exécutez le script :

    npm run tauri:dev:withidentity

Tip

Vous pouvez voir qu’une fenêtre terminal/console apparaît derrière la fenêtre de l’application . Cela est normal pour les builds Debug Tauri (il s’agit de la console du processus Rust).

Vous devez maintenant voir l’application s’ouvrir et afficher un « Nom de famille du package », ce qui confirme qu'elle fonctionne avec l'identité ! Vous pouvez maintenant commencer à utiliser et déboguer des API qui nécessitent une identité de package, comme notifications ou les nouvelles API IA telles que Phi Silicon.

Tip

winapp run inscrit également le package sur votre système. C’est pourquoi MSIX peut apparaître comme étant « déjà installé » lorsque vous essayez de l’installer ultérieurement à l’étape 5. Utilisez winapp unregister pour nettoyer les packages de développement quand vous avez terminé.

Tip

Pour les flux de travail de débogage avancés (attachement de débogueurs, configuration de l’IDE, débogage au démarrage), consultez le Guide de débogage.

5. Package avec MSIX

Une fois que vous êtes prêt à distribuer votre application, vous pouvez la empaqueter en tant que MSIX qui fournira l’identité du package à votre application.

Tout d’abord, ajoutez un pack:msix script à votre 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"
}

Ce que fait ce script :

  • npm run tauri -- build : Génère le back-end Rust en mode release.
  • copy ... dist\\: Met uniquement en scène l'exe dans un dossier dist (le dossier target\release est très volumineux et contient des artefacts de compilation intermédiaires qui ne font pas partie de votre application).
  • winapp pack .\\dist --cert .\\devcert.pfx: package et signe l’application comme MSIX.

Générer un certificat de développement

Les packages MSIX doivent être signés. Pour les tests locaux, générez un certificat de développement auto-signé :

winapp cert generate --if-exists skip

Tip

L'éditeur du certificat doit correspondre à l'Publisher dans votre Package.appxmanifest. La cert generate commande lit cette opération automatiquement à partir de votre manifeste.

Assembler, Étape et Paquet

npm run pack:msix

Tip

La pack commande utilise automatiquement package.appxmanifest à partir de votre répertoire actif et la copie dans le dossier cible avant l’empaquetage. Le fichier .msix généré se trouvera dans le répertoire actif.

Installer le certificat

Avant de pouvoir installer le package MSIX, vous devez approuver le certificat de développement sur votre ordinateur. Exécutez cette commande en tant qu’administrateur (vous devez effectuer cette opération une seule fois par certificat) :

winapp cert install .\devcert.pfx

Installer et exécuter

Tip

Si vous avez utilisé winapp run à l’étape 4, le package peut déjà être inscrit sur votre système. Utilisez winapp unregister d’abord pour supprimer l’inscription de développement, puis installer le package de mise en production.

Installez le package en double-cliquant sur le fichier généré .msix ou à l’aide de PowerShell :

Add-AppxPackage .\tauri-app.msix

Tip

Le nom de fichier MSIX inclut la version et l’architecture (par exemple, tauri-app_1.0.0.0_x64.msix). Recherchez le nom de fichier exact dans votre répertoire. Si vous devez repackager une fois le code modifié, incrémentez le Version dans votre Package.appxmanifest , Windows nécessite un numéro de version supérieur pour mettre à jour un package installé.

Une fois installé, vous pouvez lancer votre application à partir du menu Démarrer. Vous devriez voir l'application s'exécutant avec une identité.

Conseils

  1. Une fois que vous êtes prêt à être distribué, vous pouvez signer votre MSIX avec un certificat de signature de code auprès d’une autorité de certification afin que vos utilisateurs n’aient pas besoin d’installer un certificat auto-signé.
  2. Le Microsoft Store signera le MSIX pour vous, vous n'avez pas besoin de le signer avant la soumission.
  3. Vous devrez peut-être créer plusieurs packages MSIX, un pour chaque architecture prise en charge (x64, Arm64).

Prochaines étapes

  • Last updated on