Обзор первой программы WinUI на C++ - Winui C++

На предыдущем занятии мы завершили установку WinUI C++ и создали первую рабочую программу. В этом уроке разберем структуру этого первого проекта WinUI на C++.

Ниже рассмотрим назначение каждого файла и папки.

Анализ директории проекта

Имя решения

В самом верху строка «Solution ‘App3’» — это имя решения, в данном случае App3. При создании проекта можно задать произвольное имя решения; по умолчанию оно совпадает с именем проекта.

На скриншоте первое поле ввода — имя проекта, последнее — имя решения. По умолчанию они одинаковые, но можно задать разные значения.

Одно решение может объединять несколько проектов; здесь присутствует только один упакованный десктопный проект App3 (Desktop).

1. References (Ссылки)

Эта папка хранит ссылки на зависимые SDK, Windows App SDK, среду выполнения WinRT и компоненты, установленные через NuGet:

Здесь управляются все зависимости: Windows SDK, библиотека элементов управления WinUI 3, заголовочные файлы C++/WinRT, Microsoft.UI.Xaml и другие;
Ручное редактирование не требуется, Visual Studio обновляет ссылки автоматически при работе с пакетами NuGet.

2. External Dependencies (Внешние зависимости)

Папка автоматически сканирует системные заголовки, заголовки SDK и библиотек сторонних разработчиков:

Windows.h, набор заголовков из каталога winrt/, низкоуровневые заголовки Microsoft.UI.Xaml;
Папка доступна только для чтения, служит для просмотра внешнего кода, ручное редактирование запрещено. Обычно содержит библиотеки, поставляемые вместе с Visual Studio.

Дважды щелкните любой файл для открытия — вы увидите, что его путь расположен в каталоге установки Visual Studio. Наведите курсор на имя файла в верхней части редактора для отображения полного пути.

3. Папка Assets (Ресурсы: иконки и экран загрузки)

Содержит все изображения для Microsoft Store, системных окон, заставки запуска и экрана блокировки, необходимые для упаковки и публикации в Microsoft Store:

Почему эти файлы присутствуют? При создании проекта мы выбрали шаблон с упаковкой. Упаковка означает компиляцию приложения в формат MSIX для распространения через Microsoft Store. В чем разница между упакованным и неупакованным проектом? Неупакованный проект генерирует отдельный exe-файл, запускаемый двойным щелчком — так работают многие старые проекты. Упакованный вариант объединяет все exe, dll и ресурсы в один установочный файл, который пользователю достаточно открыть для установки приложения. Мы выбрали этот шаблон, так как планируем опубликовать программу в Microsoft Store.

На скриншоте выше показан выбранный шаблон. Из описания видно, что он создает файлы MSIX для публикации в Microsoft Store. Магазин требует множество иконок и графических элементов, поэтому они включены в проект изначально. Также можно создавать неупакованные проекты, выдающие только исполняемый exe — мы разберем этот вариант позже.

Назначение каждого изображения

Файл	Назначение
LockScreenLogo.scale-200.png	Иконка приложения на экране блокировки (масштабирование DPI 200%)
SplashScreen.scale-200.png	Заставка при запуске программы
Square44x44Logo… несколько изображений	Маленькая иконка меню «Пуск», значок панели задач, миниатюра окна по сочетанию Alt+Tab
Square150x150Logo.scale-200.png	Средняя плитка меню «Пуск»
StoreLogo.png	Большая иконка приложения, отображаемая в Microsoft Store
Wide310x150Logo.scale-200.png	Широкая плитка меню «Пуск»

app.manifest

Традиционный манифест приложений Windows (совместимость с Win32):

Задает права приложения, совместимые версии Windows, распознавание DPI, права администратора и поведение масштабирования окон;
Отличается от собственного Package.appxmanifest для UWP: упакованные десктопные проекты содержат оба манифеста одновременно.

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

Глобальный корневой класс, точка входа в приложение (соответствует winrt::App3::App)

App.xaml: глобальный словарь ресурсов XAML. Содержит общие стили, шаблоны элементов управления, цвета, шрифты и тематические ресурсы, доступные всем страницам проекта.
App.xaml.h: заголовочный файл, генерируемый автоматически C++/WinRT, объявляет класс App и его функции жизненного цикла: OnLaunched, OnActivated и другие.
App.xaml.cpp: реализация логики жизненного цикла приложения:
- OnLaunched: выполняется при запуске программы, создает и отображает окно MainWindow;
- Обрабатывает активацию и приостановку окон, смену тем и перехват исключений;
- Здесь размещается вся глобальная логика инициализации (шрифты, базы данных, одиночные сервисы).

Откройте cpp-файл, там вы найдете такой код:

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

С этого момента управление программой переходит к MainWindow. App — лишь точка входа, он не создает окна; именно MainWindow формирует видимые окна, элементы управления и диалоговые окна.

5. Комплект MainWindow.xaml (Основное окно)

Стандартное главное окно программы, корневое видимое окно верхнего уровня для десктопных приложений.

MainWindow.xaml: макет окна. Здесь задаются кнопки, текстовые поля, элементы навигации и контейнер Frame для размещения страниц;
MainWindow.idl: Файл определения интерфейса IDL (ядро C++/WinRT). Описывает свойства, методы и события, предоставляемые окном, используется для XAML-биндинга, межкомпонентных вызовов и генерации метаданных типов. При изменении автоматически создаются связанные файлы .h/.cpp.
MainWindow.xaml.h: классный заголовок, сгенерированный по IDL и XAML, содержит объявления членов элементов управления, конструкторов и обработчиков событий.
MainWindow.xaml.cpp: бизнес-логика окна: код для обработки нажатий кнопок, привязки данных, переходов между страницами и взаимодействия с элементами управления.

Ниже содержимое MainWindow.xaml — файла, отвечающего за отображение элементов и макета:

<?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

Автоматически генерируемый файл глобального модуля C++/WinRT (ручное редактирование запрещено)

Генерирует код регистрации типов WinRT на основе всех файлов .idl;
Предоставляет точку входа пространства имен winrt::App3::implementation, чтобы система распознавала пользовательские XAML-элементы управления и классы окон;
При добавлении или удалении IDL-файлов Visual Studio пересоздает этот файл автоматически.

7. Package.appxmanifest (Манифест пакета MSIX, ключевой файл)

Файл конфигурации для упаковки десктопных приложений в установочные пакеты MSIX. Дважды щелкните для открытия визуального редактора:

Имя приложения, версия, издатель, иконки, точка запуска;
Объявление системных прав (доступ к файлам, камера, сеть, фоновые задачи);
Привязка протоколов открытия файлов, URL-протоколов и расширений;
Настройка данных публикации в магазине, ярлыков рабочего стола и ассоциаций файлов. Отличие от app.manifest: этот файл — специализированный манифест для Microsoft Store / пакетов MSIX, используется исключительно для UWP и упакованных десктопных приложений.

Здесь задаются параметры для Microsoft Store: версия, имя пакета, издатель и другие данные. Эти сведения необходимо получить в личном кабинете разработчика Microsoft Store.

8. packages.config

Файл конфигурации пакетов NuGet: сохраняет версии всех установленных в проект пакетов NuGet, например:

Библиотеки Microsoft.Windows.SDK.NET, Windows App SDK, C++/WinRT, WinUI 3;
При совместной работе в команде или смене компьютера Visual Studio использует этот файл для автоматического восстановления всех зависимых пакетов.

9. pch.h/pch.cpp (Предварительно скомпилированные заголовки, ускорение сборки C++)

pch = Precompiled Header (предварительно скомпилированный заголовок)

pch.h: объединяет все общие глобальные заголовки (winrt/Windows.*, Microsoft.UI.Xaml.*, стандартные библиотеки). Каждый cpp-файл начинается строкой #include "pch.h";
pch.cpp: исходный файл для сборки предварительно скомпилированного заголовка. Его задача: значительно сократить время компиляции, исключая повторную загрузку сотен системных заголовков в каждый файл по отдельности.

Все повторно используемые директивы include собраны здесь, остальные исходные файлы подключают только этот один файл — это сокращает объем кода и ускоряет процесс сборки.

10. readme.txt

Сопроводительный документ из шаблона Visual Studio, содержит базовые инструкции по сборке, упаковке и отладке проектов WinUI 3 на C++.

Два часто путаемых файла манифеста

app.manifest → традиционный манифест процесса Win32 (настройка окон, совместимость системы, права доступа)
Package.appxmanifest → манифест пакета приложения MSIX (публикация в магазине, установка, объявление системных функций)

Полный поток выполнения программы

Запуск программы → переход в App::OnLaunched(App.xaml.cpp)
Создание экземпляра MainWindow и активация отображения: window = make(); window.Activate();
MainWindow.xaml отрисовывает интерфейс, cpp-файл обрабатывает все взаимодействия пользователя
При сборке установочного пакета считывается Package.appxmanifest для генерации инсталлятора, все иконки из папки Assets встраиваются в пакет

Это полное описание структуры каталогов и последовательности работы самого простого пустого проекта. На следующем занятии мы добавим на окно кнопку, увеличивающую число при нажатии, чтобы понять внутренний механизм работы фреймворка WinUI C++.

Previous: Установка WinUI на C++ и создание первого проекта