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

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

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

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

Важным аспектом любого проекта 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 одного проекта.

   

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

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

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

   

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

   

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

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

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.

   

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

API загрузчика

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

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

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

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

В этом пошаговом руководстве мы использовали шаблон проекта "Пустое приложение" (Packaged (WinUI 3 в desktop), который создает классическое приложение с пользовательским интерфейсом 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".

См. также

• WinUI 3
• Каналы выпуска пакета SDK для приложений Windows
• Установка инструментов для Windows App SDK
• Сведения об MSIX
• Упаковка приложения с помощью единого проекта MSIX
• Шаблоны проектов WinUI 3 в Visual Studio
• Руководство по развертыванию пакета SDK для приложений, зависящих от платформы, с внешним расположением или распаковкой
• Распространяемый компонент Microsoft Visual C++ (VCRedist)
• Использование среды выполнения пакета SDK для приложений Windows, упакованных с внешним расположением или распаковкой
• Архитектура развертывания для пакета SDK для приложений Windows
• Руководство. Использование API начального загрузчика в приложении, упакованом с внешним расположением или распаковкой, использующим пакет SDK для приложений Windows
• Разработка классических приложений Windows