C++ ve CMake ile winapp CLI kullanma

Bu kılavuzda CLI'yi winapp 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, AI API'leri vb.) erişmesine, temiz bir yükleme/kaldırma deneyimine ve daha fazlasına erişmesine olanak tanır.

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

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ü ile yükleyebilirsiniz (veya zaten yüklüyse güncelleştirebilirsiniz):
```
winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"
```
Yüklemeden sonra yeniden başlatın.
CMake: CMake'i yükleyin (veya zaten yüklüyse güncelleştirin):
```
winget install Kitware.CMake --source winget
```
winapp CLI: Cli'yi winapp winget aracılığıyla yükleyin (veya zaten yüklüyse güncelleştirin):
```
winget install Microsoft.winappcli --source winget
```

1. Yeni 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

Çıktı "Hello, world!" olmalıdır

2. Kimliği Denetlemek için Kodu Güncelleştirme

Uygulamanın paket kimliğiyle çalışıp çalışmadığını denetlemek için uygulamayı güncelleştireceğiz. Bu, sonraki adımlarda kimliğin düzgün çalıştığını doğrulamamıza yardımcı olur. Paket API'lerine erişmek için Windows Çalışma Zamanı C++ API'sini kullanacağız.

İlk olarak, Windows Uygulaması Model kitaplığına bağlanmak için CMakeLists.txt sonuna aşağıdaki satırı ekleyin:

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

Ardından içeriğinin tamamını main.cpp aşağıdaki kodla değiştirin. Bu kod, Windows Çalışma Zamanı API'sini kullanarak geçerli paket kimliğini almayı dener. Başarılı olursa Paket Aile Adı'nı yazdırır; aksi takdirde, "Paketlenmedi" yazdırır.

#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. Kimlik Olmadan Çalıştır

Şimdi uygulamayı her zamanki gibi yeniden derleyin ve çalıştırın:

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

"Çıkışta '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 tek seferde ihtiyacınız olan her şeyi ayarlar: uygulama manifesti, varlıklar ve isteğe bağlı olarak C++ geliştirme için Windows Uygulama SDK'sı üst bilgileri.

Aşağıdaki komutu çalıştırın ve istemleri izleyin:

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)
SDK Kurulumu: Windows Uygulama SDK'sı'sini indirmek ve C++ başlık dosyalarını oluşturmak için "Sürüm SDK'lar" seçeneğini belirleyin

Bu komut:

Oluşturma Package.appxmanifest — uygulamanızın kimliğini tanımlayan bildirim
Klasör oluşturma Assets — MSIX paketleme ve Mağaza gönderimi için gereken simgeler
Windows Uygulama SDK'sı başlık dosyaları ve kitaplıklarını içeren bir .winapp klasörü oluşturun.
SDK sürümlerini sabitlemek için yapılandırma winapp.yaml dosyası oluşturma

Görüntü adı, yayımcı ve özellikler gibi unsurları daha fazla özelleştirmek için Package.appxmanifest açabilirsiniz.

Yürütme Takma Adı Ekle (konsol uygulamaları için)

Çalıştırma takma adı, kullanıcıların uygulamanızı herhangi bir terminalden (örneğin cpp-app) isme göre çalıştırmasına olanak tanır. winapp geliştirme sırasında da kullanır, bu nedenle winapp run konsol çıkışını yeni bir pencere açmak yerine geçerli terminalde tutar.

Otomatik olarak bir tane ekleyebilirsiniz:

winapp manifest add-alias

Yahut manuel olarak: Package.appxmanifest öğesini açın ve uap5 namespace'i <Package> etiketi eksikse ekleyin, ardından uzantıyı <Applications><Application><Extensions>... içine ekleyin.

<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. Kimlikle Hata Ayıklama

Uygulamayı tamamen paketlemeden kimlik gerektiren özellikleri (Bildirimler gibi) test etmek için kullanabilirsiniz winapp run. Bu, gevşek bir düzen paketini (gerçek bir MSIX yüklemesi gibi) kaydeder ve uygulamayı bir adımda başlatır. Hata ayıklama için sertifika veya imzalama gerekmez.

Yürütülebilir dosyayı oluşturun:
```
cmake --build build --config Debug
```
Kimlikle çalıştır:
```
winapp run .\build\Debug
```

Bir konsol uygulaması, çalıştırma takma adı aracılığıyla otomatik olarak başlatılır; bu nedenle çıktısı geçerli terminalde kalır — winapp bunu oluşturulan ikili dosyadan algılar ve 4. adımda eklediğimiz uap5:ExecutionAlias öğesini kullanır. --without-alias parametresini bunun yerine AUMID etkinleştirmesini zorlamak için iletin; bu durumda uygulama burada hiçbir şey yazdırmaz.

Tavsiye

winapp run ayrıca paketi sisteminize kaydeder. Bu nedenle, 8. adımda yüklemeyi denediğinizde MSIX "zaten yüklü" olarak görünebilir. İşiniz bittiğinde geliştirme paketlerini temizlemek için kullanın winapp unregister .

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

Package Family Name: cpp-app_12345abcde

Bu, uygulamanızın geçerli bir paket kimliğiyle çalıştığını onaylar!

Alternatif: Minimal paket kimliği

Seyrek paket davranışına özellikle ihtiyacınız varsa (dosyaları kopyalamadan kimlik), bunun yerine şunları kullanabilirsiniz create-debug-identity :

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

Tavsiye

Gelişmiş hata ayıklama iş akışları (hata ayıklayıcıları ekleme, IDE kurulumu, başlatma hata ayıklama) için Hata Ayıklama Kılavuzu'na bakın.

6. Windows Uygulama SDK'sı Kullanma (İsteğe Bağlı)

winapp init sırasında SDK'ları ayarlamayı seçtiyseniz, artık .winapp/include klasöründeki Windows Uygulama SDK'sı üst bilgilerine erişebilirsiniz. Bu, bildirimler, pencereleme, cihaz içi yapay zeka ve daha fazlası gibi modern Windows API'lerine erişmenizi sağlar. Yalnızca dağıtım için paket kimliğine ihtiyacınız varsa 7. adıma atlayabilirsiniz.

Windows Uygulaması Runtime sürümünü yazdıran basit bir örnek ekleyelim.

Güncelleştirme CMakeLists.txt

Windows Uygulama SDK'sı üst bilgilerini eklemek için aşağıdaki satırı CMakeLists.txt sonuna ekleyin:

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

main.cpp dosyasını güncelle

Windows Uygulaması Çalışma Zamanı API'sini kullanmak için main.cpp içeriğinin tamamını değiştirin:

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

Derleme ve Çalıştırma

uygulamayı Windows Uygulama SDK'sı üst bilgileriyle yeniden derleyin:

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

Şimdi aşağıdaki gibi bir çıkış görmeniz gerekir:

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

.winapp/include dizini, Windows Uygulama SDK'sı için gerekli tüm üst bilgileri içerir, örneğin:

winrt/ - Windows Çalışma Zamanı API'lerine erişmek için WinRT C++ projeksiyon başlık dosyaları
Microsoft.UI.*.h - Modern kullanıcı arabirimi bileşenleri için WinUI 3 üst bilgileri
MddBootstrap.h - Windows Uygulama SDK'sı başlatma
WindowsAppSDK-VersionInfo.h - Sürüm bilgileri
Ve daha birçok Windows Uygulama SDK'sı bileşeni

Daha gelişmiş Windows Uygulama SDK'sı kullanımı için Windows Uygulama SDK'sı belgelerine göz atın.

7. Gerektiğinde üst bilgileri geri yükleyin

.winapp klasörü, .gitignore tarafından winapp init öğesine otomatik olarak eklenir, bu nedenle kaynak denetimine eklenmez. Başkaları projenizi kopyaladığında, oluşturmadan önce bu dosyaları geri yüklemeleri gerekir.

El ile Kurulum

Depoyu kopyaladıktan sonra şu iki komutu çalıştırın:

# 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

Ardından cmake -B build ve cmake --build build --config Debug ile normal bir şekilde derleyebilir ve çalıştırabilirsiniz.

CMake ile Otomatik Kurulum

Kurulum mantığını CMakeLists.txt ortamınıza ekleyerek bunu otomatikleştirebilirsiniz. İşte otomasyon, uygun bağlantı ve en aza indirilmiş C++20 standardıyla tam CMakeLists.txt.

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)

Bu kurulumla:

Birisi depoyu kopyalayıp çalıştırdığında cmake -B build, PATH'de bulunamazsa winapp otomatik olarak indirilir
Windows Uygulama SDK'sı üst bilgileri ve sertifikası otomatik olarak geri yüklenir
Komutlar yapılandırma sırasında yalnızca bir kez çalışır (her derlemede çalışmaz), çünkü dosyaların zaten var olup olmadığını denetlerler
Komutlar başarısız olursa, CMake bunları el ile çalıştırma yönergelerini içeren bir uyarı gösterir
İndirilen winapp .winapp-tools/ içinde depolanır (gerekirse bunu .gitignore öğesine ekleyin)

8. MSIX ile paketle

Uygulamanızı dağıtmaya hazır olduğunuzda, aynı bildirimi kullanarak bir MSIX olarak paketleyebilirsiniz. MSIX temiz yükleme/kaldırma, otomatik güncelleştirmeler ve güvenilir bir yükleme deneyimi sağlar.

Paket Dizinini Hazırlama

İlk olarak, en iyi performans için uygulamanızı yayın modunda derleyin:

cmake --build build --config Release

Ardından, yalnızca dağıtım için gereken dosyaları içeren bir dizin oluşturun ve yayın yürütülebilir dosyanızı kopyalayın:

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

Geliştirme Sertifikası Oluşturma

MSIX paketleri imzalanmalıdır. Yerel test için otomatik olarak imzalanan bir geliştirme sertifikası oluşturun:

winapp cert generate --if-exists skip

Tavsiye

Sertifikanın yayımcısı Publisher içindeki Package.appxmanifest ile eşleşmelidir. Komut bunu cert generate bildiriminizden otomatik olarak okur.

İmzala ve Paketle

Artık paketleyip imzalayabilirsiniz:

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

Tavsiye

Komut, pack geçerli dizininizdeki Package.appxmanifest dosyasını otomatik olarak kullanır ve paketlemeden önce hedef klasöre kopyalar. Oluşturulan .msix dosya geçerli dizinde olacaktır.

Sertifikayı Yükleme

MSIX paketini yükleyebilmeniz için önce makinenizdeki geliştirme sertifikasına güvenmeniz gerekir. Bu komutu yönetici olarak çalıştırın (bunu sertifika başına yalnızca bir kez yapmanız gerekir):

winapp cert install .\devcert.pfx

Yükleme ve Çalıştırma

Tavsiye

5. adımda kullandıysanız winapp run paket sisteminizde zaten kayıtlı olabilir. Önce geliştirme kaydını kaldırmak için kullanın winapp unregister , ardından yayın paketini yükleyin.

winapp pack komutu, proje kök dizininizde MSIX dosyasını oluşturur. Oluşturulan .msix dosyaya çift tıklayarak veya PowerShell kullanarak paketi yükleyin:

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

Tavsiye

MSIX dosya adı sürümü ve mimariyi içerir (örn. cpp-app_1.0.0.0_arm64.msix). Tam dosya adı için dizininizi denetleyin.

Artık şunu yazarak uygulamanızı terminalde herhangi bir yerden çalıştırabilirsiniz:

cpp-app

Yüklendiğini ve kimlikle çalıştığını onaylayan "Paket Aile Adı" çıkışını görmeniz gerekir.

Tavsiye

Uygulamanızı yeniden paketlemeniz gerekiyorsa (örneğin, kod değişikliklerinden sonra), Version’yi yeniden çalıştırmadan önce Package.appxmanifest içindeki winapp pack değerini artırın. Windows yüklü bir paketi güncelleştirmek için daha yüksek bir sürüm numarası gerekir.

Tips

Dağıtıma hazır olduğunuzda, kullanıcılarınızın otomatik olarak imzalanan bir sertifika yüklemesini gerektirmeyecek şekilde MSIX'inizi Sertifika Yetkilisi'nden bir kod imzalama sertifikasıyla imzalayabilirsiniz.
Azure Güvenilen İmzalama hizmeti, sertifikalarınızı güvenli bir şekilde yönetmenin ve CI/CD işlem hattınızda oturum açmayı tümleştirmenin harika bir yoludur.
Microsoft Store MSIX'i sizin için imzalar, göndermeden önce imzalamanız gerekmez.
Desteklediğiniz her mimari için (x64, Arm64) bir tane olmak üzere birden çok MSIX paketi oluşturmanız gerekebilir. CMake'yi uygun oluşturucu ve mimari bayraklarıyla yapılandırın.

Sonraki Adımlar

winget aracılığıyla dağıtın: MSIX'inizi Windows Paket Yöneticisi Topluluk Deposu'na gönderin
Microsoft Store: Paketinizi göndermek için kullanın
CI/CD'yi ayarlayın: İşlem hattınızda paketlemeyi otomatikleştirmek için setup-WinAppCli GitHub Eylemi'ni kullanın
Explore Windows API'leri: Paket kimliğiyle, artık Notifications, on-device AI ve diğer identity bağımlı API'leri kullanabilirsiniz

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-09-24

C++ ve CMake ile winapp CLI kullanma

Önkoşullar

1. Yeni C++ Uygulaması Oluşturma

2. Kimliği Denetlemek için Kodu Güncelleştirme

3. Kimlik Olmadan Çalıştır

4. winapp CLI ile Project başlatma

Yürütme Takma Adı Ekle (konsol uygulamaları için)

5. Kimlikle Hata Ayıklama

Alternatif: Minimal paket kimliği

6. Windows Uygulama SDK'sı Kullanma (İsteğe Bağlı)

Güncelleştirme CMakeLists.txt

main.cpp dosyasını güncelle

Derleme ve Çalıştırma

7. Gerektiğinde üst bilgileri geri yükleyin

El ile Kurulum

CMake ile Otomatik Kurulum

8. MSIX ile paketle

Paket Dizinini Hazırlama

Geliştirme Sertifikası Oluşturma

İmzala ve Paketle

Sertifikayı Yükleme

Yükleme ve Çalıştırma

Tips

Sonraki Adımlar

Geri Bildirim

Ek kaynaklar