Usar a linha de comando winapp com C++ e CMake

Este guia demonstra como usar a winapp CLI com uma aplicação C++ para depuração usando a identidade do pacote e embalar a sua aplicação em MSIX.

A identidade de pacote é um conceito central no modelo de Windows app. Permite que a sua aplicação aceda a APIs específicas do Windows (como Notificações, Segurança, APIs de IA, etc.), tenha uma experiência limpa de instalação/desinstalação e muito mais.

Um executável padrão (como um criado com cmake --build) não tem identidade de pacote. Este guia mostra como adicioná-lo para depuração e depois empacotar para distribuição.

Pré-requisitos

1. Ferramentas de Build: Use uma cadeia de ferramentas de compiladores suportada pelo CMake. Este exemplo utiliza o Visual Studio. Pode instalar a edição comunitária com (ou atualizar se já estiver instalada):

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

   Reinicia após a instalação.

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

   winget install Kitware.CMake --source winget
   

3. winapp CLI: Instale a winapp CLI via winget (ou atualize se já estiver instalada):

   winget install Microsoft.winappcli --source winget
   

1. Criar uma nova aplicação em C++

Comece por criar uma aplicação simples em C++. Crie um novo diretório para o seu projecto:

mkdir cpp-app
cd cpp-app

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

#include <iostream>

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

Crie um CMakeLists.txt ficheiro para configurar a 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)

Constrói e executa para garantir que tudo está a funcionar:

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

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

2. Atualizar o código para verificar a identidade

Vamos atualizar a aplicação para verificar se está a correr com identidade de pacote. Isto vai ajudar-nos a verificar se a identidade está a funcionar corretamente nos passos seguintes. Vamos usar a API C++ do Windows Runtime para aceder às APIs dos Pacotes.

Primeiro, adicione a seguinte linha no final do seu CMakeLists.txt para ligar à biblioteca Aplicação do Windows Model:

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

De seguida, substitua todo o conteúdo de main.cpp pelo seguinte código. Este código tenta recuperar a identidade atual do pacote usando a API do Windows Runtime. Se tiver sucesso, imprime o Nome da Família do Pacote; caso contrário, imprime "Não embalado".

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

Agora, reconstrua e execute a aplicação normalmente:

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

Deves ver a saída "Não empacotada". Isto confirma que o executável padrão está a correr sem qualquer identidade de pacote.

4. Inicializar o Project com o winapp CLI

O comando winapp init configura tudo o que precisas de uma só vez: manifesto da app, assets e, opcionalmente, cabeçalhos SDK de Aplicações Windows para desenvolvimento em C++.

Execute o seguinte comando e siga as indicações:

winapp init .

Quando solicitado:

• Nome do pacote: Pressione Enter para aceitar o padrão (cpp-app)
• Nome do Publicador: Pressione Enter para aceitar o padrão ou inserir o 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 "Stable SDKs" para descarregar SDK de Aplicações Windows e gerar cabeçalhos C++

Este comando irá fazer:

• Criar Package.appxmanifest — o manifesto que define a identidade da sua aplicação
• Criar Assets pasta — ícones necessários para o empacotamento MSIX e envio para a loja
• Crie uma pasta .winapp com cabeçalhos e bibliotecas SDK de Aplicações Windows
• Criar um winapp.yaml ficheiro de configuração para fixar versões do SDK

Pode abrir Package.appxmanifest para personalizar ainda mais propriedades como o nome de visualização, publicador e capacidades.

Adicionar Alias de Execução (para aplicações de consola)

Um alias de execução permite aos utilizadores executar a sua aplicação pelo nome a partir de qualquer terminal (como cpp-app). Também ativa winapp run --with-alias durante o desenvolvimento, o que mantém a saída da consola no terminal atual em vez de abrir uma nova janela.

Pode adicionar um automaticamente:

winapp manifest add-alias

Ou manualmente: abra Package.appxmanifest e adicione o namespace uap5 à tag <Package> se estiver em falta, e depois 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. Depuração com Identidade

Para testar funcionalidades que exigem identidade (como Notificações) sem embalar totalmente a aplicação, pode usar winapp run. Isto regista um pacote de layout solto (tal como numa instalação real de MSIX) e inicia a aplicação num só passo. Não é necessário nenhum certificado ou assinatura para a depuração.

1. Constrói o executável:

   cmake --build build --config Debug
   

2. Executar com identidade:

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

A --with-alias flag lança a aplicação através do seu alias de execução para que a saída da consola permaneça no terminal atual. Isto requer o uap5:ExecutionAlias que adicionámos no passo 4.

Agora deverá ver uma saída semelhante a:

Package Family Name: cpp-app_12345abcde

Isto confirma que a sua aplicação está a correr com uma identidade de pacote válida!

Alternativa: Identidade de pacote disperso

Se precisar especificamente de comportamento de pacotes esparsos (identidade sem copiar ficheiros), pode usar create-debug-identity em vez disso:

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

6. Utilização do SDK de Aplicações Windows (Opcional)

Se selecionou instalar os SDKs durante winapp init, agora tem acesso aos cabeçalhos do SDK de Aplicações Windows na pasta .winapp/include. Isto dá-lhe acesso a APIs modernas do Windows como notificações, janelas, IA no dispositivo e muito mais. Se só precisares de identidade de pacote para distribuição, podes saltar para o passo 7.

Vamos acrescentar um exemplo simples que imprime a versão Aplicação do Windows Runtime.

Atualizar CMakeLists.txt

Adicione a seguinte linha no final do seu CMakeLists.txt para incluir os cabeçalhos SDK de Aplicações Windows:

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

Atualize main.cpp

Substitua todo o conteúdo de main.cpp para utilizar a API de Runtime do Aplicação do Windows:

#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

Reconstrua a aplicação com os cabeçalhos do SDK de Aplicações Windows:

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

Agora deverá ver resultados como:

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 de Aplicações Windows, incluindo:

• winrt/ - Cabeçalhos de projeção C++ do WinRT para acesso às APIs do Windows Runtime
• Microsoft.UI.*.h - Cabeçalhos WinUI 3 para componentes modernos de UI
• MddBootstrap.h - Inicialização do SDK do Windows App
• WindowsAppSDK-VersionInfo.h - Informação de versão
• E muitos mais componentes do SDK de Aplicações Windows

Para uso mais avançado de SDK de Aplicações Windows, consulte a documentação SDK de Aplicações Windows.

7. Restaurar cabeçalhos quando necessário

A pasta .winapp é automaticamente adicionada a .gitignore por winapp init, por isso não será comprometida no sistema de controlo de versão. Quando outros clonarem o teu projeto, terão de restaurar esses ficheiros antes de compilar.

Configuração Manual

Executa estes dois comandos depois de clonares 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

Depois podes construir e correr normalmente com cmake -B build e cmake --build build --config Debug.

Configuração Automatizada com CMake

Alternativamente, pode automatizar isto ao adicionar lógica de configuração ao CMakeLists.txt. Aqui está o CMakeLists.txt completo com automação, ligação correta e uso mínimo do padrão 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 é automaticamente descarregado se não for encontrado no PATH
• Os cabeçalhos e o certificado do SDK de Aplicações Windows são automaticamente restaurados
• Os comandos só são executados uma vez durante a configuração (não em todas as builds) porque verificam se os ficheiros já existem
• Se os comandos falharem, o CMake mostra um aviso com instruções para os executar manualmente
• A aplicação winapp descarregada é armazenada em .winapp-tools/ (adicione isto a .gitignore se necessário)

8. Pacote com MSIX

Quando estiver pronto para distribuir a sua aplicação, pode empacotá-la como MSIX usando o mesmo manifesto. O MSIX proporciona instalação/desinstalação limpa, atualizações automáticas e uma experiência de instalação confiável.

Preparar o Diretório de Pacotes

Primeiro, construa a sua aplicação em modo de lançamento para um desempenho ótimo:

cmake --build build --config Release

Depois, crie um diretório apenas com os ficheiros necessários para a distribuição e copie o executável de release:

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

Gerar um Certificado de Desenvolvimento

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

winapp cert generate --if-exists skip

Assinar e Embalar

Agora pode embalar e assinar:

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

Instalar o Certificado

Antes de poderes instalar o pacote MSIX, precisas de confiar no certificado de desenvolvimento da tua máquina. Executa este comando como administrador (só precisas de o fazer uma vez por certificado):

winapp cert install .\devcert.pfx

Instalar e Executar

O winapp pack comando gera o ficheiro MSIX na diretoria raiz do projeto. Instale o pacote fazendo duplo clique no ficheiro gerado .msix , ou usando o PowerShell:

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

Agora pode executar a sua aplicação a partir de qualquer ponto do terminal escrevendo:

cpp-app

Deves ver o resultado "Nome da Família do Pacote", confirmando que está instalado e a funcionar com a identidade.

Tips

1. Quando estiver pronto para a distribuição, pode assinar o seu MSIX com um certificado de assinatura de código de uma Autoridade Certificadora, para que os seus utilizadores não tenham de instalar um certificado auto-assinado.
2. O serviço Assinatura Confiável do Azure é uma excelente forma de gerir os seus certificados de forma segura e integrar a assinatura no seu pipeline CI/CD.
3. A Microsoft Store assina o MSIX por si, não precisa de assinar antes de submeter.
4. Pode ser necessário criar vários pacotes MSIX, um para cada arquitetura que suporta (x64, Arm64). Configure CMake com o gerador e os sinalizadores de arquitetura apropriados.

Próximas Etapas

• Distribua via winget: Submeta o seu MSIX ao Repositório Comunitário Windows Gestor de Pacotes
• Publicar no Microsoft Store: Use winapp store para submeter o seu pacote
• Configurar CI/CD: Use o GitHub Action para automatizar o empacotamento no seu pipeline
• Explore Windows APIs: Com a identidade do pacote, pode agora usar Notifications, on-device AI e outras APIs dependentes da identidade