Utilisation de winapp CLI avec Rust

Ce guide montre comment utiliser l’interface winapp CLI avec une application Rust pour déboguer avec l’identité de package et empaqueter votre application en tant que MSIX.

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

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.

Un exécutable standard (tel qu’un fichier créé avec cargo build) n’a pas d’identité de package. Ce guide montre comment l’ajouter pour le débogage, et ensuite l'emballer pour la distribution.

Prerequisites

  1. Chaîne d’outils Rust : Installez Rust à l’aide de rustup ou winget (ou mettez à jour si déjà installé) :

    winget install Rustlang.Rustup --source winget

  2. winapp CLI : Installez l’outil winapp via winget (ou mettez à jour s’il est déjà installé) :

    winget install microsoft.winappcli --source winget

1. Créer une application Rust

Commencez par créer une application Rust simple :

cargo new rust-app
cd rust-app

Exécutez-le pour vous assurer que tout fonctionne :

cargo run

La sortie doit être « Hello, world ! »

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. Cela nous aidera à vérifier que l’identité fonctionne correctement dans les étapes ultérieures. Nous allons utiliser le module windows pour accéder aux API Windows.

Tout d’abord, ajoutez la windows dépendance à votre Cargo.toml en exécutant :

cargo add windows --features ApplicationModel

Cela ajoute les liaisons d’API Windows avec la fonctionnalité ApplicationModel, qui nous donne accès à l’API Package pour vérifier l’identité.

Ensuite, remplacez l’intégralité du contenu de src/main.rs par le code suivant. Ce code tente de récupérer l’identité actuelle du package. S’il réussit, il imprime le nom de la famille de packages ; sinon, il imprime « Non empaqueté ».

Note

L'exemple full inclut également du code pour afficher une notification Windows si l'identité est présente, mais pour ce guide, nous allons nous concentrer sur la vérification des identités.

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. Exécuter sans identité

À présent, générez et exécutez l’application comme d’habitude :

cargo run

La sortie « Non empaquetée » doit s’afficher. Cela confirme que l’exécutable standard est en cours d’exécution sans identité de package.

4. Initialiser le projet avec l’interface CLI 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 (rust-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
  • Description : Appuyez sur Entrée pour accepter la valeur par défaut ou entrer une description
  • Configuration des SDKs : sélectionnez « Ne pas configurer les SDKs » (Rust utilise son propre windows crate, pas les en-têtes du 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 paquet SDK n’est géré, aucun winapp.yaml n’est créé — Rust utilise le crate via Cargo, donc il n’y a 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.

Ajouter un alias d’exécution (pour les applications console)

Comme cargo new il crée une application console, nous devons ajouter un alias d’exécution au manifeste. Sans cela, winapp run lance l’application via l’activation AUMID, qui ouvre une nouvelle fenêtre , et cette fenêtre se ferme immédiatement lorsqu’une application console se termine, avalant toute sortie.

L’alias permet également aux utilisateurs d’exécuter votre application par nom à partir d’un terminal après avoir installé MSIX. Le manifeste inscrit un alias comme rust-app.exe (par défaut le nom d’exe de votre projet), que les utilisateurs peuvent appeler en tant que rust-app ou rust-app.exe.

Ignorez cette étape si vous créez une application d’interface utilisateur (une application Rust qui affiche sa propre fenêtre). Ces applications fonctionnent correctement avec le lancement AUMID par défaut.

Ajoutez l’alias :

winapp manifest add-alias

Cela ajoute une uap5:ExecutionAlias entrée à Package.appxmanifest.

5. Déboguer avec l’identité numérique

Pour tester les fonctionnalités qui nécessitent une identité (comme notifications) sans empaqueter entièrement l’application, utilisez winapp run. Cela enregistre l’intégralité du dossier de sortie de build sous la forme d’un package de disposition libre, tout comme une installation MSIX réelle, et lance l’application. Aucun certificat ou signature n’est nécessaire pour le débogage.

  1. Générez l’exécutable :

    cargo build

  2. Exécuter avec l’identité :

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

L’indicateur --with-alias lance l’application via son alias d’exécution afin que la sortie de la console reste dans le terminal actuel. Cela nécessite le uap5:ExecutionAlias que nous avons ajouté à l'étape 4.

Note

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

Vous devez maintenant voir un résultat semblable à :

Package Family Name: rust-app_12345abcde

Cela confirme que votre application est en cours d’exécution avec une identité de package valide !

Conseil / Astuce

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.

6. Package avec MSIX

Une fois que vous êtes prêt à distribuer votre application, vous pouvez la empaqueter en tant que MSIX à l’aide du même manifeste. MSIX fournit une expérience d’installation/désinstallation propre, de mises à jour automatiques et d’installation approuvée.

Préparer le répertoire du package

Tout d’abord, générez votre application en mode mise en production pour obtenir des performances optimales :

cargo build --release

Ensuite, créez un répertoire avec uniquement les fichiers nécessaires à la distribution. Le target\release dossier contient des artefacts de build qui ne font pas partie de votre application. Nous avons uniquement besoin de l’exécutable :

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

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

Important

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.

Signer et Emballer

Vous pouvez maintenant empaqueter et vous connecter en une seule étape :

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

Remarque : 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

Note

Si vous avez utilisé winapp run à l’étape 5, 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 via PowerShell :

Add-AppxPackage .\rust-app.msix

Vous pouvez maintenant exécuter votre application n’importe où dans le terminal en tapant :

rust-app

Vous devez voir la sortie « Nom de la famille de packages », confirmant son installation et son exécution avec l’identité.

Conseil / Astuce

Si vous devez repackager votre application (par exemple, après une modification du code), incrémentez le Version dans votre Package.appxmanifest, avant de lancer à nouveau winapp pack. Windows nécessite un numéro de version supérieur pour mettre à jour un package installé.

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, sans avoir à le signer vous-même 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