Winapp CLI gebruiken met C++ en CMake

In deze handleiding ziet u hoe u de winapp CLI gebruikt met een C++-toepassing om fouten op te sporen met pakketidentiteit en uw toepassing als msix te verpakken.

Pakketidentiteit is een kernconcept in het Windows app model. Hiermee heeft uw toepassing toegang tot specifieke Windows API's (zoals meldingen, beveiliging, AI-API's, enzovoort), een schone installatie-/verwijderingservaring en meer.

Een standaard uitvoerbaar bestand (zoals een bestand dat is gemaakt met cmake --build) heeft geen pakketidentiteit. In deze handleiding ziet u hoe u deze toevoegt voor foutopsporing en deze vervolgens inpakt voor distributie.

Vereiste voorwaarden

1. Build Tools: Gebruik een compilerhulpprogrammaketen die wordt ondersteund door CMake. In dit voorbeeld wordt Visual Studio gebruikt. U kunt de community-editie installeren met (of bijwerken als deze al is geïnstalleerd):

   winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"
   

   Start opnieuw op na de installatie.

2. CMake: CMake installeren (of bijwerken als deze al is geïnstalleerd):

   winget install Kitware.CMake --source winget
   

3. winapp CLI: installeer de winapp cli via winget (of werk bij als deze al is geïnstalleerd):

   winget install Microsoft.winappcli --source winget
   

1. Een nieuwe C++-app maken

Begin met het maken van een eenvoudige C++-toepassing. Maak een nieuwe map voor uw project:

mkdir cpp-app
cd cpp-app

Maak een main.cpp bestand met een eenvoudig 'Hallo wereld!'-programma:

#include <iostream>

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

Maak een CMakeLists.txt bestand om de build te configureren:

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)

Bouw en voer het uit om ervoor te zorgen dat alles werkt:

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

Uitvoer moet 'Hallo, wereld!' zijn

2. Code bijwerken om identiteit te controleren

We werken de app bij om te controleren of deze wordt uitgevoerd met pakketidentiteit. Dit helpt ons te controleren of de identiteit in latere stappen correct werkt. We gebruiken de Windows Runtime C++-API voor toegang tot de pakket-API's.

Voeg eerst de volgende regel toe aan het einde van uw CMakeLists.txt om een koppeling te maken met de Windows-app Modelbibliotheek:

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

Vervang vervolgens de volledige inhoud van main.cpp door de volgende code. Met deze code wordt geprobeerd de huidige pakketidentiteit op te halen met behulp van de Windows Runtime-API. Als het lukt, wordt de familienaam van het pakket afgedrukt; anders wordt 'Niet verpakt' afgedrukt.

#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. Uitvoeren zonder identiteit

Bouw nu de app opnieuw en voer deze uit zoals gebruikelijk:

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

U zou de uitvoer 'Niet verpakt' moeten zien. Hiermee wordt bevestigd dat het standaard uitvoerbare bestand wordt uitgevoerd zonder pakketidentiteit.

4. Initialiseer Project met winapp CLI

Met de opdracht winapp init stelt u alles in wat u nodig hebt: app-manifest, assets en optioneel Windows App SDK headers voor C++-ontwikkeling.

Voer de volgende opdracht uit en volg de aanwijzingen:

winapp init .

Wanneer u hierom wordt gevraagd:

• Pakketnaam: druk op Enter om de standaardwaarde te accepteren (cpp-app)
• Publisher naam: Druk op Enter om de standaardinstelling te accepteren of voer uw naam in
• Versie: Druk op Enter om 1.0.0.0 te accepteren
• Toegangspunt: Druk op Enter om de standaardwaarde (cpp-app.exe) te accepteren
• Setup SDK's: Selecteer 'Stabiele SDK's' om Windows App SDK te downloaden en C++-headers te genereren

Met deze opdracht wordt het volgende uitgevoerd:

• Maken Package.appxmanifest : het manifest waarmee de identiteit van uw app wordt gedefinieerd
• Map maken Assets : pictogrammen die vereist zijn voor MSIX-pakketten en Store-inzending
• Een map .winapp maken met Windows App SDK headers en bibliotheken
• winapp.yaml Een configuratiebestand maken voor het vastmaken van SDK-versies

U kunt openen Package.appxmanifest om eigenschappen zoals de weergavenaam, uitgever en mogelijkheden verder aan te passen.

Uitvoeringsalias toevoegen (voor console-apps)

Met een uitvoeringsalias kunnen gebruikers uw app op naam uitvoeren vanuit elke terminal (zoals cpp-app). Het maakt het ook mogelijk winapp run --with-alias tijdens de ontwikkeling, waardoor console-uitvoer in de huidige terminal wordt behouden in plaats van een nieuw venster te openen.

U kunt er automatisch een toevoegen:

winapp manifest add-alias

Of handmatig: open Package.appxmanifest en voeg de uap5 naamruimte toe aan de <Package> tag als deze ontbreekt en voeg vervolgens de extensie toe binnen <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. Debuggen met identiteit

Als u functies wilt testen waarvoor identiteit (zoals meldingen) is vereist zonder de app volledig te verpakken, kunt u dit gebruiken winapp run. Hiermee wordt een losse indelingspakket geregistreerd (net als bij een echte MSIX-installatie) en wordt de app in één stap gestart. Er is geen certificaat of ondertekening nodig voor foutopsporing.

1. Bouw het uitvoerbare bestand:

   cmake --build build --config Debug
   

2. Uitvoeren met identiteit:

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

De --with-alias vlag start de app via de uitvoeringsalias, zodat de console-uitvoer in de huidige terminal blijft. Hiervoor is vereist dat we uap5:ExecutionAlias in stap 4 hebben toegevoegd.

U ziet nu uitvoer die vergelijkbaar is met:

Package Family Name: cpp-app_12345abcde

Hiermee wordt bevestigd dat uw app wordt uitgevoerd met een geldige pakketidentiteit.

Alternatief: Sparse-pakketidentiteit

Als u specifiek sparse-pakketgedrag nodig hebt (identiteit zonder bestanden te kopiëren), kunt u in plaats daarvan het volgende gebruiken create-debug-identity :

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

6. Windows App SDK gebruiken (optioneel)

Als u hebt geselecteerd om de SDK's in te stellen tijdens winapp init, hebt u nu toegang tot Windows App SDK headers in de map .winapp/include. Dit biedt u toegang tot moderne Windows API's, zoals meldingen, vensters, AI op apparaat en meer. Als u alleen pakketidentiteit nodig hebt voor distributie, kunt u doorgaan naar stap 7.

Laten we een eenvoudig voorbeeld toevoegen waarmee de Windows-app Runtime-versie wordt afgedrukt.

CMakeLists.txt bijwerken

Voeg de volgende regel toe aan het einde van uw CMakeLists.txt om de Windows App SDK headers op te nemen:

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

Main.cpp bijwerken

Vervang de volledige inhoud van main.cpp om de Windows-app Runtime-API te gebruiken:

#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;
}

Bouwen en uitvoeren

Bouw de toepassing opnieuw met de Windows App SDK headers:

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

U ziet nu uitvoer zoals:

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

De map .winapp/include bevat alle benodigde headers voor Windows App SDK, waaronder:

• winrt/ - WinRT C++ projectieheaders voor toegang tot Windows Runtime API's
• Microsoft.UI.*.h - WinUI 3-headers voor moderne UI-onderdelen
• MddBootstrap.h - Windows App SDK opstarten
• WindowsAppSDK-VersionInfo.h - Versie-informatie
• En nog veel meer Windows App SDK onderdelen

Raadpleeg de documentatie Windows App SDK voor geavanceerdere Windows App SDK gebruik.

7. Headers herstellen wanneer dat nodig is

De .winapp map wordt automatisch toegevoegd door .gitignorewinapp init, zodat deze niet wordt ingecheckt in broncodebeheer. Wanneer anderen uw project klonen, moeten ze deze bestanden herstellen voordat ze worden gebouwd.

Handmatige installatie

Voer deze twee opdrachten uit na het klonen van de opslagplaats:

# 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

Vervolgens kunt u normaal bouwen en uitvoeren met cmake -B build en cmake --build build --config Debug.

Geautomatiseerde installatie met CMake

U kunt dit ook automatiseren door installatielogica toe te voegen aan uw CMakeLists.txt. Dit is het volledige CMakeLists.txt met automatisering, juiste koppeling en minimale C++20-standaard:

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)

Met deze installatie:

• Wanneer iemand de opslagplaats kloont en cmake -B build uitvoert, wordt winapp automatisch gedownload als die niet in de PATH is gevonden.
• De Windows App SDK headers en certificaten worden automatisch hersteld
• De opdrachten worden slechts eenmaal uitgevoerd tijdens de configuratie (niet op elke build), omdat ze controleren of de bestanden al bestaan
• Als de opdrachten mislukken, geeft CMake een waarschuwing weer met instructies om ze handmatig uit te voeren
• De gedownloade winapp wordt opgeslagen in .winapp-tools/ (voeg deze indien nodig toe aan .gitignore)

8. Pakket met MSIX

Zodra u klaar bent om uw app te distribueren, kunt u deze verpakken als een MSIX met hetzelfde manifest. MSIX biedt schone installatie/verwijdering, automatische updates en een vertrouwde installatie-ervaring.

De pakketmap voorbereiden

Bouw eerst uw toepassing in de releasemodus voor optimale prestaties:

cmake --build build --config Release

Maak vervolgens een map met alleen de bestanden die nodig zijn voor distributie en kopieer het uitvoerbare bestand van de release:

mkdir dist
copy .\build\Release\cpp-app.exe .\dist\

Een ontwikkelingscertificaat genereren

MSIX-pakketten moeten zijn ondertekend. Genereer voor lokaal testen een zelfondertekend ontwikkelingscertificaat:

winapp cert generate --if-exists skip

Ondertekenen en inpakken

U kunt nu het volgende inpakken en ondertekenen:

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

Het certificaat installeren

Voordat u het MSIX-pakket kunt installeren, moet u het ontwikkelingscertificaat op uw computer vertrouwen. Voer deze opdracht uit als beheerder (u hoeft dit slechts één keer per certificaat te doen):

winapp cert install .\devcert.pfx

Installeren en uitvoeren

Met de winapp pack opdracht wordt het MSIX-bestand in de hoofdmap van uw project gegenereerd. Installeer het pakket door te dubbelklikken op het gegenereerde .msix bestand of met behulp van PowerShell:

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

U kunt nu uw app vanaf elke locatie in de terminal uitvoeren door het volgende te typen:

cpp-app

Als het goed is, ziet u de uitvoer "Package Family Name", waarin wordt bevestigd dat deze is geïnstalleerd en uitgevoerd met identiteit.

Tips

1. Zodra u klaar bent voor distributie, kunt u uw MSIX ondertekenen met een certificaat voor ondertekening van programmacode van een certificeringsinstantie, zodat uw gebruikers geen zelfondertekend certificaat hoeven te installeren.
2. De Vertrouwde ondertekening van Azure-service is een uitstekende manier om uw certificaten veilig te beheren en aanmelding te integreren in uw CI/CD-pijplijn.
3. De Microsoft Store zal de MSIX voor u ondertekenen, u hoeft deze niet te ondertekenen voordat u hem indient.
4. Mogelijk moet u meerdere MSIX-pakketten maken, één voor elke architectuur die u ondersteunt (x64, Arm64). Configureer CMake met de juiste generator- en architectuurvlagmen.

Volgende stappen

• Distribute via winget: Dien uw MSIX in bij de Windows Pakketbeheer Community-opslagplaats
• Publiceren naar de Microsoft Store: gebruik winapp store om uw pakket in te dienen
• Set up CI/CD: Gebruik de GitHub Actie setup-WinAppCli om automatisering van het verpakken in uw pijplijn te realiseren.
• Explore Windows API's: Met pakketidentiteit kunt u nu meldingen, on-device AI en andere identiteitsafhankelijke API's gebruiken