Usando a CLI do winapp com C++ e CMake

Este guia demonstra como usar a winapp CLI com um aplicativo C++ para depurar usando a identidade do pacote e empacotar o seu aplicativo como um MSIX.

A identidade do pacote é um conceito básico no modelo de Windows app. Ele permite que seu aplicativo acesse APIs de Windows específicas (como Notificações, Segurança, APIs de IA etc.), ter uma experiência de instalação/desinstalação limpa e muito mais.

Um executável padrão (como um criado com cmake --build) não tem a identidade do pacote. Este guia mostra como adicionar para depuração e, em seguida, empacotar para distribuição.

Pré-requisitos

  1. Ferramentas de Build: use um conjunto de ferramentas do compilador com suporte do CMake. Este exemplo usa Visual Studio. Você pode instalar a edição da comunidade com (ou atualizar se já estiver instalado):

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

    Reinicialize após a instalação.

  2. CMake: instalar o CMake (ou atualizar se já estiver instalado):

    winget install Kitware.CMake --source winget

  3. CLI do winapp: instale a winapp CLI por meio do winget (ou atualize se já estiver instalada):

    winget install Microsoft.winappcli --source winget

1. Criar um novo aplicativo C++

Comece criando um aplicativo C++ simples. Crie um novo diretório para seu project:

mkdir cpp-app
cd cpp-app

Crie um main.cpp arquivo com um programa básico "Olá, mundo!":

#include <iostream>

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

Crie um CMakeLists.txt arquivo para configurar o build:

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)

Crie e execute-o para garantir que tudo esteja funcionando:

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

A saída deve ser "Olá, mundo!"

2. Atualizar código para verificar identidade

Atualizaremos o aplicativo para verificar se ele está em execução com a identidade do pacote. Isso nos ajudará a verificar se a identidade está funcionando corretamente em etapas posteriores. Usaremos a API Windows Runtime C++ para acessar as APIs do Pacote.

Primeiro, adicione a seguinte linha ao final do CMakeLists.txt para vincular-se à biblioteca aplicativo do Windows Model:

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

Em seguida, substitua todo o conteúdo main.cpp pelo código a seguir. Esse código tenta recuperar a identidade do pacote atual usando a API Windows Runtime. Se for bem-sucedido, ele imprimirá o Nome da Família de Pacotes; senão, imprimirá "Não empacotado".

#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. Executar sem identidade

Agora, recompile e execute o aplicativo como de costume:

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

Você deve ver a saída "Não empacotado". Isso confirma que o executável padrão está em execução sem nenhuma identidade de pacote.

4. Inicializar Project com a CLI do winapp

O comando winapp init configura tudo o que você precisa de uma só vez: manifesto do aplicativo, ativos e, opcionalmente, SDK do Aplicativo Windows cabeçalhos para o desenvolvimento do C++.

Execute o seguinte comando e siga os prompts:

winapp init .

Quando solicitado:

  • Nome do pacote: Pressione Enter para aceitar o padrão (cpp-app)
  • Nome do publicador: pressione Enter para aceitar o valor padrão ou insira seu nome
  • Versão: Pressione Enter para aceitar 1.0.0.0
  • Ponto de entrada: pressione Enter para aceitar o padrão (cpp-app.exe)
  • Setup SDKs: selecione "SDKs estáveis" para baixar SDK do Aplicativo Windows e gerar cabeçalhos C++

Este comando será:

  • Criar Package.appxmanifest — o manifesto que define a identidade do aplicativo
  • Criar Assets pasta — ícones necessários para empacotamento MSIX e envio para a Loja
  • Criar uma pasta .winapp com SDK do Aplicativo Windows cabeçalhos e bibliotecas
  • Criar um winapp.yaml arquivo de configuração para fixar versões do SDK

Você pode abrir Package.appxmanifest para personalizar ainda mais as propriedades, como o nome de exibição, o editor e os recursos.

Adicionar alias de execução (para aplicativos de console)

Um alias de execução permite que os usuários executem seu aplicativo pelo nome de qualquer terminal (como cpp-app). Ele também habilita winapp run --with-alias durante o desenvolvimento, o que mantém a saída do console no terminal atual em vez de abrir uma nova janela.

Você pode adicionar um automaticamente:

winapp manifest add-alias

Ou manualmente: abra Package.appxmanifest e adicione o uap5 namespace à tag <Package> se ele estiver ausente e adicione a extensão dentro de <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. Depurar com Identidade

Para testar recursos que exigem identidade (como Notificações) sem empacotar totalmente o aplicativo, você pode usar winapp run. Isso registra um pacote de layout solto (como uma instalação real de MSIX) e inicia o aplicativo em uma etapa. Nenhum certificado ou assinatura é necessário para depuração.

  1. Crie o executável:

    cmake --build build --config Debug

  2. Executar com identidade:

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

O --with-alias flag inicia o aplicativo através de seu alias de execução, com que a saída do console permaneça no terminal atual. Isso requer o uap5:ExecutionAlias que adicionamos na etapa 4.

Dica

winapp run também registra o pacote em seu sistema. É por isso que o MSIX pode aparecer como "já instalado" quando você tentar instalá-lo posteriormente na etapa 8. Use winapp unregister para limpar pacotes de desenvolvimento quando terminar.

Agora você deve ver uma saída semelhante a:

Package Family Name: cpp-app_12345abcde

Isso confirma que seu aplicativo está em execução com uma identidade de pacote válida!

Alternativa: identidade de pacote esparso

Se você precisar de um comportamento de pacote esparso especificamente (identidade sem copiar arquivos), poderá usar create-debug-identity em vez disso:

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

Dica

Para obter fluxos de trabalho avançados de depuração (anexando depuradores, configuração de IDE, depuração de inicialização), consulte o Guia de Depuração.

6. Usando SDK do Aplicativo Windows (opcional)

Se você tiver selecionado configurar os SDKs durante winapp init, agora terá acesso a cabeçalhos SDK do Aplicativo Windows na pasta .winapp/include. Isso fornece acesso a APIs de Windows modernas, como notificações, janelas, IA no dispositivo e muito mais. Se você precisar apenas da identidade do pacote para distribuição, poderá pular para a etapa 7.

Vamos adicionar um exemplo simples que imprime a versão aplicativo do Windows Runtime.

Atualizar CMakeLists.txt

Adicione a seguinte linha ao final do CMakeLists.txt para incluir os cabeçalhos SDK do Aplicativo Windows:

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

Atualizar main.cpp

Substitua todo o conteúdo de main.cpp para usar a API do aplicativo do 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;
}

Compilar e executar

Recompile o aplicativo com os cabeçalhos SDK do Aplicativo Windows:

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

Agora, você deve ver uma saída semelhante a:

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

O diretório .winapp/include contém todos os cabeçalhos necessários para SDK do Aplicativo Windows, incluindo:

  • winrt/ – Cabeçalhos de projeção do WinRT C++ para acessar APIs de Windows Runtime
  • Microsoft.UI.*.h - Cabeçalhos do WinUI 3 para componentes modernos de UI
  • MddBootstrap.h – inicialização SDK do Aplicativo Windows
  • WindowsAppSDK-VersionInfo.h - Informações de versão
  • E muitos outros componentes do SDK do Aplicativo Windows

Para obter um uso mais avançado de SDK do Aplicativo Windows, confira a documentação SDK do Aplicativo Windows.

7. Restaurar cabeçalhos quando necessário

A pasta .winapp é adicionada automaticamente ao .gitignore por winapp init, portanto, não será incluída no controle de versão. Quando outros clonarem seu projeto, precisarão restaurar esses arquivos antes de construir o projeto.

Instalação manual

Execute estes dois comandos depois de clonar o repositório:

# 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

Em seguida, você pode compilar e executar normalmente com cmake -B build e cmake --build build --config Debug.

Instalação automatizada com o CMake

Como alternativa, você pode automatizar isso adicionando lógica de configuração ao seu CMakeLists.txt. Aqui está a íntegra CMakeLists.txt com automação, vinculação adequada e padrão mínimo do 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)

Com esta configuração:

  • Quando alguém clona o repositório e executa cmake -B build, o winapp será baixado automaticamente se não for encontrado no PATH.
  • Os cabeçalhos SDK do Aplicativo Windows e o certificado são restaurados automaticamente
  • Os comandos só são executados uma vez durante a configuração (não em cada build) porque verificam se os arquivos já existem
  • Se os comandos falharem, o CMake mostrará um aviso com instruções para executá-los manualmente
  • O aplicativo baixado é armazenado em .winapp-tools/ (adicione isto a .gitignore se necessário)

8. Pacote com MSIX

Quando estiver pronto para distribuir seu aplicativo, você poderá empacotá-lo como um MSIX usando o mesmo manifesto. O MSIX fornece instalação/desinstalação limpa, atualizações automáticas e uma experiência de instalação confiável.

Preparar o diretório do pacote

Primeiro, crie seu aplicativo no modo de versão para um desempenho ideal:

cmake --build build --config Release

Em seguida, crie um diretório apenas com os arquivos necessários para distribuição e copie o executável de versão:

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

Gerar um certificado de desenvolvimento

Os pacotes MSIX devem ser assinados. Para testes locais, gere um certificado de desenvolvimento autoassinado:

winapp cert generate --if-exists skip

Dica

O emissor do certificado deve corresponder ao Publisher em seu Package.appxmanifest. O cert generate comando lê isso automaticamente do manifesto.

Assinar e empacotar

Agora você pode empacotar e assinar:

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

Dica

O pack comando usa automaticamente o Package.appxmanifest do diretório atual e copia-o para a pasta de destino antes do empacotamento. O arquivo gerado .msix estará no diretório atual.

Instalar o certificado

Antes de instalar o pacote MSIX, você precisa confiar no certificado de desenvolvimento em seu computador. Execute este comando como administrador (você só precisa fazer isso uma vez por certificado):

winapp cert install .\devcert.pfx

Instalar e executar

Dica

Se você usou winapp run na etapa 5, o pacote pode já estar registrado em seu sistema. Use winapp unregister primeiro para remover o registro de desenvolvimento e, em seguida, instale o pacote de lançamento.

O winapp pack comando gera o arquivo MSIX no diretório raiz do projeto. Instale o pacote clicando duas vezes no arquivo gerado .msix ou usando o PowerShell:

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

Dica

O nome do arquivo MSIX inclui a versão e a arquitetura (por exemplo, cpp-app_1.0.0.0_arm64.msix). Verifique o diretório para obter o nome de arquivo exato.

Agora você pode executar seu aplicativo de qualquer lugar no terminal digitando:

cpp-app

Você deverá visualizar a saída "Nome da Família de Pacotes", o que confirmará que o pacote está instalado e em execução com sua identidade.

Dica

Se você precisar reempacotar seu aplicativo (por exemplo, após alterações de código), incremente-o Version antes Package.appxmanifest de executar winapp pack novamente. Windows requer um número de versão mais alto para atualizar um pacote instalado.

Dicas

  1. Quando estiver pronto para distribuição, você poderá assinar seu MSIX com um certificado de assinatura de código de uma Autoridade de Certificação para que os usuários não precisem instalar um certificado autoassinado.
  2. O serviço Assinatura Confiável do Azure é uma ótima maneira de gerenciar seus certificados com segurança e integrar a assinatura no pipeline de CI/CD.
  3. O Microsoft Store assinará o MSIX para você, não é necessário assinar antes do envio.
  4. Talvez seja necessário criar vários pacotes MSIX, um para cada arquitetura compatível (x64, Arm64). Configure o CMake com o gerador e os sinalizadores de arquitetura apropriados.

Próximas etapas

  • Last updated on