Тема 1.2: Налаштування середовища розробки

Вступ

Тепер, коли ми знаємо, що таке WinUI 3 і чому він крутий, час підготувати все необхідне для роботи. У цій темі ми налаштуємо середовище розробки, створимо наш перший проєкт і розберемо його структуру. Наприкінці ви побачите, як запустити простий додаток "Hello World" на WinUI 3. Готові? Тоді вперед!

1. Встановлення Visual Studio 2022 із підтримкою Windows App SDK

Щоб працювати з WinUI 3, нам потрібен правильний інструмент — Visual Studio 2022. Це основне середовище для розробки додатків на C# і WinUI.

Крок 1: Завантаження Visual Studio

  • Перейдіть на офіційний сайт: visualstudio.microsoft.com.
  • Завантажте Visual Studio 2022 Community (безкоштовна версія для студентів і невеликих команд). Якщо у вас є доступ до Professional або Enterprise, вони теж підійдуть.
  • Запустіть інсталятор.

Крок 2: Вибір компонентів

  • У процесі встановлення вам запропонують обрати Workloads (набори інструментів). Оберіть:
    • Desktop development with C# — це включає все необхідне для WinUI 3 і Windows App SDK.
  • Додатково (опціонально):
    • English language pack (якщо хочете англійський інтерфейс).
    • Git for Windows (для роботи з контролем версій).
  • Натисніть "Install" і дочекайтеся завершення.

Крок 3: Перевірка

  • Після встановлення відкрийте Visual Studio.
  • Переконайтеся, що версія — 2022 (File → About). Якщо у вас стара версія (наприклад, 2019), оновіть її.

Чому саме Visual Studio?

Visual Studio — це не просто редактор коду. Воно має вбудовані шаблони для WinUI 3, дебагер для XAML і зручний інтерфейс для роботи з проєктами. Альтернативи (наприклад, VS Code) можна використовувати, але це складніше для початківців.

2. Огляд шаблонів проєктів WinUI 3 у Visual Studio

Visual Studio пропонує готові шаблони, щоб швидко почати роботу. Давайте подивимося, що доступно.

Як знайти шаблони?

  1. Відкрийте Visual Studio.
  2. Натисніть Create a new project.
  3. У пошуковому рядку введіть "WinUI".
  4. Фільтри: мова — C#, платформа — Windows.

Основні шаблони

  • Blank App, Packaged (WinUI 3 in Desktop):
    • Найпростіший шаблон для настільного додатка.
    • Використовує Windows App SDK і створює додаток у форматі MSIX (пакет для розгортання).
    • Ми використаємо саме його для "Hello World".
  • Blank App, Unpackaged (WinUI 3 in Desktop):
    • Те саме, але без MSIX. Підходить, якщо вам не потрібне пакування.
  • WinUI 3 Class Library:
    • Для створення бібліотеки, яку можна перевикористовувати в інших проєктах.

Що обрати?

Для початку беріть Blank App, Packaged. Це стандартний вибір для WinUI 3, який включає всі потрібні залежності.

3. Створення першого проєкту "Hello World" у WinUI 3

Тепер давайте створимо наш перший додаток!

Крок 1: Створення проєкту

  1. У Visual Studio виберіть Create a new project.
  2. Оберіть Blank App, Packaged (WinUI 3 in Desktop).
  3. Назвіть проєкт, наприклад, "HelloWorldWinUI".
  4. Вкажіть шлях для збереження (наприклад, C:\Projects\).
  5. Натисніть "Create".

Крок 2: Перший запуск

  • Натисніть F5 (або Debug → Start Debugging).
  • Зачекайте, поки Visual Studio збере проєкт і запустить додаток.
  • Ви побачите порожнє вікно з заголовком "HelloWorldWinUI". Вітаємо, ваш перший WinUI-додаток працює!

Крок 3: Додавання "Hello World"

  1. Відкрийте файл MainWindow.xaml у папці проєкту.
  2. Знайдіть тег <Window> ... </Window>.
  3. Додайте всередину простий текстовий елемент: 
    <TextBlock Text="Hello, World!" HorizontalAlignment="Center" VerticalAlignment="Center" />
  4. Збережіть файл (Ctrl+S) і запустіть знову (F5).
  5. Тепер у вікні з’явиться напис "Hello, World!".

4. Структура проєкту

Давайте розберемо, що створив Visual Studio.

Припустимо, ми створили проєкт із назвою "MyWinUIApp" за допомогою шаблону "Blank App, Packaged (WinUI 3 in Desktop)" у Visual Studio з використанням C# та .NET. Ось як виглядатиме структура в Solution Explorer:

MyWinUIApp (Solution)
├── MyWinUIApp (Проєкт)
│   ├── Properties
│   │   ├── launchSettings.json
│   ├── Assets
│   │   ├── LockScreenLogo.scale-200.png
│   │   ├── SplashScreen.scale-200.png
│   │   ├── Square150x150Logo.scale-200.png
│   │   ├── Square44x44Logo.scale-200.png
│   │   ├── StoreLogo.scale-200.png
│   │   ├── Wide310x150Logo.scale-200.png
│   ├── Package.appxmanifest
│   ├── App.xaml
│   │   ├── App.xaml.cs
│   ├── MainWindow.xaml
│   │   ├── MainWindow.xaml.cs
│   ├── MyWinUIApp.csproj
│   ├── packages.config (опціонально, якщо використовуються старіші пакети)

Тепер розберемо кожен елемент детально.

1. Рівень рішення (Solution)

  • MyWinUIApp.sln: Файл рішення Visual Studio, який об’єднує всі проєкти в рамках однієї "Solution". У простому випадку тут буде лише один проєкт (наприклад, "MyWinUIApp"), але якщо ви додаєте, наприклад, окремий проєкт для пакування (Windows Application Packaging Project), то в рішенні з’являться додаткові проєкти.

2. Рівень проєкту (Project)

Проєкт "MyWinUIApp" — це основний робочий простір, де міститься весь код, ресурси та конфігурація для вашого додатка.

2.1. Папка "Properties"

  • launchSettings.json: Файл конфігурації для запуску додатка в Visual Studio. Він визначає профілі запуску (наприклад, для відладки) і налаштування, такі як цільова платформа (x86, x64 тощо). Приклад вмісту: 
    {
  "profiles": {
    "MyWinUIApp": {
      "commandName": "Project",
      "applicationUrl": "http://localhost:5000"
    }
  }
}
    Цей файл дозволяє налаштувати поведінку запуску, наприклад, чи запускати додаток як упакований (MSIX) чи неупакований.

2.2. Папка "Assets"

Ця папка містить графічні ресурси, які використовуються для ідентифікації додатка в Windows (наприклад, у меню "Пуск" або на екрані завантаження). Усі зображення зазвичай мають різні масштаби (scale-200 означає 200% для високої роздільної здатності).

  • LockScreenLogo.scale-200.png: Іконка для екрану блокування.
  • SplashScreen.scale-200.png: Зображення заставки, яке відображається під час запуску додатка.
  • Square150x150Logo.scale-200.png: Квадратна плитка розміром 150x150 пікселів.
  • Square44x44Logo.scale-200.png: Маленька іконка для панелі завдань або меню "Пуск".
  • StoreLogo.scale-200.png: Логотип для Microsoft Store (якщо додаток публікується).
  • Wide310x150Logo.scale-200.png: Широка плитка для меню "Пуск".

Ці ресурси пов’язані з файлом Package.appxmanifest і автоматично включаються до пакета MSIX під час збирання.

2.3. Файл "Package.appxmanifest"

  • Це XML-файл, який описує метадані додатка для пакування в MSIX. Він визначає:
    • Ідентифікатор додатка (наприклад, "MyWinUIApp_12345").
    • Версію додатка (наприклад, "1.0.0.0").
    • Підтримувані мови (локалізація).
    • Залежності (наприклад, Windows App SDK).
    • Візуальні елементи (посилання на файли з папки "Assets").
    • Можливості (capabilities), такі як доступ до файлів чи мережі.

Приклад фрагменту:

<Package>
  <Identity Name="MyWinUIApp" Publisher="CN=YourName" Version="1.0.0.0" />
  <Properties>
    <DisplayName>My WinUI App</DisplayName>
    <PublisherDisplayName>YourName</PublisherDisplayName>
  </Properties>
  <Resources>
    <Resource Language="en-us" />
  </Resources>
  <Dependencies>
    <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.22621.0" />
  </Dependencies>
</Package>

Цей файл необхідний для упакування додатка, але якщо ви створюєте неупакований додаток, його можна видалити, додавши <WindowsPackageType>None</WindowsPackageType> до .csproj.

2.4. Файл "App.xaml" та "App.xaml.cs"

  • App.xaml: Файл XAML, який визначає глобальні ресурси та стилі для додатка. Наприклад, ви можете визначити кольори чи теми, які застосовуватимуться до всіх вікон. За замовчуванням він мінімальний: 
    <Application
    x:Class="MyWinUIApp.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
</Application>
  • App.xaml.cs: Кодова частина (code-behind) для App.xaml. Це точка входу в додаток, де ініціалізується основне вікно. Приклад: 
    public partial class App : Application
{
    public App()
    {
        this.InitializeComponent();
    }

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        m_window = new MainWindow();
        m_window.Activate();
    }

    private Window m_window;
}
    • Метод OnLaunched викликається під час запуску додатка і створює екземпляр MainWindow.
    • Змінна m_window зберігає посилання на головне вікно, щоб уникнути його збирання сміттям.

2.5. Файл "MainWindow.xaml" та "MainWindow.xaml.cs"

  • MainWindow.xaml: Файл XAML, який визначає інтерфейс користувача для головного вікна. За замовчуванням шаблон включає простий приклад із кнопкою:
    <Window
    x:Class="MyWinUIApp.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <StackPanel Orientation="Horizontal" HorizontalAlignment="Center" VerticalAlignment="Center">
        <Button x:Name="myButton" Click="myButton_Click">Click Me</Button>
    </StackPanel>
</Window>
    • Елемент <Window> є кореневим і представляє вікно додатка.
    • <StackPanel> — контейнер для розміщення елементів інтерфейсу (у цьому випадку кнопки).
    • Атрибут Click="myButton_Click" пов’язує подію натискання кнопки з методом у коді.
  • MainWindow.xaml.cs: Кодова частина для MainWindow.xaml. Тут реалізується логіка взаємодії з інтерфейсом:
    public sealed partial class MainWindow : Window
{
    public MainWindow()
    {
        this.InitializeComponent();
    }

    private void myButton_Click(object sender, RoutedEventArgs e)
    {
        myButton.Content = "Clicked";
    }
}
    • Метод InitializeComponent() ініціалізує компоненти, визначені в XAML.
    • Метод myButton_Click змінює текст кнопки після натискання.

2.6. Файл "MyWinUIApp.csproj"

  • Файл проєкту в форматі SDK-style, який визначає залежності, цільову платформу та налаштування збирання. Приклад: 
    <Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net6.0-windows10.0.17763.0</TargetFramework>
    <Nullable>enable</Nullable>
    <UseWinUI>true</UseWinUI>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.5.0" />
  </ItemGroup>
</Project>
    • <OutputType>WinExe</OutputType>: Вказує, що це настільний додаток Windows.
    • <TargetFramework>: Визначає версію .NET (наприклад, .NET 6) і мінімальну версію Windows (10.0.17763.0 — Windows 10 October 2018 Update).
    • <UseWinUI>true</UseWinUI>: Включає підтримку WinUI 3.
    • <PackageReference>: Посилання на NuGet-пакет Windows App SDK.

2.7. Файл "packages.config" (опціонально)

  • Використовується лише в старих проєктах для управління залежностями через NuGet у форматі packages.config. У сучасних проєктах із SDK-style цей файл зазвичай відсутній, оскільки залежності визначаються в .csproj.

Як це все працює разом?

  1. Точка входу: Під час запуску Windows викликає код у App.xaml.cs (метод OnLaunched), який створює і відображає MainWindow.
  2. UI: MainWindow.xaml визначає візуальну структуру вікна, а MainWindow.xaml.cs обробляє логіку (наприклад, події).
  3. Ресурси: Глобальні стилі та ресурси (якщо є) визначаються в App.xaml.
  4. Пакування: Package.appxmanifest і ресурси з папки Assets використовуються для створення MSIX-пакета, якщо додаток упакований.
  5. Залежності: Windows App SDK (через NuGet) забезпечує WinUI 3 і всі необхідні API для роботи додатка.

Додаткові зауваження

  • Неупакований додаток: Якщо ви хочете створити неупакований додаток, додайте <WindowsPackageType>None</WindowsPackageType> до .csproj і видалите Package.appxmanifest. У такому випадку вам потрібно вручну розгорнути Windows App SDK runtime на цільовому комп’ютері.
  • Розширення: Ви можете додавати нові сторінки (наприклад, Page1.xaml), класи, бібліотеки чи ресурси, розширюючи структуру за потреби.
  • Локалізація: Для підтримки кількох мов додавайте файли ресурсів (.resw) до папки, наприклад, Strings/en-us.

5. Налаштування Git для командної роботи (опціонально)

Якщо ви працюєте в команді або хочете зберігати історію змін, підключіть Git.

Крок 1: Ініціалізація Git

  1. У Visual Studio: Git → Create Git Repository.
  2. Виберіть папку проєкту і натисніть "Create and Push" (якщо у вас є віддалений репозиторій, наприклад, на GitHub).
  3. Або в терміналі: 
    cd C:\Projects\HelloWorldWinUI
git init
git add .
git commit -m "Initial commit"

Крок 2: Ігнорування непотрібного

  • Створіть файл .gitignore у корені проєкту.
  • Додайте: 
    bin/
obj/
*.user
  • Це запобігає додаванню тимчасових файлів у репозиторій.

Чому Git?

Git дозволяє відстежувати зміни, працювати в команді та повертатися до попередніх версій коду, якщо щось пішло не так.

У контексті розробки додатків для Windows, зокрема з використанням WinUI 3 і Windows App SDK, терміни упакований додаток (packaged app) і неупакований додаток (unpackaged app) відносяться до способу, яким додаток компілюється, розгортається та запускається на цільовій системі. Ці два підходи мають різні особливості, переваги та обмеження. Давайте розберемо їх детально.

Упакований додаток (Packaged App)

Упакований додаток — це додаток, який компілюється та розгортається у вигляді пакета MSIX (Microsoft Store Package). MSIX — це сучасний формат пакування для Windows, який замінює старіші формати, такі як MSI чи EXE-інсталятори. Упаковані додатки зазвичай асоціюються з Microsoft Store, але їх також можна розгортати вручну (наприклад, через sideload).

Особливості упакowanego додатка:

  1. Формат MSIX:
    • Додаток упакований у контейнер MSIX, який включає всі необхідні файли (бінарники, ресурси, залежності) в одному архіві.
    • Файл Package.appxmanifest визначає метадані додатка (ідентифікатор, версію, залежності тощо).
  2. Автоматичне розгортання залежностей:
    • Windows App SDK runtime (який включає WinUI 3, DWriteCore тощо) автоматично розгортається разом із додатком. Користувачу не потрібно встановлювати ці компоненти окремо.
  3. Ізоляція:
    • Додаток працює в ізольованому середовищі (sandbox), що підвищує безпеку. Він має обмежений доступ до системи, який регулюється через "capabilities" у маніфесті (наприклад, доступ до файлів чи мережі).
  4. Оновлення та видалення:
    • Оновлення додатка відбувається через механізм MSIX, що дозволяє атомарні оновлення (без залишків старих файлів).
    • Видалення додатка повністю очищає всі його дані з системи.
  5. Інтеграція з Windows:
    • Підтримка функцій, таких як плитки в меню "Пуск", сповіщення, автоматичне оновлення через Microsoft Store (якщо додаток опубліковано).
  6. Розгортання:
    • Через Microsoft Store, корпоративні портали (sideload) або вручну за допомогою .msix чи .appx файлів.

Приклад у WinUI 3:

  • У проєкті є файл Package.appxmanifest, а в .csproj за замовчуванням увімкнено пакування: 
    <Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net6.0-windows10.0.17763.0</TargetFramework>
    <UseWinUI>true</UseWinUI>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.5.0" />
  </ItemGroup>
</Project>
  • Після збирання ви отримуєте файл .msix, який можна встановити через подвійний клік або PowerShell (Add-AppxPackage).

Переваги:

  • Легке розгортання для кінцевих користувачів.
  • Автоматична інтеграція з Windows App SDK.
  • Підтримка Microsoft Store і корпоративного розгортання.
  • Високий рівень безпеки завдяки ізоляції.

Недоліки:

  • Обмеження на доступ до системи (потрібно явно вказувати "capabilities").
  • Складніше налагодження в деяких сценаріях (наприклад, через ізоляцію).
  • Потребує підпису сертифікатом для встановлення поза Microsoft Store.

Неупакований додаток (Unpackaged App)

Неупакований додаток — це додаток, який компілюється як звичайний виконуваний файл (.exe), без використання MSIX-контейнера. Він більше схожий на традиційні настільні додатки, які не залежать від сучасного пакування.

Особливості неупакованого додатка:

  1. Формат EXE:
    • Додаток компілюється як окремий .exe файл разом із супутніми DLL (бібліотеками), але не упаковується в MSIX.
    • Файл Package.appxmanifest відсутній або ігнорується.
  2. Ручне управління залежностями:
    • Windows App SDK runtime не включається автоматично. Його потрібно розгорнути окремо на цільовому комп’ютері (наприклад, через інсталятор або копіювання файлів).
  3. Відсутність ізоляції:
    • Додаток працює як традиційна програма з повним доступом до системи (обмежується лише правами користувача, а не sandbox).
  4. Оновлення та видалення:
    • Оновлення та видалення потрібно реалізовувати вручну (наприклад, через власний інсталятор).
    • Немає вбудованої інтеграції з Microsoft Store чи механізмами MSIX.
  5. Інтеграція з Windows:
    • Деякі функції (наприклад, сповіщення чи плитки) потребують додаткової реалізації через Windows App SDK, але базові можливості WinUI 3 доступні.
  6. Розгортання:
    • Просто копіювання .exe та необхідних файлів на цільовий комп’ютер або використання власного інсталятора.

Приклад у WinUI 3:

  • У .csproj додається <WindowsPackageType>None</WindowsPackageType> для відключення MSIX: 
    <Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net6.0-windows10.0.17763.0</TargetFramework>
    <UseWinUI>true</UseWinUI>
    <WindowsPackageType>None</WindowsPackageType>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.5.0" />
  </ItemGroup>
</Project>
  • Після збирання ви отримуєте папку з .exe та супутніми файлами (наприклад, Microsoft.WindowsAppRuntime.dll).

Переваги:

  • Повний контроль над поведінкою додатка та доступом до системи.
  • Простіше налагодження (немає ізоляції MSIX).
  • Не потрібен підпис сертифікатом.
  • Зручний для розробки чи тестування.

Недоліки:

  • Складніше розгортання для кінцевих користувачів (потрібно вручну встановлювати Windows App SDK).
  • Відсутність автоматичних оновлень чи інтеграції з Microsoft Store.
  • Потенційно менш безпечний через відсутність ізоляції.

Порівняння упакованих і неупакованих додатків

АспектУпакований (Packaged)Неупакований (Unpackaged)
ФорматMSIX-пакетEXE + DLL
ЗалежностіАвтоматично включаютьсяВимагають ручного розгортання
ІзоляціяТак (sandbox)Ні
РозгортанняЧерез MSIX, Store або sideloadКопіювання файлів або інсталятор
ОновленняАвтоматичні через MSIXВручну
Доступ до системиОбмежений (через capabilities)Повний (залежить від прав користувача)
Інтеграція з WindowsГлибока (плитки, сповіщення)Базова (вимагає додаткової роботи)
Підпис сертифікатомОбов’язковий поза StoreНе потрібен

Коли використовувати що?

  • Упакований додаток:
    • Якщо ви плануєте публікацію в Microsoft Store.
    • Якщо потрібна легка дистрибуція для широкої аудиторії.
    • Якщо важлива безпека та ізоляція.
    • Якщо ви хочете використовувати сучасні функції Windows (сповіщення, плитки тощо) без додаткових зусиль.
  • Неупакований додаток:
    • Якщо ви розробляєте додаток для внутрішнього використання чи тестування.
    • Якщо потрібен повний доступ до системи без обмежень MSIX.
    • Якщо ви хочете уникнути складнощів із підписом сертифікатів.
    • Якщо цільові комп’ютери вже мають встановлений Windows App SDK.

Як це виглядає в WinUI 3?

У шаблоні Visual Studio за замовчуванням створюється упакований додаток, але ви можете легко переключитися на неупакований, змінивши .csproj. Наприклад:

  • Упакований: Залишаєте все як є, отримуєте .msix.
  • Неупакований: Додаєте <WindowsPackageType>None</WindowsPackageType>, отримуєте .exe.

Обидва типи підтримують WinUI 3, але упакований додаток є "рекомендованим" підходом від Microsoft для сучасних додатків, тоді як неупакований — це спадщина для сумісності з традиційними сценаріями.

Практична частина: Перевірка

  1. Запустіть ваш "Hello World" ще раз (F5).
  2. Змініть текст у TextBlock на щось своє, наприклад, "Привіт, WinUI!".
  3. Збережіть і перевірте результат.

Питання для роздумів

  1. Що станеться, якщо не встановити "Desktop development with C#" у Visual Studio?
  2. Як ви думаєте, чому Visual Studio автоматично додає MSIX-пакування?

Ресурси

Висновок

Ви успішно налаштували середовище розробки, створили перший проєкт WinUI 3 і навіть додали простий текст. Ми розібрали структуру проєкту і підготувалися до роботи з XAML та C#. На наступній темі ми почнемо створювати справжній інтерфейс користувача. Чудова робота!

Edit this page on GitHub
Table of Contents