Utilisation de winapp CLI avec C++ et CMake

Ce guide montre comment utiliser l’interface winapp CLI avec une application C++ pour déboguer avec l’identité de package et empaqueter votre application en tant que 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.

Un exécutable standard (tel qu’un fichier créé avec cmake --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

Outils de génération : utilisez une chaîne d’outils du compilateur prise en charge par CMake. Cet exemple utilise Visual Studio. Vous pouvez installer l’édition community avec (ou mettre à jour si elle est déjà installée) :
```
winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"
```
Redémarrez après l’installation.
CMake : Installer CMake (ou mettre à jour s’il est déjà installé) :
```
winget install Kitware.CMake --source winget
```
interface CLI winapp : installez l’interface winapp cli via winget (ou mettez à jour si elle est déjà installée) :
```
winget install Microsoft.winappcli --source winget
```

1. Créer une application C++

Commencez par créer une application C++ simple. Créez un répertoire pour votre project :

mkdir cpp-app
cd cpp-app

Créez un main.cpp fichier avec un programme « Hello, world ! » de base :

#include <iostream>

int main() {
    std::cout << "Hello, world!" << std::endl;
    return 0;
}

Créez un CMakeLists.txt fichier pour configurer la build :

cmake_minimum_required(VERSION 3.20)
project(cpp-app)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(cpp-app main.cpp)

Générez et exécutez-le pour vous assurer que tout fonctionne :

cmake -B build
cmake --build build --config Debug
.\build\Debug\cpp-app.exe

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 l'API Windows Runtime C++ pour accéder aux API package.

Tout d’abord, ajoutez la ligne suivante à la fin de votre CMakeLists.txt pour établir un lien vers la bibliothèque de modèles application Windows :

# Link Windows Runtime libraries
target_link_libraries(cpp-app PRIVATE WindowsApp.lib OneCoreUap.lib)

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

#include <iostream>
#include <windows.h>
#include <appmodel.h>

int main() {
    UINT32 length = 0;
    LONG result = GetCurrentPackageFamilyName(&length, nullptr);
    
    if (result == ERROR_INSUFFICIENT_BUFFER) {
        // We have a package identity
        std::wstring familyName;
        familyName.resize(length);
        
        result = GetCurrentPackageFamilyName(&length, familyName.data());
        
        if (result == ERROR_SUCCESS) {
            std::wcout << L"Package Family Name: " << familyName.c_str() << std::endl;
        } else {
            std::wcout << L"Error retrieving Package Family Name" << std::endl;
        }
    } else {
        // No package identity
        std::cout << "Not packaged" << std::endl;
    }

    return 0;
}

3. Exécuter sans identité

Maintenant, régénérez et exécutez l’application comme d’habitude :

cmake --build build --config Debug
.\build\Debug\cpp-app.exe

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. Initialisez le projet avec l’interface CLI winapp

La commande winapp init configure tout ce dont vous avez besoin en une seule étape : manifeste d’application, ressources et éventuellement SDK d'application Windows en-têtes pour le développement C++.

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 (cpp-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 (cpp-app.exe)
Setup SDK : sélectionnez « Sdk stables » pour télécharger SDK d'application Windows et générer des en-têtes 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
Créer un dossier .winapp avec des en-têtes et des bibliothèques SDK d'application Windows
Créer un fichier de configuration winapp.yaml pour l’épinglage des versions du Kit de développement logiciel (SDK)

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)

Un alias d’exécution permet aux utilisateurs d’exécuter votre application par un nom à partir de n’importe quel terminal (par exemple cpp-app). Il permet winapp run --with-alias également pendant le développement, ce qui conserve la sortie de la console dans le terminal actuel au lieu d’ouvrir une nouvelle fenêtre.

Vous pouvez en ajouter un automatiquement :

winapp manifest add-alias

Ou manuellement : ouvrez Package.appxmanifest et ajoutez l'espace de noms uap5 à la balise <Package> s'il est manquant, puis ajoutez l'extension à l'intérieur de <Applications><Application><Extensions>... :

<Package
  ...
  xmlns:uap10="http://schemas.microsoft.com/appx/manifest/uap/windows10/10"
+ xmlns:uap5="http://schemas.microsoft.com/appx/manifest/uap/windows10/5"
  IgnorableNamespaces="uap uap2 uap3 rescap desktop desktop6 uap10">

  ...
  <Applications>
    <Application ...>
      ...
+     <Extensions>
+       <uap5:Extension Category="windows.appExecutionAlias">
+         <uap5:AppExecutionAlias>
+           <uap5:ExecutionAlias Alias="cpp-app.exe" />
+         </uap5:AppExecutionAlias>
+       </uap5:Extension>
+     </Extensions>
    </Application>
  </Applications>
</Package>

5. Déboguer avec l’identité

Pour tester les fonctionnalités qui nécessitent une identité (comme notifications) sans empaqueter entièrement l’application, vous pouvez utiliser winapp run. Cela inscrit un package de disposition libre (comme une véritable installation MSIX) et lance l’application en une seule étape. Aucun certificat ou signature n’est nécessaire pour le débogage.

Générez l’exécutable :
```
cmake --build build --config Debug
```
Exécuter avec l’identité :
```
winapp run .\build\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.

Conseil / Astuce

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 8. 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: cpp-app_12345abcde

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

Alternative : Identité de paquet éparse

Si vous avez besoin d’un comportement de package éparse spécifiquement (identité sans copie de fichiers), vous pouvez utiliser create-debug-identity à la place :

winapp create-debug-identity .\build\Debug\cpp-app.exe
.\build\Debug\cpp-app.exe

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. Utilisation de SDK d'application Windows (facultatif)

Si vous avez sélectionné de configurer les kits sdk pendant winapp init, vous avez désormais accès à des en-têtes SDK d'application Windows dans le dossier .winapp/include. Cela vous permet d’accéder à des API modernes Windows telles que les notifications, les fenêtres, l’IA sur appareil, etc. Si vous avez simplement besoin d’une identité de package pour la distribution, vous pouvez passer à l’étape 7.

Ajoutons un exemple simple qui imprime la version application Windows Runtime.

Mettre à jour CMakeLists.txt

Ajoutez la ligne suivante à la fin de votre CMakeLists.txt pour inclure les en-têtes SDK d'application Windows :

# Add Windows App SDK include directory
target_include_directories(cpp-app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/.winapp/include)

Mettre à jour main.cpp

Remplacez l’intégralité du contenu de main.cpp pour utiliser l’API runtime application Windows :

#include <iostream>
#include <windows.h>
#include <appmodel.h>
#include <winrt/Microsoft.Windows.ApplicationModel.WindowsAppRuntime.h>

int main() {
    // Initialize WinRT
    winrt::init_apartment();
    
    UINT32 length = 0;
    LONG result = GetCurrentPackageFamilyName(&length, nullptr);
    
    if (result == ERROR_INSUFFICIENT_BUFFER) {
        // We have a package identity
        std::wstring familyName;
        familyName.resize(length);
        
        result = GetCurrentPackageFamilyName(&length, familyName.data());
        
        if (result == ERROR_SUCCESS) {
            std::wcout << L"Package Family Name: " << familyName.c_str() << std::endl;
            
            // Get Windows App Runtime version using the API
            auto runtimeVersion = winrt::Microsoft::Windows::ApplicationModel::WindowsAppRuntime::RuntimeInfo::AsString();
            std::wcout << L"Windows App Runtime Version: " << runtimeVersion.c_str() << std::endl;
        } else {
            std::wcout << L"Error retrieving Package Family Name" << std::endl;
        }
    } else {
        std::cout << "Not packaged" << std::endl;
    }
    
    return 0;
}

Compiler et exécuter

Reconstruisez l’application avec les en-têtes du SDK d'application Windows :

cmake --build build --config Debug
winapp run .\build\Debug --with-alias

Vous devriez maintenant voir une sortie ressemblant à :

Package Family Name: cpp-app_12345abcde
Windows App Runtime Version: 1.8-stable (1.8.0)

Le répertoire .winapp/include contient tous les en-têtes nécessaires pour SDK d'application Windows, notamment :

winrt/ - En-têtes de projection C++ pour WinRT permettant d'accéder aux API Windows Runtime
Microsoft.UI.*.h - En-têtes WinUI 3 pour les composants d’interface utilisateur modernes
MddBootstrap.h - initialisation du SDK d'applications Windows
WindowsAppSDK-VersionInfo.h - Informations sur la version
Et bien d’autres composants SDK d'application Windows

Pour une utilisation plus avancée SDK d'application Windows, consultez la documentation SDK d'application Windows.

7. Restaurer des en-têtes si nécessaire

Le dossier .winapp est automatiquement ajouté à .gitignore par winapp init, de sorte qu’il n’est pas enregistré dans la gestion de code source. Lorsque d’autres clonent votre projet, ils doivent restaurer ces fichiers avant de générer.

Configuration manuelle

Exécutez ces deux commandes après le clonage du dépôt :

# Restore Windows App SDK headers
winapp restore

# Generate development certificate (optional - only if planning to package the app and sideload)
winapp cert generate --if-exists skip

Vous pouvez ensuite générer et exécuter normalement avec cmake -B build et cmake --build build --config Debug.

Configuration automatisée avec CMake

Vous pouvez également automatiser cette opération en ajoutant la logique d’installation à votre CMakeLists.txt. Voici le CMakeLists.txt complet avec automatisation, liaison appropriée et standard C++20 minimal :

cmake_minimum_required(VERSION 3.20)
project(cpp-app)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Download winapp CLI if not available in PATH
find_program(WINAPP_CLI winapp)
if(NOT WINAPP_CLI)
    set(WINAPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/.winapp-tools")
    set(WINAPP_CLI "${WINAPP_DIR}/winapp.exe")
    
    if(NOT EXISTS "${WINAPP_CLI}")
        message(STATUS "Downloading winapp CLI...")
        
        # Determine architecture
        if(CMAKE_SYSTEM_PROCESSOR MATCHES "ARM64|aarch64")
            set(WINAPP_ARCH "arm64")
        else()
            set(WINAPP_ARCH "x64")
        endif()
        
        # Download and extract
        set(WINAPP_ZIP "${CMAKE_CURRENT_BINARY_DIR}/winappcli.zip")
        file(DOWNLOAD 
            "https://github.com/microsoft/WinAppCli/releases/latest/download/winappcli-${WINAPP_ARCH}.zip"
            "${WINAPP_ZIP}"
            SHOW_PROGRESS
        )
        
        file(ARCHIVE_EXTRACT INPUT "${WINAPP_ZIP}" DESTINATION "${WINAPP_DIR}")
        file(REMOVE "${WINAPP_ZIP}")
        message(STATUS "winapp CLI downloaded to ${WINAPP_DIR}")
    endif()
endif()

# Automatically restore Windows App SDK headers and generate certificate if needed
# This runs once during CMake configuration, not on every build
if(NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/.winapp/include")
    message(STATUS "Restoring Windows App SDK headers...")
    execute_process(
        COMMAND "${WINAPP_CLI}" restore
        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
        RESULT_VARIABLE RESTORE_RESULT
    )
    if(NOT RESTORE_RESULT EQUAL 0)
        message(WARNING "Failed to restore Windows App SDK. Run 'winapp restore' manually.")
    endif()
endif()

if(NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/devcert.pfx")
    message(STATUS "Generating development certificate...")
    execute_process(
        COMMAND "${WINAPP_CLI}" cert generate --if-exists skip
        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
        RESULT_VARIABLE CERT_RESULT
    )
    if(NOT CERT_RESULT EQUAL 0)
        message(WARNING "Failed to generate certificate. Run 'winapp cert generate' manually.")
    endif()
endif()

add_executable(cpp-app main.cpp)

# Link Windows Runtime libraries
target_link_libraries(cpp-app PRIVATE WindowsApp.lib OneCoreUap.lib)

# Add Windows App SDK include directory
target_include_directories(cpp-app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/.winapp/include)

Avec cette configuration :

Lorsque quelqu’un clone le dépôt et s’exécute cmake -B build, winapp est automatiquement téléchargé s’il est introuvable dans PATH
Les en-têtes et le certificat SDK d'application Windows sont automatiquement restaurés
Les commandes s’exécutent une seule fois pendant la configuration (pas sur chaque build), car elles vérifient si les fichiers existent déjà.
Si les commandes échouent, CMake affiche un avertissement avec des instructions pour les exécuter manuellement
L'application winapp téléchargée est stockée dans .winapp-tools/ (ajoutez ceci à .gitignore si nécessaire)

8. 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 :

cmake --build build --config Release

Ensuite, créez un répertoire avec uniquement les fichiers nécessaires à la distribution et copiez votre exécutable de mise en production :

mkdir dist
copy .\build\Release\cpp-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

Conseil / Astuce

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

# package and sign the app with the generated certificate
winapp pack .\dist --cert .\devcert.pfx

Conseil / Astuce

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 généré .msix 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

Conseil / Astuce

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.

La winapp pack commande génère le fichier MSIX dans le répertoire racine de votre projet. Installez le package en double-cliquant sur le fichier généré .msix ou à l’aide de PowerShell :

Add-AppxPackage .\cpp-app_1.0.0.0_x64.msix

Conseil / Astuce

Le nom de fichier MSIX inclut la version et l’architecture (par exemple, cpp-app_1.0.0.0_arm64.msix). Recherchez le nom de fichier exact dans votre répertoire.

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

cpp-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

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é.
Le service Signatures de confiance Azure est un excellent moyen de gérer vos certificats en toute sécurité et d’intégrer la connexion à votre pipeline CI/CD.
Le Microsoft Store signera le MSIX pour vous, sans avoir à le signer vous-même avant la soumission.
Vous devrez peut-être créer plusieurs packages MSIX, un pour chaque architecture prise en charge (x64, Arm64). Configurez CMake avec les indicateurs de générateur et d’architecture appropriés.

Prochaines étapes

Distribute via winget : envoyez votre MSIX au dépôt Windows Gestionnaire de package Community Repository
Publish dans le Microsoft Store : utilisez winapp store pour envoyer votre package
Configurer CI/CD : utilisez l’action setup-WinAppCli GitHub pour automatiser l’empaquetage dans votre pipeline
Explorez les API Windows : avec l’identité du package, vous pouvez maintenant utiliser les Notifications, l’IA sur appareil et d’autres API dépendantes de l’identité

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-05-12

Utilisation de winapp CLI avec C++ et CMake

Prerequisites

1. Créer une application C++

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

3. Exécuter sans identité

4. Initialisez le projet avec l’interface CLI winapp

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

5. Déboguer avec l’identité

Alternative : Identité de paquet éparse

6. Utilisation de SDK d'application Windows (facultatif)

Mettre à jour CMakeLists.txt

Mettre à jour main.cpp

Compiler et exécuter

7. Restaurer des en-têtes si nécessaire

Configuration manuelle

Configuration automatisée avec CMake

8. Package avec MSIX

Préparer le répertoire du package

Générer un certificat de développement

Signer et Emballer

Installer le certificat

Installer et exécuter

Conseils

Prochaines étapes

Commentaires

Ressources supplémentaires