C++ ve CMake ile winapp CLI kullanma

Bu kılavuzda winapp CLI'yi bir C++ uygulamasıyla kullanarak paket kimliğiyle hata ayıklama ve uygulamanızı MSIX olarak paketleme işlemleri gösterilmektedir.

Paket kimliği, Windows app modelinde temel bir kavramdır. Uygulamanızın belirli Windows API'lerine (Bildirimler, Güvenlik, Yapay Zeka API'leri vb.) erişmesini sağlar, sorunsuz yükleme ve kaldırma deneyimi sunar ve daha fazlasını gerçekleştirir.

Standart bir yürütülebilir dosya (örneğin cmake --build ile oluşturulan) paket kimliğine sahip değildir. Bu kılavuzda hata ayıklama için nasıl ekleneceği ve ardından dağıtım için nasıl paketleneceği gösterilmektedir.

Önkoşullar

1. Derleme Araçları: CMake tarafından desteklenen bir derleyici araç zinciri kullanın. Bu örnekte Visual Studio kullanılır. Topluluk sürümünü şu şekilde yükleyebilirsiniz:

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

   Yüklemeden sonra yeniden başlatın.

2. CMake: CMake'yi yükleyin:

   winget install Kitware.CMake --source winget
   

3. winapp CLI: CLI'yi winapp winget aracılığıyla yükleyin:

   winget install Microsoft.winappcli --source winget
   

1. Yeni bir C++ uygulaması oluşturma

Basit bir C++ uygulaması oluşturarak başlayın. project için yeni bir dizin oluşturun:

mkdir cpp-app
cd cpp-app

Temel bir main.cpp "Hello, world!" programıyla bir dosya oluşturun:

#include <iostream>

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

Derlemeyi yapılandırmak için bir CMakeLists.txt dosya oluşturun:

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)

Her şeyin düzgün çalıştığını doğrulamak için oluşturun ve çalıştırın.

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

2. Kimliği denetlemek için kodu güncelleştirme

Windows Runtime C++ API'sini kullanarak paket kimliğiyle çalışıp çalışmadığını denetlemek için uygulamayı güncelleştirin.

İlk olarak, CMakeLists.txt Windows App Model kitaplığına bağlanacak şekilde güncelleştirin:

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)

Ardından, main.cpp öğesinin içeriğini değiştirin:

#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. Kimlik olmadan çalıştırma

Uygulamayı yeniden derleyin ve çalıştırın:

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

"Paketlenmedi" ifadesini görmeniz gerekir. Bu, standart yürütülebilir dosyanın herhangi bir paket kimliği olmadan çalıştığını onaylar.

4. winapp CLI ile project başlatma

winapp init komutu, gereken her şeyi ayarlar: uygulama manifesti, varlıklar ve C++ geliştirme için opsiyonel Windows App SDK üst bilgileri.

winapp init

Sorulduğunda:

• Paket adı: Varsayılanı kabul etmek için Enter tuşuna basın (cpp-app)
• Publisher name: Varsayılanı kabul etmek için Enter tuşuna basın veya adınızı girin
• Sürüm: 1.0.0.0'ı kabul etmek için Enter'a basın
• Giriş noktası: Varsayılanı kabul etmek için Enter tuşuna basın (cpp-app.exe)
• Setup SDK'ları: Windows App SDK indirmek ve başlık dosyaları oluşturmak için "Kararlı SDK'lar" seçeneğini belirleyin

Bu komut şunu oluşturur:

• appxmanifest.xml ve Assets klasörleri uygulama kimliğiniz içindir
• Windows App SDK başlık dosyaları ve kitaplıkları olan bir .winapp klasörü
• winapp.yaml SDK sürümlerini sabitlemek için bir yapılandırma dosyası

5. Kimlikle hata ayıklama

Uygulamayı tamamen paketlemeden kimlik gerektiren özellikleri test etmek için kullanın winapp create-debug-identity:

1. Yürütülebilir dosyayı oluşturun:

   cmake --build build --config Debug
   

2. Hata ayıklama kimliğini uygula:

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

3. Yürütülebilir dosyayı çalıştırın:

   .\build\Debug\cpp-app.exe
   

Şimdi şuna benzer bir çıkış görmeniz gerekir:

Package Family Name: cpp-app_12345abcde

Hata ayıklama kimliğini otomatikleştirme (isteğe bağlı)

CMakeLists.txt uygulamanıza hata ayıklama kimliğini otomatik olarak uygulamak için bir derleme sonrası komutu ekleyin.

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. Windows App SDK kullanma (isteğe bağlı)

winapp init sırasında SDK'ları ayarlamayı seçtiyseniz, .winapp/include klasöründe Windows App SDK üst bilgilerine erişiminiz var.

CMakeLists.txt içerecek şekilde üst bilgileri güncelleyin.

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

main.cpp Windows App Çalışma Zamanı API'sini kullanacak şekilde güncelleştirin:

#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. Gerektiğinde üst bilgileri geri yükleyin

.winapp klasörü .gitignore öğesine otomatik olarak eklenir. Başkaları projenizi klonladığında, şu dosyaları geri yüklemeleri gerekir:

winapp restore
winapp cert generate --if-exists skip

8. MSIX ile paketle

Dağıtmaya hazır olduğunuzda MSIX olarak paketle:

1. Yayın için derleme:

   cmake --build build --config Release
   

2. Paket dizinini hazırlama:

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

3. Geliştirme sertifikası oluşturma:

   winapp cert generate --if-exists skip
   

4. Paketle ve imzala:

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

5. Sertifikayı yükleyin (yönetici olarak çalıştırın):

   winapp cert install .\devcert.pfx
   

6. Yükleme ve çalıştırma:

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

Tavsiye

• MSIX'inizi üretim dağıtımı için sertifika yetkilisinden bir kod imzalama sertifikasıyla imzalayın.
• Microsoft Store MSIX'i sizin için imzalar, göndermeden önce imzalamanız gerekmez.
• Desteklediğiniz her mimari (x64, Arm64) için ayrı MSIX paketlerine ihtiyacınız olabilir.

İlgili konular

• winapp CLI referans
• winapp CLI'ye genel bakış
• Windows App SDK belgeleri