Apresentação do primeiro programa WinUI em C++

Na aula anterior, concluímos a instalação do WinUI C++ e criamos nosso primeiro programa funcional. Nesta aula, vamos analisar a estrutura interna desse primeiro projeto WinUI em C++.

Abaixo, explicamos a função de cada arquivo e pasta.

Análise do diretório do projeto

Nome da solução

No topo, aparece “Solution ‘App3’”, esse é o nome da solução, neste caso App3. Ao criar um projeto, você pode definir um nome personalizado para a solução; por padrão, ele é igual ao nome do projeto.

Na captura, o primeiro campo de texto é o nome do projeto e o último é o nome da solução. Por padrão ambos são iguais, mas você pode atribuir nomes diferentes.

Uma solução pode agrupar vários projetos; aqui temos apenas um projeto empacotado para área de trabalho: App3 (Desktop).

1. References (Referências)

Esta pasta armazena referências aos SDKs dos quais o projeto depende, Windows App SDK, runtime WinRT e componentes instalados via NuGet:

Todas as dependências são gerenciadas aqui: Windows SDK, biblioteca de controles WinUI 3, arquivos de cabeçalho C++/WinRT, Microsoft.UI.Xaml e outros;
Não é necessário editar manualmente, o Visual Studio atualiza automaticamente ao gerenciar pacotes NuGet.

Lista de referências (trecho da captura)

2. External Dependencies (Dependências Externas)

Esta pasta escaneia automaticamente arquivos de cabeçalho do sistema, cabeçalhos de SDK e bibliotecas de terceiros:

Windows.h, cabeçalhos da pasta winrt/, cabeçalhos de baixo nível do Microsoft.UI.Xaml;
Apenas leitura: serve para visualizar códigos externos, não pode ser editada manualmente. Geralmente contém bibliotecas instaladas junto com o Visual Studio.

Arquivos de dependências externas (trecho)

Clique duas vezes em qualquer arquivo para abrir, você verá que seu caminho está dentro do diretório de instalação do Visual Studio. Passe o mouse sobre o nome do arquivo no topo para exibir o caminho completo.

3. Pasta Assets (Recursos: ícones e tela de inicialização)

Contém todas as imagens usadas na Microsoft Store, janelas do sistema, tela de splash de inicialização e tela de bloqueio, necessárias para empacotamento e publicação na Microsoft Store:

Por que esses arquivos existem? Porque escolhemos um modelo de projeto empacotado na criação. Empacotar significa compilar o aplicativo no formato MSIX para distribuição na Microsoft Store. Qual a diferença entre projeto empacotado e não empacotado? O projeto não empacotado gera um arquivo exe independente que executa diretamente com um duplo clique, como muitos projetos antigos. Já o empacotado agrupa todos os exe, dll e recursos em um único arquivo instalável que o usuário abre para instalar o app. Escolhemos esse modelo pois vamos publicar o aplicativo na Microsoft Store.

A captura acima mostra o modelo selecionado. Sua descrição informa que ele gera arquivos MSIX para publicação na Microsoft Store. A loja exige vários ícones e imagens, por isso eles vêm inclusos no projeto. Também é possível criar projetos não empacotados que geram apenas um exe executável, falaremos sobre isso mais tarde.

Função de cada imagem

Arquivo	Função
LockScreenLogo.scale-200.png	Ícone do app na tela de bloqueio (escala DPI 200%)
SplashScreen.scale-200.png	Tela de carregamento ao abrir o programa
Square44x44Logo… várias imagens	Ícone pequeno do menu Iniciar, ícone da barra de tarefas, miniatura da janela com Alt+Tab
Square150x150Logo.scale-200.png	Ícone de bloco médio do menu Iniciar
StoreLogo.png	Ícone grande do app exibido na Microsoft Store
Wide310x150Logo.scale-200.png	Bloco largo do menu Iniciar

app.manifest

Manifesto tradicional de aplicativos Windows (compatível com Win32):

Configura permissões do app, versões compatíveis do Windows, detecção DPI, permissões de administrador e comportamento de escala de janelas;
Diferente do Package.appxmanifest dos UWP: projetos de área de trabalho empacotados possuem os dois manifestos simultaneamente.

4. App.xaml / App.xaml.h / App.xaml.cpp

Classe raiz global e ponto de entrada da aplicação (corresponde a winrt::App3::App)

App.xaml: Dicionário de recursos XAML global. Estilos globais, modelos de controles, cores, fontes e recursos de tema compartilhados por todas as páginas do projeto.
App.xaml.h: Arquivo de cabeçalho gerado automaticamente pelo C++/WinRT, declara a classe App e suas funções de ciclo de vida como OnLaunched e OnActivated.
App.xaml.cpp: Implementação da lógica do ciclo de vida do app:
- OnLaunched: Executado ao abrir o programa, cria e exibe a janela MainWindow;
- Gerencia ativação e suspensão de janelas, troca de temas e captura de exceções;
- Toda lógica de inicialização global (fontes, bancos de dados, serviços singleton) é escrita aqui.

Abra o arquivo cpp e você verá o código abaixo:

    void App::OnLaunched([[maybe_unused]] LaunchActivatedEventArgs const& e)
    {
        window = make<MainWindow>();
        window.Activate();
    }Code language: C++ (cpp)

A partir daqui o programa segue para o MainWindow. O App é apenas o ponto de entrada e não cria janelas; o MainWindow é o local que gera as janelas visíveis, controles e caixas de diálogo.

5. Conjunto completo MainWindow.xaml (janela principal)

Janela principal padrão do programa, janela raiz visível de nível superior para aplicativos de área de trabalho.

MainWindow.xaml: Layout da janela. Botões, caixas de texto, controles de navegação e o Frame que carrega páginas são definidos aqui;
MainWindow.idl: Arquivo de definição de interface IDL (núcleo do C++/WinRT). Declara propriedades, métodos e eventos expostos pela janela, usados para binding XAML, chamadas entre componentes e geração de metadados de tipos. Ao modificar, arquivos de ligação .h/.cpp são gerados automaticamente.
MainWindow.xaml.h: Arquivo de cabeçalho de classe gerado via IDL + XAML, contém declarações de membros de controles, construtores e manipuladores de eventos.
MainWindow.xaml.cpp: Lógica de negócio da janela: código para cliques de botão, binding de dados, navegação entre páginas e interações de controles.

Abaixo o conteúdo de MainWindow.xaml, arquivo responsável por renderizar controles e layouts:

<?xml version="1.0" encoding="utf-8"?>
<Window
    x:Class="App3.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:App3"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    Title="App3">

    <Grid>

    </Grid>
</Window>
Code language: HTML, XML (xml)

6. module.g.cpp

Arquivo de módulo global C++/WinRT gerado automaticamente (proibido edição manual)

Gera código de registro de tipos WinRT a partir de todos os arquivos .idl;
Fornece o ponto de entrada do namespace winrt::App3::implementation, para o sistema reconhecer controles XAML e classes de janela personalizadas;
Ao adicionar ou remover arquivos IDL, o Visual Studio regenera este arquivo automaticamente.

7. Package.appxmanifest (Manifesto de pacote MSIX, arquivo fundamental)

Arquivo de configuração para empacotar apps de área de trabalho em instaladores MSIX. Clique duas vezes para abrir no editor visual:

Nome do app, versão, editor, ícones e ponto de inicialização;
Declaração de permissões do sistema (acesso a arquivos, câmera, rede, tarefas em segundo plano);
Associação de protocolos de abertura de arquivos, protocolos URL e extensões;
Configuração de dados de publicação na loja, atalhos de área de trabalho e associações de arquivos. Diferença do app.manifest: este é o manifesto exclusivo para Microsoft Store / pacotes MSIX, usado apenas em UWP e apps de área de trabalho empacotados.

Aqui configuramos dados relacionados à Microsoft Store como versão, nome do pacote, editor, etc. Essas informações devem ser obtidas no portal de desenvolvedores da Microsoft Store.

8. packages.config

Arquivo de configuração de pacotes NuGet: registra a versão de todos os pacotes NuGet instalados no projeto, como:

Bibliotecas Microsoft.Windows.SDK.NET, Windows App SDK, C++/WinRT, WinUI 3;
Ao trabalhar em equipe ou trocar de máquina, o Visual Studio usa esse arquivo para restaurar automaticamente todos os pacotes de dependência.

9. pch.h/pch.cpp (Cabeçalhos pré-compilados, acelera compilação C++)

pch = Precompiled Header (cabeçalho pré-compilado)

pch.h: Agrupa todos os cabeçalhos globais compartilhados (winrt/Windows.*, Microsoft.UI.Xaml.*, bibliotecas padrão). Todo arquivo cpp inicia com a linha #include "pch.h";
pch.cpp: Arquivo fonte para compilar o cabeçalho pré-compilado. Função: reduz drasticamente o tempo de compilação, evitando carregar centenas de cabeçalhos de sistema em cada arquivo separadamente.

Todos os includes compartilhados são agrupados aqui. Os demais arquivos fonte apenas importam esse arquivo, reduzindo linhas de código e agilizando a compilação.

10. readme.txt

Documento incluso no modelo do Visual Studio, com instruções básicas de compilação, empacotamento e depuração para projetos WinUI 3 em C++.

Os dois arquivos manifesto que causam confusão

app.manifest → Manifesto de processo Win32 tradicional (janelas, compatibilidade com sistema, permissões)
Package.appxmanifest → Manifesto de pacote MSIX do aplicativo (publicação na loja, instalação, declaração de funcionalidades do sistema)

Fluxo completo de execução do programa

Início do programa → Entra em App::OnLaunched(App.xaml.cpp)
Cria instância do MainWindow e ativa para exibição: window = make(); window.Activate();
MainWindow.xaml renderiza a interface, o arquivo cpp gerencia todas as interações do usuário
Ao gerar o pacote de instalação, lê o Package.appxmanifest para criar o instalador, e todos os ícones da pasta Assets são embutidos no pacote

Essa é toda a explicação sobre a estrutura de pastas e fluxo de execução do projeto vazio mais simples. Na próxima aula, adicionaremos um botão na janela que incrementa um número ao ser clicado, para entender o funcionamento interno do framework WinUI C++.

Previous: Instalar o WinUI com C++ e criar seu primeiro projeto