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

Tato příručka vysvětluje, jak použít winapp CLI s aplikací C++ k ladění pomocí identity balíčku a k zabalení aplikace ve formátu MSIX.

Identita balíčku je základním konceptem modelu Windows app. Umožňuje aplikaci přistupovat k konkrétním rozhraním API systému Windows (jako jsou oznámení, zabezpečení, rozhraní API AI atd.), má čistý proces instalace a odinstalace 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

  1. 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 pomocí:

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

    Po instalaci restartujte počítač.

  2. CMake: Instalace CMake:

    winget install Kitware.CMake --source winget

  3. winapp CLI: Nainstalujte rozhraní příkazového řádku prostřednictvím wingetu winapp :

    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

2. Aktualizace kódu pro kontrolu identity

Aktualizujte aplikaci, abyste zkontrolovali, jestli je spuštěná s identitou balíčku pomocí rozhraní API Windows Runtime C++.

Nejprve aktualizujte CMakeLists.txt pro propojení s knihovnou Windows App Model:

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)

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

Dále nahraďte obsah main.cpp:

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

int main() {
    UINT32 length = 0;
    LONG result = GetCurrentPackageFamilyName(&length, nullptr);

    if (result == ERROR_INSUFFICIENT_BUFFER) {
        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 {
        std::cout << "Not packaged" << std::endl;
    }

    return 0;
}

3. Spuštění bez identity

Znovu sestavte a spusťte aplikaci:

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

Měla by se zobrazit zpráva "Nenabalené". 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: manifest aplikace, prostředky a volitelně headery Windows App SDK pro vývoj v C++.

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, vyberte Stabilní sady SDK.

Tento příkaz vytvoří:

  • appxmanifest.xml a Assets složka pro identitu vaší aplikace
  • Složka .winapp se záhlavími a knihovnami Windows App SDK
  • winapp.yaml Konfigurační soubor pro připnutí verzí sady SDK

5. Ladění s identitou

K testování funkcí, které vyžadují identitu bez plného zabalení aplikace, použijte winapp create-debug-identity:

  1. Sestavení spustitelného souboru:

    cmake --build build --config Debug

  2. Použít identitu ladění:

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

  3. Spusťte spustitelný soubor:

    .\build\Debug\cpp-app.exe

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

Package Family Name: cpp-app_12345abcde

Automatizace identity ladění (volitelné)

Přidejte příkaz post-build do vašeho CMakeLists.txt, aby se automaticky použila identita ladění:

add_custom_command(TARGET cpp-app POST_BUILD
    COMMAND $<$<CONFIG:Debug>:winapp>
            $<$<CONFIG:Debug>:create-debug-identity>
            $<$<CONFIG:Debug>:$<TARGET_FILE:cpp-app>>
    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
    COMMAND_EXPAND_LISTS
    COMMENT "Applying debug identity to executable..."
)

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

Pokud jste během winapp init zvolili nastavení sad SDK, máte přístup k záhlavím Windows App SDK ve složce .winapp/include.

Aktualizujte CMakeLists.txt tak, aby zahrnovaly záhlaví:

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

Aktualizujte main.cpp tak, aby používalo rozhraní API Windows App Runtime:

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

int main() {
    winrt::init_apartment();

    UINT32 length = 0;
    LONG result = GetCurrentPackageFamilyName(&length, nullptr);

    if (result == ERROR_INSUFFICIENT_BUFFER) {
        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;

            auto runtimeVersion = winrt::Microsoft::Windows::ApplicationModel::WindowsAppRuntime::RuntimeInfo::AsString();
            std::wcout << L"Windows App Runtime Version: " << runtimeVersion.c_str() << std::endl;
        }
    } else {
        std::cout << "Not packaged" << std::endl;
    }

    return 0;
}

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

Složka .winapp se automaticky přidá do .gitignoresložky . Když vaši project naklonují jiní uživatelé, musí tyto soubory obnovit:

winapp restore
winapp cert generate --if-exists skip

8. Balíček s MSIX

Jakmile budete připraveni distribuovat, zabalte ho jako MSIX:

  1. Sestavení pro vydání:

    cmake --build build --config Release

  2. Příprava adresáře balíčku:

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

  3. Vygenerování vývojového certifikátu:

    winapp cert generate --if-exists skip

  4. Balíček a podepsání:

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

  5. Nainstalujte certifikát (spusťte ho jako správce):

    winapp cert install .\devcert.pfx

  6. Instalace a spuštění:

    Add-AppxPackage .\cpp-app.msix
cpp-app

Návod

  • Podepište MSIX podpisovým certifikátem od certifikační autority pro produkční distribuci.
  • Microsoft Store za vás podepíše MSIX, před odesláním se nemusíte podepisovat.
  • Pro každou architekturu, kterou podporujete (x64, Arm64), možná budete potřebovat samostatné balíčky MSIX.
  • Last updated on