Introducción al primer programa WinUI en C++

En la clase anterior completamos la instalación de WinUI C++ y creamos nuestro primer programa funcional. En esta lección analizaremos la estructura interna de este primer proyecto WinUI en C++.

A continuación explicamos la función de cada archivo y carpeta.

Análisis del directorio del proyecto

Nombre de la solución

En la parte superior aparece «Solution ‘App3’», ese es el nombre de la solución, en este caso App3. Al crear un proyecto puedes definir un nombre personalizado para la solución; por defecto coincide con el nombre del proyecto.

En la captura, el primer campo de texto corresponde al nombre del proyecto y el último al nombre de la solución. Por defecto ambos son iguales, pero puedes asignar nombres distintos.

Una solución puede agrupar varios proyectos; aquí solo tenemos un proyecto empaquetado de escritorio: App3 (Desktop).

1. References (Referencias)

Esta carpeta almacena las referencias a los SDK de los que depende el proyecto, Windows App SDK, el tiempo de ejecución WinRT y los componentes instalados mediante NuGet:

• Aquí se gestionan todas las dependencias: Windows SDK, biblioteca de controles WinUI 3, archivos de cabecera C++/WinRT, Microsoft.UI.Xaml, entre otros;
• No hace falta modificarlo manualmente, Visual Studio lo actualiza automáticamente al gestionar los paquetes NuGet.

2. External Dependencies (Dependencias externas)

Esta carpeta escanea automáticamente los archivos de cabecera del sistema, cabeceras de SDK y cabeceras de bibliotecas de terceros:

• Windows.h, las cabeceras de la carpeta winrt/, las cabeceras de bajo nivel de Microsoft.UI.Xaml;
• Solo lectura: sirve para consultar código externo, no se puede editar manualmente. Normalmente contiene bibliotecas incluidas al instalar Visual Studio.

Haz doble clic en cualquier archivo para abrirlo y verás que su ruta está dentro del directorio de instalación de Visual Studio. Coloca el cursor sobre el nombre del archivo en la parte superior para ver la ruta completa.

3. Carpeta Assets (Recursos: iconos y pantalla de arranque)

Contiene todas las imágenes que usa la Tienda Microsoft, ventanas del sistema, pantalla de carga inicial y pantalla de bloqueo, necesarias para empaquetar y publicar en la Tienda Microsoft:

¿Por qué existen estos archivos? Porque al crear el proyecto elegimos una plantilla empaquetada. Empaquetar significa compilar la aplicación a formato MSIX para distribuirla en la Tienda Microsoft. ¿Cuál es la diferencia entre proyecto empaquetado y sin empaquetar? El proyecto sin empaquetar genera un archivo exe independiente que se ejecuta directamente al hacer doble clic, así funcionaban muchos proyectos antiguos. En cambio, el empaquetado agrupa todos los exe, dll y recursos en un solo archivo instalable que los usuarios solo deben abrir para instalar la app. Elegimos esta plantilla porque nuestra app se publicará en la Tienda Microsoft.

La captura anterior muestra la plantilla seleccionada. Su descripción indica que genera archivos MSIX para publicar en la Tienda Microsoft. La tienda requiere múltiples iconos e imágenes, por eso vienen incluidos en el proyecto. También es posible crear proyectos sin empaquetar que solo generen un exe ejecutable, hablaremos de eso más adelante.

Función de cada imagen

Archivo	Función
LockScreenLogo.scale-200.png	Icono de la app en la pantalla de bloqueo (escala DPI 200%)
SplashScreen.scale-200.png	Pantalla de carga al abrir el programa
Square44x44Logo… varias imágenes	Icono pequeño del menú Inicio, icono de barra de tareas, miniatura de ventana al pulsar Alt+Tab
Square150x150Logo.scale-200.png	Icono de mosaico mediano del menú Inicio
StoreLogo.png	Icono grande de la app que se muestra en la Tienda Microsoft
Wide310x150Logo.scale-200.png	Mosaico ancho del menú Inicio

app.manifest

Manifiesto tradicional de aplicaciones Windows (compatible con Win32):

• Configura permisos de la app, versiones de Windows compatibles, detección DPI, permisos de administrador y comportamiento de escalado de ventanas;
• Se diferencia del Package.appxmanifest propio de UWP: los proyectos de escritorio empaquetados cuentan con ambos manifiestos simultáneamente.

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

Clase raíz global y punto de entrada de la aplicación (corresponde a winrt::App3::App)

1. App.xaml: Diccionario de recursos XAML global. Estilos globales, plantillas de controles, colores, fuentes y recursos de tema compartidos por todas las páginas del proyecto.
2. App.xaml.h: Archivo de cabecera generado automáticamente por C++/WinRT, declara la clase App y sus funciones de ciclo de vida como OnLaunched y OnActivated.
3. App.xaml.cpp: Implementación de la lógica del ciclo de vida de la app:
   • OnLaunched: Se ejecuta al abrir el programa, crea y muestra la ventana MainWindow;
   • Gestiona la activación y suspensión de ventanas, cambio de temas y captura de excepciones;
   • Aquí escribimos toda la lógica de inicialización global (fuentes, bases de datos, servicios singleton).

Abre el archivo cpp y verás este código:

    void App::OnLaunched([[maybe_unused]] LaunchActivatedEventArgs const& e)
    {
        window = make<MainWindow>();
        window.Activate();
    }Lenguaje del código: C++ (cpp)

Desde este punto el programa pasa a MainWindow. App solo es el punto de entrada y no crea ventanas; MainWindow es el elemento que genera las ventanas visibles, controles y cuadros de diálogo.

5. Conjunto completo MainWindow.xaml (ventana principal)

Ventana principal predeterminada del programa, ventana raíz visible de nivel superior para aplicaciones de escritorio.

1. MainWindow.xaml: Diseño de la ventana. Aquí definimos botones, cajas de texto, controles de navegación y el Frame que alberga páginas;
2. MainWindow.idl: Archivo de definición de interfaz IDL (núcleo de C++/WinRT). Declara propiedades, métodos y eventos expuestos por la ventana, usados para binding XAML, llamadas entre componentes y generación de metadatos de tipos. Al modificarlo se generan automáticamente archivos .h/.cpp de enlace.
3. MainWindow.xaml.h: Archivo de cabecera de clase generado a partir de IDL y XAML, almacena declaraciones de miembros de controles, constructores y manejadores de eventos.
4. MainWindow.xaml.cpp: Lógica de negocio de la ventana: código para clics de botones, binding de datos, navegación entre páginas e interacciones con controles.

A continuación el contenido de MainWindow.xaml, el archivo donde definimos controles y diseños:

<?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>
Lenguaje del código: HTML, XML (xml)

6. module.g.cpp

Archivo generado automáticamente para el módulo global C++/WinRT (prohibido editar manualmente)

• Genera código de registro de tipos WinRT a partir de todos los archivos .idl;
• Proporciona el punto de entrada del espacio de nombres winrt::App3::implementation, para que el sistema reconozca controles XAML y clases de ventana personalizados;
• Al agregar o eliminar archivos IDL, Visual Studio lo regenera automáticamente.

7. Package.appxmanifest (Manifiesto de paquete MSIX, archivo fundamental)

Archivo de configuración para empaquetar aplicaciones de escritorio en instaladores MSIX. Haz doble clic para abrirlo con el editor visual:

• Nombre de la app, versión, editor, iconos y punto de arranque;
• Declaración de permisos del sistema (acceso a archivos, cámara, red, tareas en segundo plano);
• Asociación de protocolos de apertura de archivos, protocolos URL y extensiones;
• Configuración de datos de publicación en tienda, accesos directos de escritorio y asociaciones de archivos. Diferencia con app.manifest: este es el manifiesto exclusivo para Tienda Microsoft / paquetes MSIX, propio de UWP y apps de escritorio empaquetadas.

Aquí configuramos datos relacionados con la Tienda Microsoft como versión, nombre del paquete, editor, etc. Estos datos debemos obtenerlos desde el portal de desarrolladores de la Tienda Microsoft.

8. packages.config

Archivo de configuración de paquetes NuGet: registra la versión de todos los paquetes NuGet instalados en el proyecto, como:

• Bibliotecas Microsoft.Windows.SDK.NET, Windows App SDK, C++/WinRT, WinUI 3;
• Al trabajar en equipo o cambiar de equipo, Visual Studio usa este archivo para restaurar automáticamente todos los paquetes de dependencias.

9. pch.h/pch.cpp (Cabeceras precompiladas, aceleran la compilación C++)

pch = Precompiled Header (cabecera precompilada)

1. pch.h: Agrupa todas las cabeceras globales compartidas (winrt/Windows.*, Microsoft.UI.Xaml.*, bibliotecas estándar). Cada archivo cpp empieza con la línea #include "pch.h";
2. pch.cpp: Archivo fuente para compilar la cabecera precompilada. Su función: reducir mucho el tiempo de compilación al evitar cargar cientos de cabeceras de sistema en cada archivo por separado.

Todos los includes compartidos se agrupan aquí. Los demás archivos fuente solo importan este archivo, reduciendo líneas de código y agilizando la compilación.

10. readme.txt

Documento incluido en la plantilla de Visual Studio, con instrucciones básicas para compilar, empaquetar y depurar proyectos WinUI 3 en C++.

Los dos archivos manifest que suelen confundirse

1. app.manifest → Manifiesto de proceso Win32 tradicional (ventanas, compatibilidad del sistema, permisos)
2. Package.appxmanifest → Manifiesto de paquete MSIX de aplicación (publicación en tienda, instalación, declaración de funcionalidades del sistema)

Flujo completo de ejecución del programa

1. Inicio del programa → Entra en App::OnLaunched(App.xaml.cpp)
2. Crea la instancia de MainWindow y la activa para mostrarla: window = make(); window.Activate();
3. MainWindow.xaml renderiza la interfaz, el archivo cpp gestiona todas las interacciones del usuario
4. Al generar el paquete de instalación lee Package.appxmanifest para crear el instalador, y todos los iconos de la carpeta Assets se incrustan dentro del paquete

Esto es toda la explicación sobre la estructura de directorios y el flujo de ejecución del proyecto vacío más simple. En la próxima lección añadiremos un botón a la ventana que incremente un número al pulsarlo, para entender el funcionamiento interno del framework WinUI C++.