Создание первого проекта WinUI 3 (Windows App SDK)

  • Статья

В этом разделе показано, как с помощью Visual Studio создать новый проект Windows App SDK для приложения C# .NET или C++ с пользовательским интерфейсом на основе Библиотеки пользовательского интерфейса Windows (WinUI) 3. Мы также рассмотрим часть кода в итоговом проекте, в том числе его задачи и принцип работы.

Ссылки на подробные инструкции по установке приведены в следующих шагах. Рекомендуется установить и нацелить последний стабильный выпуск Windows App SDK (см. Заметки о выпуске для стабильного канала).

Совет

Вне зависимости от версии Windows App SDK, которую вы установите и нацелите, (и от используемой версии Visual Studio) необходимо проверить в заметках о выпуске все ограничения и известные проблемы для выбранной версии (см. Каналы выпуска Windows App SDK). Зная ограничения и известные проблемы для своей версии Windows App SDK, вы сможете реализовать обходное решение, если столкнетесь с ними во время выполнения шагов в этом разделе.

Если вы столкнетесь с другими проблемами, сведения о них можно найти в разделе проблем на GitHub, на вкладке "Обсуждения"WindowsAppSDK репозитория GitHub или с помощью поиска в Интернете.

Важно!

Если вы работаете с приложением UWP, перейдите к разделу "Миграция из UWP" в пакет SDK для приложений Windows.

Упакованные, распакованные и упакованные с внешним расположением

Важным аспектом любого проекта Windows App SDK является упаковка. Дополнительные сведения о вариантах упаковки см. в разделе "Преимущества и недостатки упаковки приложения".

Упакованное приложение: создание нового проекта для упакованного классического приложения WinUI 3 на C# или C++

  1. Чтобы настроить среду разработки на компьютере, выполните инструкции из статьи Установка средств для пакета SDK для приложений Windows.

  2. В Visual Studio выберите Файл>Создать>Проект.

  3. В раскрывающихся фильтрах диалогового окна "Новый проект" выберите C#/C++, Windows и winui соответственно.

  4. Выберите шаблон проекта Blank App, Packaged (WinUI 3 in Desktop) (Пустое, упакованное приложение (WinUI 3 в классических приложениях)) и щелкните Далее. Этот шаблон создает классическое приложение с пользовательским интерфейсом на основе WinUI 3. Созданный проект настраивается с помощью манифеста пакета и других средств, которые требуются для компиляции приложения в пакет MSIX (подробнее об этом формате см. здесь). Дополнительные сведения об этом шаблоне проекта см. в статье Упаковка приложения с помощью пакета MSIX одного проекта.

    Screenshot of Create a new project wizard with the Blank App Packaged (Win UI in Desktop) option highlighted.

  5. Введите имя проекта, при необходимости выберите другие параметры, а затем нажмите кнопку Создать.

  6. Проект, который создаст Visual Studio, содержит код вашего приложения. Файл App.xaml и файлы кода программной части определяют класс, производный от Application, который представляет выполняемое приложение. Файл MainWindow.xaml и файл кода программной части определяют класс MainWindow, который представляет главное окно, отображаемое приложением. Эти классы являются производными от типов в пространстве имен Microsoft.UI.Xaml, который предоставляет WinUI 3.

    Также этот проект включает манифест пакета для компиляции приложения в пакет MSIX.

    Screenshot of Visual Studio showing the Solution Explorer pane and the contents of the Main Windows X A M L dot C S file for single project M S I X.

  7. Чтобы добавить новый элемент в приложение, в Обозревателе решений щелкните правой кнопкой мыши узел проекта и выберите Добавить>Создать элемент. В диалоговом окне Добавление нового элемента щелкните вкладку WinUI, выберите нужный элемент и нажмите кнопку Добавить. Дополнительные сведения о доступных элементах см. в статье Шаблоны WinUI 3 в Visual Studio.

    Screenshot of the Add New Item dialog box with the Installed > Visual C sharp Items > Win U I selected and the Blank Page option highlighted.

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

Неупакованное приложение: создание нового проекта для неупакованного классического приложения WinUI 3 на C# или C++

Важно!

Начиная с пакета SDK для приложений Windows 1.0, подход по умолчанию к загрузке пакета SDK для приложений Windows из пакета с внешним расположением или распаковкой приложения заключается в использовании автоматической инициализации через <WindowsPackageType> свойство проекта (а также внесение дополнительных изменений в конфигурацию). Чтобы узнать об этапах автоматической инициализации в контексте проекта WinUI 3, ознакомьтесь с этим разделом. Кроме того, если у вас есть существующий проект, который не является WinUI 3, см. статью "Использование пакета SDK для приложений Windows" в существующем проекте.

  1. Чтобы настроить среду разработки на компьютере, выполните инструкции из статьи Установка средств для пакета SDK для приложений Windows.

  2. Скачайте и запустите последнюю версию установщика для Windows App SDK на странице Загрузки для Windows App SDK. Это установит зависимости пакета среды выполнения, необходимые для запуска и развертывания пакета с внешним расположением или распакованным приложением на целевом устройстве (см . руководство по развертыванию пакета SDK для приложений windows, упакованных с внешним расположением или распаковкой).

  3. C++. Установите распространяемый компонент Microsoft Visual C++ (VCRedist) для архитектуры целевого устройства.

    • Последняя версия VCRedist совместима с последним общедоступным (то есть не предварительной версии) выпуском Visual Studio, а также со всеми версиями Visual Studio, которые можно использовать для компиляции двоичных файлов пакета SDK для приложений Windows.
    • В сборках Visual Studio для предварительной оценки может быть установлена более поздняя версия VCRedist. В таком случае запуск общедоступной версии завершится сбоем со следующим сообщением об ошибке, которое вы можете игнорировать: Error 0x80070666: Cannot install a product when a newer version is installed (Ошибка 0x80070666: не удается установить продукт, если установлена более новая версия).

    Примечание.

    Если на целевом устройстве не установлен VCRedist, динамическая ссылка на c:\windows\system32\vcruntime140.dll возвратит ошибку. Такой сбой может по-разному отображаться на пользователей приложения.

  4. В Visual Studio выберите Файл>Создать>Проект.

  5. В раскрывающихся фильтрах для создания проекта выберите C#/C++, Windows и WinUI, соответственно.

  6. Чтобы использовать диагностику XAML, необходимо начинать работу с упакованным проектом. Поэтому выберите шаблон проекта Blank App, Packaged (WinUI 3 in Desktop) (Пустое, упакованное приложение (WinUI 3 в классических приложениях)) и щелкните Далее.

    Важно!

    Убедитесь, что созданный проект предназначен для версии пакета SDK для приложений Windows, установленного с установщиком на шаге 2. Для этого в Visual Studio щелкните Инструменты>Диспетчер пакетов NuGet>Управление пакетами NuGet для решения>Обновления. При необходимости обновите ссылку на пакет NuGet Microsoft.WindowsAppSDK. Вы можете увидеть, какая версия установлена на вкладке Установлено.

  7. Добавьте следующее свойство в файл проекта — это файл .csproj (для C#) или .vcxproj (для C++). Поместите его в элемент PropertyGroup, который уже существует (для C++, элемент будет включать Label="Globals"):

    <Project ...>
  ...
  <PropertyGroup>
    ...
    <WindowsPackageType>None</WindowsPackageType>
    ...
  </PropertyGroup> 
  ...
</Project>

  8. C++. В файле проекта C++ (.vcxproj) в элементе PropertyGroup, который уже существует, задайте свойству AppxPackage значение false:

    <Project ...>
  ...
  <PropertyGroup Label="Globals">
    ...
    <AppxPackage>false</AppxPackage>
    ...
  </PropertyGroup> 
  ...
</Project>

  9. C#. Чтобы запустить приложение C# из Visual Studio (в режиме Отладка или Без отладки), выберите в раскрывающемся списке Запуск профиль запуска Unpackaged (Неупакованный). Если выбран профиль Packaged (Упакованный), вы увидите ошибку развертывания в Visual Studio. Этот шаг не нужен, если вы выполняете приложение (.exe) из командной строки или проводника Windows.

    Visual Studio - Start drop-down with C# application unpackaged launch profile highlighted

  10. Выполните сборку и запуск.

API загрузчика

Если установить свойство проекта <WindowsPackageType>None</WindowsPackageType>, автоинициализатор будет находить и загружать версию Windows App SDK, оптимальную для вашего приложения.

Если у вас есть дополнительные требования (например, настраиваемая обработка ошибок или загрузка определенной версии Windows App SDK), вы можете явно вызвать API загрузчика. Дополнительные сведения см. в статье "Использование среды выполнения пакета SDK для приложений Windows" для приложений, упакованных с внешним расположением или распаковкой, и руководство. Использование API начальной загрузки в приложении, упакованом с внешним расположением или распаковкой, использующим пакет SDK для приложений Windows.

Дополнительные сведения о загрузчике см. в статье Архитектура развертывания и общие сведения о приложениях, зависимых от платформы.

Изучение кода в шаблоне проекта

В этом руководстве мы использовали шаблон проекта Пустое, упакованное приложение (WinUI 3 в классических приложениях), который создает классическое приложение с пользовательским интерфейсом на основе WinUI 3. Давайте рассмотрим часть кода, поставляемого с этим шаблоном, и выполняемые им задачи. Дополнительные сведения о доступных шаблонах проектов и элементов WinUI 3 см. в статье Шаблоны WinUI 3 в Visual Studio.

Точка входа приложения

Когда ОС Windows запускает приложение, она начинает выполнение в его точке входа. Эта точка входа представляет собой функцию Main (или wWinMain в случае C++/WinRT). Как правило, в новом проекте настраивается автоматическое создание этой функции, активируемое процессом сборки Visual Studio. Она скрыта по умолчанию, поэтому вам не нужно о ней беспокоиться. Но если вы хотите получить дополнительные сведения, см. раздел Настройка создания единственного экземпляра в Main или wWinMain.

Класс App

Приложение в целом представляется классом, который обычно называется App. Этот класс определен в файле App.xaml и в его файлах кода программной части (App.xaml.cs либо App.xaml.h и .cpp). Класс App является производным от класса WinUI 3 Microsoft.UI.Xaml.Application.

Созданный код в точке входа создает экземпляр App и задает его выполнение.

В конструкторе App вызывается метод InitializeComponent. Этот метод по сути анализирует содержимое файла App.xaml, который является разметкой XAML. И это важно, так как App.xaml содержит объединенные ресурсы, которые необходимо разрешить и загрузить в словарь для использования в работающем приложении.

Еще один представляющий интерес метод App — OnLaunched. В нем создается и активируется новый экземпляр класса MainWindow, который мы рассмотрим далее.

Класс MainWindow

Главное окно приложения, конечно же, представлено классом MainWindow. Этот класс определен в файле MainWindow.xaml и в его файлах кода программной части (MainWindow.xaml.cs либо MainWindow.xaml.h и .cpp). Класс MainWindow является производным от класса WinUI 3 Microsoft.UI.Xaml.Window.

Конструктор MainWindow вызывает собственный метод InitializeComponent. Опять же, его задание заключается в том, чтобы превратить разметку XAML в MainWindow.xaml в граф объектов пользовательского интерфейса.

В файле MainWindow.xaml виден базовый макет MainWindow. В корне макета находится динамическая панель с именем Microsoft.UI.Xaml.Controls.StackPanel. Дополнительные сведения о панелях макета см. в статье Панели макета.

Внутри StackPanel находится Microsoft.UI.Xaml.Controls.Button. И эта кнопка (Button) использует разметку Click="myButton_Click", чтобы декларативно подключить метод обработчика событий для события нажатия (Click).

Этот метод называется myButton_Click, и реализацию этого метода можно найти в MainWindow.xaml.cs или в MainWindow.xaml.cpp. В нем содержимое кнопки меняется со значения по умолчанию "Click Me" на "Clicked".

C++. Если вы создали проект C++, вы также увидите файл MainWindow.idl. Дополнительные сведения см. в документации по C++/WinRT. Начать изучение целей и способов использования файлов .idl можно со статьи Элементы управления XAML; привязка к свойству/WinRT C++.

Следующие шаги

В этом разделе показано, как создать проект Visual Studio для упаковаемого или распаковки приложения. Пример добавления функций в такое приложение см. в руководстве . Создание простого средства просмотра фотографий с помощью WinUI 3. В этом разделе описывается процесс создания простого приложения для отображения фотографий.

Затем, чтобы продолжить разработку с помощью пакета SDK для приложений Windows, см. статью "Разработка классических приложений Windows".