MAUI
MAUI
Статья полезна в двух сценариях: миграция команды .NET в мобильную разработку и поддержка единой кодовой базы для Android, iOS и desktop. Для быстрого старта используйте этот материал вместе с .NET MAUI — первая программа и публикацией Android.
Где применяют MAUI
Один проект C#/XAML на Android, iOS, Windows, macOS — если команда уже на .NET, а не на Kotlin/Swift отдельно.
Пошаговый старт: .NET MAUI — первая программа · Публикация Android-приложения.
Официальная документация Microsoft Learn
Актуальный хаб .NET MAUI 10 на русском: Документация .NET MAUI. Ключевые точки входа:
| Раздел | Ссылка |
|---|---|
| Что такое .NET MAUI | what-is-maui |
| Установка | installation |
| Первое приложение | first-app |
| Корпоративные шаблоны | architecture/maui |
| Учебный путь | build-apps-with-dotnet-maui |
MAUI (Multi-platform App UI, .NET MAUI) — кроссплатформенная платформа с открытым исходным кодом для создания нативных мобильных и классических приложений на C# и XAML. По определению Microsoft одна общая кодовая база покрывает Android, iOS, macOS и Windows; также поддерживается Tizen (хаб документации).
Платформа — эволюция Xamarin.Forms: элементы UI перестроены для производительности и расширяемости, сценарии расширены с мобильных до desktop. Опыт Xamarin.Forms переносится, но отличается единым проектом (single project) и мультитаргетингом: максимум логики и разметки — в общем коде, при необходимости — платформенные Platforms/* и API.
Разработка на MAUI предполагает разделение UI и бизнес-логики (часто MVVM). Сборка даёт нативные пакеты под каждую ОС; модель компиляции зависит от платформы (см. ниже).
Архитектура и особенности платформы
Для кого и как устроен стек
По документации Microsoft .NET MAUI рассчитан на разработчиков, которые хотят:
- писать кроссплатформенные приложения на XAML и C# из одной базы в Visual Studio;
- совместно использовать макет UI и дизайн между платформами;
- переиспользовать код, тесты и бизнес-логику.
.NET MAUI объединяет API Android, iOS, macOS и Windows в единый слой ("написал один раз — работает везде") с возможностью вызывать нативные API платформы напрямую, когда нужны специфичные возможности.
Под капотом .NET 6+ предоставляет платформы: .NET for Android, .NET for iOS, Mac Catalyst, WinUI 3 (Windows). Общая BCL абстрагирует ОС; с .NET 11 Preview 4 для Android, iOS и Mac Catalyst по умолчанию используется CoreCLR (раньше это был Mono), на Windows также CoreCLR. Отдельные UI для каждой платформы возможны, но MAUI даёт один UI-слой для мобильных и desktop.
В приложении MAUI код в основном работает с элементами управления MAUI и уровнем API MAUI; этот слой вызывает нативные API платформы. При необходимости приложение обращается к платформенным API напрямую.
Компиляция по платформам
| Платформа | Модель сборки (по Microsoft Learn) |
|---|---|
| Android | C# → IL → JIT в нативную сборку при запуске |
| iOS | C# → AOT, полная ahead-of-time компиляция в ARM |
| macOS | Mac Catalyst (UIKit на desktop + AppKit по необходимости) |
| Windows | WinUI 3 — нативные приложения для Windows |
Для iOS и macOS сборка требует Mac (узел сборки / Pair to Mac в Visual Studio на Windows).
.NET 11: переход MAUI на CoreCLR
Начиная с .NET 11 Preview 4, приложения MAUI на Android, iOS и Mac Catalyst запускаются на CoreCLR по умолчанию. Это убирает историческое разделение "мобильный Mono vs серверный/десктопный CoreCLR" и делает поведение рантайма более предсказуемым между платформами.
Что это меняет на практике:
- один рантайм для мобильных, серверных и desktop-сценариев в экосистеме .NET;
- более единый профиль производительности (JIT/GC/диагностика);
- доступ к инструментам диагностики dotnet-trace и dotnet-counters для мобильных таргетов;
- база для дальнейшего развития NativeAOT в MAUI (особенно для Android).
В Preview 4 отмечаются и риски: у части сложных Android-приложений сообщество фиксирует регрессии по cold start и размеру пакета. Поэтому при миграции важно сравнивать метрики до/после на реальном проекте, а не только на шаблоне.
Как проверить и как откатиться
Для эксперимента используйте TFM net11.0-android, net11.0-ios, net11.0-maccatalyst и прогоните базовый чек-лист:
- время старта (cold/warm start);
- размер артефакта (
.apk/.aab/.ipa); - критические пользовательские сценарии и стабильность.
Если в проекте обнаружилась регрессия, в .NET 11 можно временно вернуть Mono:
<PropertyGroup>
<UseMonoRuntime>true</UseMonoRuntime>
</PropertyGroup>
Этот переключатель подходит для Android, iOS и Mac Catalyst и полезен как временный safety net на период миграции и сервисинга .NET 11.
Возможности платформы
Помимо набора контролов (данные, действия, коллекции, выбор) Microsoft выделяет:
- продвинутый layout engine и типы страниц (вкладки, навигация);
- привязка данных (data binding);
- handlers для кастомизации отрисовки UI;
- кроссплатформенные API устройства (GPS, акселерометр, сеть, буфер обмена, файлы, secure storage, TTS, OAuth в браузере);
- Graphics — рисование на
Canvas; - единый проект (single project) с мультитаргетингом;
- .NET Hot Reload и XAML Hot Reload — правки C#/XAML без полной пересборки, с сохранением навигации и состояния.
Дополнительно в экосистеме:
- .NET MAUI Blazor — UI на HTML/CSS/JS внутри нативного приложения;
- Native Controls — нативный вид и поведение на каждой ОС;
- встроенный DI в
MauiProgram.cs.
Сборка — MSBuild; результат: .apk/.aab, .ipa, пакеты Windows и т.д.
Исходники и образцы: dotnet/maui, dotnet/maui-samples.
Сборка MAUI и сравнение с React Native / Expo
Для команд на .NET release-сборка MAUI обычно проще, чем у React Native или Expo на том же Windows-хосте:
| Аспект | .NET MAUI | React Native / Expo |
|---|---|---|
| Оркестрация | MSBuild + .NET SDK | Metro + Gradle + NDK + autolinking |
| Android-проект | Single project, Platforms/Android | Часто сгенерированный android/ после prebuild |
| Пути в Windows | Короче, без огромного node_modules | Риск лимита 260 символов |
| JDK | Требования .NET/Android workload | Gradle чувствителен к версии (17/21) |
MAUI — один компиляторный конвейер в экосистеме Microsoft — шаблон, workload, Visual Studio, подпись и публикация описаны в одном месте. Нативный C++ подключается точечно; нет цепочки Hermes + CMake на каждый npm-пакет.
Ограничения остаются — для iOS нужен Mac (Pair to Mac), эмулятор Android требует HAXM/Hyper-V, миграция на новый .NET иногда даёт регрессии cold start (см. CoreCLR выше). Зато типичный сценарий "Собрать → APK на телефон" реже упирается в Gradle daemon и длинные пути, чем у JS-стека.
Общая таблица стеков и советы для Windows — Сборка и развёртывание.
Создание первого приложения
Официальное пошаговое руководство: Создание первого приложения .NET MAUI (Visual Studio 2022 на Windows или Visual Studio Code на Windows/macOS/Linux). Ниже — сжатая выжимка; для Android в Learn используется эмулятор и шаблон со счётчиком "Щелкните меня".
Шаг 1. Установка среды разработки
Требования по Microsoft:
- Visual Studio 2022 17.12+ с рабочей нагрузкой "Разработка приложений .NET MAUI" (в англ. установщике — .NET Multi-platform App UI development), см. Установка;
- либо VS Code + .NET SDK и workload MAUI:
dotnet workload install maui
В установщике Visual Studio отметьте:
- разработку .NET MAUI;
- инструменты Android (SDK, эмулятор);
- iOS/macOS (для сборки под Apple нужен Mac как узел сборки);
- актуальную среду выполнения .NET.
Важно: разработка под iOS на Windows требует подключения к Mac. Без Mac разумно начать с Android или Windows. Для эмулятора Android включите аппаратное ускорение.
Шаг 2. Создание проекта
В Visual Studio: Создать проект → фильтр MAUI → шаблон Приложение .NET MAUI → имя и расположение → на шаге Дополнительные сведения выберите целевую версию .NET → Создать. Дождитесь восстановления NuGet.
Через CLI:
dotnet new maui -n MyFirstApp
cd MyFirstApp
Шаг 3. Структура проекта
Проект содержит следующие ключевые элементы:
- MauiProgram.cs: Точка входа в приложение, где регистрируются зависимости и инициализируется среда.
- App.xaml / App.xaml.cs: Описание корневого элемента приложения и логика запуска.
- MainPage.xaml / MainPage.xaml.cs: Главный экран приложения, содержащий разметку и код.
- Resources — Папка с ресурсами, такими как изображения, шрифты и стили.
- Platforms — Папки для специфичных настроек каждой платформы (Android, iOS, Windows, MacCatalyst).
Шаг 4. Настройка целевых платформ
Откройте файл MauiProgram.cs. В методе CreateMauiApp можно настроить поведение приложения. Для базового запуска достаточно стандартной конфигурации.
Проверьте файл *.csproj (например, MyFirstApp.csproj). В шаблоне MAUI 10 типичны целевые фреймворки вроде:
<TargetFrameworks>net10.0-android;net10.0-ios;net10.0-maccatalyst;net10.0-windows10.0.19041.0</TargetFrameworks>
Конкретные TFM зависят от установленного SDK; см. поддерживаемые платформы.
Шаг 5. Запуск приложения
На панели инструментов в Целевой объект отладки выберите, например, Android Emulator → при первом запуске примите лицензии SDK, установите недостающие компоненты, создайте виртуальное устройство в Диспетчере устройств Android → Пуск. В работающем приложении нажмите "Щелкните меня" — счётчик нажатий должен расти (как в учебнике Microsoft).
Для Windows выберите Компьютер Windows в целевом объекте. Для iOS — симулятор после Pair to Mac; на Windows доступен удалённый симулятор iOS.
На реальном Android — USB, режим разработчика, отладка по USB — устройство в списке целей вместо эмулятора.
Если сборка падает: устранение неполадок MAUI, для эмулятора — Android emulator troubleshooting.
Следующие шаги по Learn: учебник приложение "Заметки" и учебный путь build-apps-with-dotnet-maui (в этой статье — отдельный раздел ниже).
Шаг 6. Модификация интерфейса
Откройте файл MainPage.xaml. Найдите элемент <Label Text="{Binding WelcomeText}" />. Измените текст на свое приветствие:
<Label Text="Привет, мир! Это мое первое MAUI приложение"
HorizontalOptions="Center"
VerticalOptions="Center"
FontSize="24" />
Сохраните изменения и запустите приложение снова. Если включена функция Hot Reload, изменение отобразится мгновенно без перезапуска.
Шаг 7. Сборка и публикация
Для создания установочного пакета перейдите в меню Сборка -> Собрать решение. После успешной сборки откройте папку bin/Release/net8.0-android (для Android). Там будет находиться файл .aab или .apk. Этот файл можно передать на устройство для установки.
Для публикации в магазины: в Visual Studio — Подпись пакета в свойствах проекта, затем Сборка → Опубликовать. Из CLI (после настройки подписи, подставьте свой TFM):
dotnet publish -f net10.0-android -c Release
Подпись release, RuStore, Google Play и раздача APK с сайта: Публикация Android-приложения.
Работа с ресурсами и стилями
Приложение MAUI использует систему ресурсов для хранения изображений, шрифтов и цветов. Файлы помещаются в папку Resources и классифицируются по типу.
Изображения размещаются в папке raw или img. Шрифты добавляются в папку fonts. Цвета определяются в файле Colors.xaml.
Пример подключения изображения в коде:
Image image = new Image
{
Source = ImageSource.FromFile("icon.png")
};
Стилизация осуществляется через XAML или программно. Использование ресурсов позволяет поддерживать единый дизайн для всех платформ.
Доступ к нативным функциям устройства
Кроссплатформенные API устройства встроены в .NET MAUI (преемник Xamarin.Essentials): датчики, сеть, геолокация, файлы, secure storage, буфер обмена и др. — см. Essentials / device features.
Пример получения геолокации:
var location = await Geolocation.GetLocationAsync(Accuracy.Default);
Console.WriteLine($"Широта: {location.Latitude}, Долгота: {location.Longitude}");
Пример записи файла:
var filePath = Path.Combine(FileSystem.AppDataDirectory, "data.txt");
await File.WriteAllTextAsync(filePath, "Пример данных");
Эти вызовы работают одинаково на всех поддерживаемых платформах. Платформа автоматически выбирает нужный метод реализации для текущей ОС.
Отладка и тестирование
Инструменты отладки в MAUI аналогичны инструментам для обычных .NET приложений. Используются точки останова, просмотр переменных и стек вызовов.
Для отладки на эмуляторе необходимо включить режим отладки в настройках эмулятора. Для реальных устройств требуется активация режима разработчика и разрешение на отладку через USB.
Автоматическое тестирование выполняется с помощью фреймворка xUnit или NUnit. Тесты пишутся в отдельном проекте и выполняются через командную строку или в среде Visual Studio.
Особенности развертывания
Развертывание приложения требует соблюдения требований магазинов приложений. Для Google Play необходим формат AAB. Для Apple App Store — формат IPA с подписанным сертификатом.
Процесс подготовки включает:
- Генерацию сертификата подписи;
- Настройку манифеста приложения;
- Проверку прав доступа (Permissions);
- Прохождение модерации.
Visual Studio предоставляет мастера для генерации необходимых файлов и подписи.
Единый проект (Single Project)
С .NET MAUI один SDK-style проект таргетирует Android, iOS, macOS и Windows через мультитаргетинг:
- общие ресурсы (изображения, шрифты) в
Resources; - один манифест приложения (имя, идентификатор, версия);
- единая точка входа (
MauiProgram.cs); - при необходимости — код в
Platforms/Android,Platforms/iOSи т.д.
Подробнее: один проект .NET MAUI в документации Microsoft.
Корпоративная архитектура
Для зрелых приложений Microsoft публикует электронную книгу Шаблоны корпоративных приложений с помощью .NET MAUI (скачивание: aka.ms/maui-ebook). Книга основана на руководстве по Xamarin.Forms и описывает:
- MVVM, внедрение зависимостей, навигацию, конфигурацию;
- слабое связывание и типичные корпоративные задачи (меняющиеся требования, несколько платформ, интеграции);
- эталонное приложение eShop (репозиторий dotnet/eshop).
Книга не заменяет базовый туториал: для первого приложения — first-app; для паттернов — архитектурное руководство после знакомства с платформой.
Учебный путь Microsoft Learn — сборка приложений с .NET MAUI
Официальный путь (~6 ч 40 мин, 8 модулей): Сборка мобильных и классических приложений с .NET MAUI.
Предварительные требования: Visual Studio 2022 с workload MAUI, опыт C# и .NET.
| Модуль | Тема | Длительность |
|---|---|---|
| build-mobile-and-desktop-apps | Кроссплатформенное приложение, архитектура MAUI, первый проект, контролы, переводчик номеров | ~33 мин |
| create-user-interface-xaml | UI на XAML | ~54 мин |
| customize-xaml-pages-layout | StackLayout, Grid, адаптивный layout | ~1 ч |
| separate-ui-and-logic-with-data-binding | Привязка данных, конвертеры | ~47 мин |
| design-mvvm-viewmodel | MVVM и ViewModel | ~46 мин |
| use-shared-resources | Общие ресурсы и стили XAML | ~46 мин |
| create-multi-page-apps | Вкладки, flyout, навигация | ~49 мин |
| store-local-data | Локальные данные, SQLite | ~1 ч 4 мин |
Путь покрывает основы MAUI, XAML, layout, binding, MVVM, многостраничные приложения и локальное хранилище; для REST и продвинутых тем — документация хаба и корпоративная книга.
Карта документации Microsoft Learn
Структура главной страницы .NET MAUI — ориентир для углубления.
Старт и обзор
| Тема | Ссылка |
|---|---|
| Что такое MAUI | what-is-maui |
| Поддерживаемые платформы | supported-platforms |
| Установка | installation |
| Первое приложение | first-app |
| Что нового | whats-new |
| Миграция с Xamarin | migration |
UI, данные, жизненный цикл
| Тема | Ссылка |
|---|---|
| XAML | get-started with XAML |
| CollectionView | collectionview |
| Жизненный цикл приложения | app-lifecycle |
| Интеграция с устройством | platform-integration |
| Горячая перезагрузка | hot-reload |
Архитектура, обучение, примеры
| Тема | Ссылка |
|---|---|
| Корпоративные шаблоны (eBook) | architecture/maui |
| Учебный путь Learn | build-apps-with-dotnet-maui |
| Примеры кода | samples — dotnet-maui |
| Устранение неполадок | troubleshooting |
Частые ошибки
| Симптом | Причина |
|---|---|
| Android SDK not found | Не установлен workload ".NET MAUI" в VS |
InitializeComponent | Ошибка в XAML / неверный x:Class |
| iOS только на Mac | Сборка под iPhone требует macOS + Xcode |
| Медленный cold start | Тяжёлый MainPage — отложите инициализацию |
Что попробовать
- Первая программа MAUI — счётчик на одной странице.
CollectionViewсо списком строк изObservableCollection.- Публикация Android после
dotnet publish.