Použití rozhraní příkazového řádku winapp s C++ a CMake

Tato příručka ukazuje, jak pomocí rozhraní příkazového winapp řádku spolu s aplikací C++ ladit aplikaci s identitou balíčku a jak ji zabalit jako MSIX.

Identita balíčku je základním konceptem modelu Windows app. Umožňuje vaší aplikaci přistupovat ke konkrétním rozhraním API Windows (jako jsou oznámení, zabezpečení, rozhraní API AI atd.), mají čisté prostředí pro instalaci a odinstalaci a další.

Standardní spustitelný soubor (například vytvořený pomocí cmake --build) nemá identitu balíčku. Tento průvodce ukazuje, jak ho přidat pro ladění a pak ho zabalit pro distribuci.

Předpoklady

Nástroje sestavení: Použijte sadu nástrojů kompilátoru podporovanou nástrojem CMake. Tento příklad používá Visual Studio. Komunitní edici můžete nainstalovat (nebo aktualizovat, pokud už je nainstalovaná):
```
winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"
```
Po instalaci restartujte počítač.
CMake: Nainstalujte CMake (nebo aktualizujte, pokud už je nainstalovaný):
```
winget install Kitware.CMake --source winget
```
winapp CLI: Nainstalujte winapp CLI pomocí winget (nebo aktualizujte, je-li už nainstalované):
```
winget install Microsoft.winappcli --source winget
```

1. Vytvoření nové aplikace C++

Začněte vytvořením jednoduché aplikace jazyka C++. Vytvořte nový adresář pro project:

mkdir cpp-app
cd cpp-app

Vytvořte main.cpp soubor se základním programem "Hello, world!":

#include <iostream>

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

Vytvořte CMakeLists.txt soubor pro konfiguraci sestavení:

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)

Sestavte a spusťte ho, abyste měli jistotu, že všechno funguje:

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

Výstup by měl být "Hello, world!"

2. Aktualizace kódu pro kontrolu identity

Aplikaci aktualizujeme a zkontrolujeme, jestli běží s identitou balíčku. To nám pomůže ověřit, jestli identita funguje správně v dalších krocích. Pro přístup k rozhraním API balíčků použijeme rozhraní API prostředí Windows Runtime C++.

Nejprve na konec CMakeLists.txt přidejte následující řádek pro propojení s knihovnou modelu aplikace pro Windows:

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

Dále nahraďte celý obsah main.cpp následujícím kódem. Tento kód se pokusí načíst aktuální identitu balíčku pomocí rozhraní WINDOWS RUNTIME API. Pokud bude úspěšný, vytiskne název rodiny balíčků; jinak se vytiskne "Není zabaleno".

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

Spusťte (program) bez přiřazené identity.

Teď znovu sestavte a spusťte aplikaci obvyklým způsobem:

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

Měl by se zobrazit výstup "Není zabaleno". Tím potvrdíte, že standardní spustitelný soubor běží bez jakékoli identity balíčku.

4. Inicializace Project pomocí rozhraní příkazového řádku winapp

Příkaz winapp init nastaví vše, co potřebujete najednou: manifest aplikace, prostředky a volitelné hlavičky Windows App SDK pro vývoj v C++.

Spusťte následující příkaz a postupujte podle pokynů:

winapp init .

Po zobrazení výzvy:

Název balíčku: Stisknutím klávesy Enter přijměte výchozí hodnotu (cpp-app).
Publisher název: Stisknutím klávesy Enter přijměte výchozí hodnotu nebo zadejte své jméno.
Verze: Stisknutím klávesy Enter přijměte verzi 1.0.0.0.
Vstupní bod: Stisknutím klávesy Enter přijměte výchozí (cpp-app.exe)
Nastavení sad SDK: Pokud chcete stáhnout Windows App SDK a vygenerovat hlavičky C++, vyberte Stabilní sady SDK.

Tento příkaz:

Vytvoření Package.appxmanifest – manifest, který definuje identitu vaší aplikace
Vytvoření Assets složky – ikony vyžadované pro balení MSIX a odesílání do Storu
Vytvoření složky .winapp s hlavičkami a knihovnami Windows App SDK
Vytvoření konfiguračního winapp.yaml souboru pro připnutí verzí sady SDK

Můžete otevřít Package.appxmanifest a upravit vlastnosti, jako je zobrazovaný název, vydavatel a možnosti.

Přidání spuštěcího aliasu (pro konzolové aplikace)

Alias spuštění umožňuje uživatelům spouštět aplikaci podle názvu z libovolného terminálu (například cpp-app). Umožňuje také winapp run --with-alias během vývoje, což udržuje výstup konzoly v aktuálním terminálu místo otevření nového okna.

Můžete ho přidat automaticky:

winapp manifest add-alias

Nebo ručně: otevřete Package.appxmanifest a přidejte obor názvů uap5 do značky <Package>, pokud chybí, a pak přidejte rozšíření do <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. Ladění pomocí identity

Pokud chcete otestovat funkce, které vyžadují identitu (jako oznámení), aniž by se aplikace plně zabalily, můžete použít winapp run. Tím se zaregistruje volný balíček rozložení (stejně jako skutečná instalace MSIX) a spustí se aplikace v jednom kroku. Pro ladění není potřeba žádný certifikát ani podepisování.

Sestavení spustitelného souboru:
```
cmake --build build --config Debug
```
Spusťte s identitou:
```
winapp run .\build\Debug --with-alias
```

Příznak --with-alias spustí aplikaci prostřednictvím svého aliasu spuštění, takže výstup konzoly zůstane v aktuálním terminálu. To vyžaduje uap5:ExecutionAlias, který jsme přidali v kroku 4.

Návod

winapp run také zaregistruje balíček ve vašem systému. To je důvod, proč se MSIX může při pokusu o jeho instalaci později v kroku 8 zobrazit jako již nainstalovaný. Slouží winapp unregister k vyčištění vývojových balíčků po dokončení.

Teď by se měl zobrazit výstup podobný následujícímu:

Package Family Name: cpp-app_12345abcde

Tím potvrdíte, že vaše aplikace běží s platnou identitou balíčku.

Alternativa: Neúplná identita balíčku

Pokud potřebujete konkrétně řídké chování balíčku (identita bez kopírování souborů), můžete místo toho použít create-debug-identity :

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

Návod

Pokročilé ladicí pracovní postupy (připojení ladicích programů, nastavení integrovaného vývojového prostředí, ladění po spuštění) najdete v průvodci laděním.

6. Použití Windows App SDK (volitelné)

Pokud jste během winapp init vybrali instalaci sad SDK, nyní máte přístup k záhlavím Windows App SDK ve složce .winapp/include. Díky tomu máte přístup k moderním Windows rozhraním API, jako jsou oznámení, okna, AI na zařízení a další. Pokud potřebujete jenom identitu balíčku pro distribuci, můžete přeskočit ke kroku 7.

Pojďme přidat jednoduchý příklad, který vytiskne verzi aplikace pro Windows Runtime.

Aktualizace CMakeLists.txt

Na konec CMakeLists.txt přidejte následující řádek, který zahrne záhlaví Windows App SDK:

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

Aktualizace main.cpp

Nahraďte celý obsah main.cpp pro použití rozhraní API modulu aplikace pro Windows Runtime:

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

Sestavení a spuštění

Znovu sestavte aplikaci pomocí hlaviček Windows App SDK:

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

Teď by se měl zobrazit výstup jako:

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

Adresář .winapp/include obsahuje všechna potřebná záhlaví pro Windows App SDK, včetně:

winrt/ – hlavičky projekce WinRT C++ pro přístup k rozhraním API prostředí Windows Runtime
Microsoft.UI.*.h – hlavičky WinUI 3 pro moderní komponenty uživatelského rozhraní
MddBootstrap.h – spouštění Windows App SDK
WindowsAppSDK-VersionInfo.h - Informace o verzi
A mnoho dalších komponent Windows App SDK

Pokud chcete pokročilejší Windows App SDK využití, přečtěte si dokumentaci k Windows App SDK.

7. V případě potřeby obnovte hlavičky.

Složka .winapp se automaticky přidá do .gitignorewinapp init, takže se neuloží do správy zdrojového kódu. Když ostatní naklonují váš projekt, budou muset tyto soubory před sestavením obnovit.

Ruční nastavení

Po naklonování úložiště spusťte tyto dva příkazy:

# 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

Pak můžete sestavovat a spouštět normálně s cmake -B build a cmake --build build --config Debug.

Automatizované nastavení pomocí CMake

Alternativně to můžete automatizovat přidáním logiky nastavení do vašeho CMakeLists.txtpočítače . Zde je kompletní CMakeLists.txt se zahrnutím automatizace, správným propojením a minimálním standardem C++20:

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)

S tímto nastavením:

Když někdo naklonuje úložiště a cmake -B build se spustí, winapp se automaticky stáhne, pokud se nenajde v PATH.
Záhlaví Windows App SDK a certifikát se automaticky obnoví.
Příkazy se spouští pouze jednou během konfigurace (ne v každém sestavení), protože kontrolují, jestli soubory už existují.
Pokud příkazy selžou, CMake zobrazí upozornění s pokyny ke spuštění ručně.
Stažená aplikace WinApp je uložená v .winapp-tools/ (přidejte do .gitignore, pokud je to potřeba).

8. Balíček s MSIX

Jakmile budete připraveni distribuovat aplikaci, můžete ji zabalit jako MSIX pomocí stejného manifestu. MSIX poskytuje čistou instalaci/odinstalaci, automatické aktualizace a důvěryhodné instalační prostředí.

Příprava adresáře balíčků

Nejprve sestavte aplikaci v režimu vydávání, abyste mohli dosáhnout optimálního výkonu:

cmake --build build --config Release

Pak vytvořte adresář pouze se soubory potřebnými k distribuci a zkopírujte spustitelný soubor vydané verze:

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

Vygenerování vývojového certifikátu

Balíčky MSIX musí být podepsané. Pro místní testování vygenerujte vývojový certifikát podepsaný svým držitelem:

winapp cert generate --if-exists skip

Návod

Publisher certifikátu musí odpovídat Publisher ve vašem Package.appxmanifest. Automaticky tento cert generate příkaz načte z manifestu.

Podepsání a balení

Teď můžete zabalit a podepsat:

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

Návod

Příkaz pack před zabalení automaticky použije Package.appxmanifest z aktuálního adresáře a zkopíruje ho do cílové složky. Vygenerovaný .msix soubor bude v aktuálním adresáři.

Instalace certifikátu

Než budete moct nainstalovat balíček MSIX, musíte na svém počítači důvěřovat vývojovému certifikátu. Spusťte tento příkaz jako správce (stačí to udělat jenom jednou pro každý certifikát):

winapp cert install .\devcert.pfx

Instalace a spuštění

Návod

Pokud jste tento balíček použili winapp run v kroku 5, možná už je v systému zaregistrovaný. Nejprve winapp unregister odeberte registraci vývojové verze a pak nainstalujte produkční balíček.

Příkaz winapp pack vygeneruje soubor MSIX v kořenovém adresáři projektu. Nainstalujte balíček poklikáním na vygenerovaný .msix soubor nebo pomocí PowerShellu:

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

Návod

Název souboru MSIX zahrnuje verzi a architekturu (např cpp-app_1.0.0.0_arm64.msix. ). Zkontrolujte přesný název souboru v adresáři.

Teď můžete aplikaci spustit odkudkoli v terminálu zadáním:

cpp-app

Měl by se zobrazit výstup "Název rodiny balíčků", čímž se potvrdí jeho instalace a spuštění pod danou identitou.

Návod

Pokud potřebujete aplikaci znovu přebalit (např. po změně kódu), před dalším spuštěním Package.appxmanifest zvyšte hodnotu Version. Windows k aktualizaci nainstalovaného balíčku vyžaduje vyšší číslo verze.

Tips

Jakmile budete připraveni k distribuci, můžete podepisovat MSIX certifikátem pro podepisování kódu od certifikační autority, aby uživatelé nemuseli instalovat certifikát podepsaný svým držitelem.
Služba Důvěryhodné podepisování Azure představuje skvělý způsob, jak bezpečně spravovat certifikáty a integrovat přihlašování do kanálu CI/CD.
Microsoft Store za vás podepíše MSIX, před odesláním se nemusíte podepisovat.
Možná budete muset vytvořit několik balíčků MSIX, jeden pro každou architekturu, kterou podporujete (x64, Arm64). Nakonfigurujte CMake s příslušnými parametry generátoru a architektury.

Další kroky

Distribuujte pomocí winget: Odešlete svůj MSIX do repizitáře Windows Správce balíčků Community
Publish do Microsoft Store: Odešlete balíček pomocí winapp store
Nastavte CI/CD: Použijte akci setup-WinAppCli GitHub ke zautomatizování balení v pipeline
prozkoumat rozhraní Windows API: S identitou balíčku teď můžete používat oznámení, AI na zařízení a další rozhraní API závislé na identitě

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-05-12

Použití rozhraní příkazového řádku winapp s C++ a CMake

Předpoklady

1. Vytvoření nové aplikace C++

2. Aktualizace kódu pro kontrolu identity

Spusťte (program) bez přiřazené identity.

4. Inicializace Project pomocí rozhraní příkazového řádku winapp

Přidání spuštěcího aliasu (pro konzolové aplikace)

5. Ladění pomocí identity

Alternativa: Neúplná identita balíčku

6. Použití Windows App SDK (volitelné)

Aktualizace CMakeLists.txt

Aktualizace main.cpp

Sestavení a spuštění

7. V případě potřeby obnovte hlavičky.

Ruční nastavení

Automatizované nastavení pomocí CMake

8. Balíček s MSIX

Příprava adresáře balíčků

Vygenerování vývojového certifikátu

Podepsání a balení

Instalace certifikátu

Instalace a spuštění

Tips

Další kroky

Váš názor

Další materiály