Поделиться через

Обновление Xamarin.Forms приложения вручную до одного приложения .NET MAUI

Чтобы перенести приложение Xamarin.Forms на единый проект приложения с многофункциональным интерфейсом .NET Multi-platform App UI (.NET MAUI), необходимо:

  • Обновите приложение Xamarin.Forms, чтобы использовать Xamarin.Forms 5.
  • Обновите зависимости приложения до последних версий.
  • Убедитесь, что приложение все еще работает.
  • Создайте приложение .NET MAUI.
  • Скопируйте код и конфигурацию из Xamarin.Forms приложения в приложение .NET MAUI.
  • Скопируйте ресурсы из Xamarin.Forms приложения в приложение .NET MAUI.
  • Обновить пространства имен
  • Рассмотрите любые изменения API.
  • Обновите или замените несовместимые зависимости на версии .NET 8.
  • Компилируйте и тестируйте ваше приложение.

Чтобы упростить процесс обновления, необходимо создать новое приложение MAUI .NET с тем же именем, что и приложение Xamarin.Forms , а затем скопировать код, конфигурацию и ресурсы. Вот подход, изложенный ниже.

Обновите приложение Xamarin.Forms

Перед обновлением вашего Xamarin.Forms приложения до .NET MAUI необходимо сначала обновить Xamarin.Forms приложение до Xamarin.Forms 5 и убедиться, что оно по-прежнему работает правильно. Кроме того, вам следует обновить зависимости, которые использует ваше приложение, до последних версий.

Это поможет упростить остальную часть процесса миграции, так как минимизирует различия между API Xamarin.Forms и .NET MAUI, а также обеспечит использование совместимых с .NET версий ваших зависимостей, если они существуют.

Создание приложения .NET MAUI

В Visual Studio создайте новое приложение MAUI .NET, используя то же имя, что и приложение Xamarin.Forms :

Снимок экрана: создание приложения .NET MAUI в Visual Studio.

Открытие файла проекта подтвердит наличие проекта в стиле пакета SDK для .NET.

Копирование кода в приложение .NET MAUI

Весь кроссплатформенный код из Xamarin.Forms проекта библиотеки должен быть скопирован в проект приложения .NET MAUI в идентичных именованных папках и файлах.

Пользовательские средства визуализации могут быть повторно использованы в приложении .NET MAUI или перенесены в обработчик .NET MAUI. Для получения дополнительной информации см. Повторное использование пользовательских рендереров в .NET MAUI и Перенос Xamarin.Forms пользовательского рендерера в обработчик .NET MAUI.

Эффекты могут быть повторно использованы в приложении .NET MAUI. Для получения дополнительной информации смотрите Reuse effects.

Замечание

Вы можете быстро обновить свои Xamarin.Forms пространства имен до Microsoft.Maui, используя Быстрые действия в Visual Studio, при условии, что у вас установлен Upgrade Assistant.

Код для конкретной платформы

Проект приложения .NET MAUI содержит папку "Платформы" с каждой дочерней папкой, представляющей платформу, предназначенную для .NET MAUI:

Снимок экрана папок платформы.

Папки для каждой платформы содержат ресурсы для конкретной платформы и код, который запускает приложение на каждой платформе:

Снимок экрана кода для конкретной платформы.

Код и их содержащие папки из Xamarin.Forms головных проектов должны быть скопированы в следующие папки:

  • Код из Xamarin.Forms головного проекта Android должен быть скопирован в папку Platform\Android проекта приложения .NET MAUI. Кроме того, скопируйте любой пользовательский код из ваших Xamarin.FormsMainActivity и MainApplication классов в те же классы в проекте приложения .NET MAUI.

  • Код из Xamarin.Forms головного проекта iOS должен быть скопирован в папку Platform\iOS проекта приложения .NET MAUI. Кроме того, скопируйте любой пользовательский код из Xamarin.FormsAppDelegate класса в тот же класс в проекте приложения .NET MAUI.

    Замечание

    Список критических изменений в .NET для iOS см. в разделе "Критические изменения" в .NET для iOS.

  • Код из Xamarin.Forms головного проекта UWP должен быть скопирован в папку Platform\Windows проекта приложения .NET MAUI. Кроме того, скопируйте любой пользовательский код из Xamarin.FormsApp класса в тот же класс в проекте приложения .NET MAUI.

Во время сборки система сборки включает только код из каждой папки для этой конкретной платформы. Например, при сборке для Android файлы в папке Platform\Android будут встроены в пакет приложения, но файлы в других папках платформ не будут. Этот подход использует мультиплатформенный подход для нацеливания на несколько платформ из одного проекта. Приложения .NET MAUI также могут быть ориентированы на несколько платформ в соответствии с вашими критериями имен файлов и папок. Это позволяет структурировать проект приложения .NET MAUI, чтобы не помещать код платформы в дочерние папки папки "Платформы ". Для получения дополнительной информации см. в разделе «Настройка многоцелевого назначения».

Копирование конфигурации в приложение .NET MAUI

Каждая платформа использует собственный файл манифеста приложения для указания таких сведений, как название приложения, идентификатор, версия и многое другое. Один проект .NET MAUI позволяет указать эти общие данные приложения в одном расположении в файле проекта.

Чтобы указать данные манифеста общего приложения для проекта, откройте контекстное меню проекта в обозревателе решений и выберите пункт "Свойства". Название, идентификатор и версия приложения затем могут быть указаны в общем файле MAUI> General:

Снимок экрана манифеста приложения .NET MAUI.

Во время сборки данные манифеста общего приложения объединяются с данными, зависящими от платформы, в файле манифеста собственного приложения, чтобы создать файл манифеста для пакета приложения. Дополнительные сведения см. в разделе "Конфигурация проекта" в .NET MAUI — общий доступ к MAUI.

Оставшиеся данные из Xamarin.Forms манифестов приложения должны быть скопированы в манифест приложения .NET MAUI:

  • В Android скопируйте все дополнительные данные из файлаAndroidManifest.xml в головном Xamarin.Forms проекте Android в файл Платформы\Android\AndroidManifest.xml в проекте приложения .NET MAUI.
  • В iOS скопируйте дополнительные данные из файла Info.plist в головном Xamarin.Forms проекте iOS в файл Platform\iOS\Info.plist в проекте приложения .NET MAUI. Кроме того, скопируйте файл Entitlements.plist в головном проекте iOS в Xamarin.Forms папку Platform\iOS в проекте приложения .NET MAUI.
  • В Windows скопируйте дополнительные данные из файла Package.appxmanifest в Xamarin.Forms головном проекте UWP в файл Platform\Windows\Package.appxmanifest в проекте приложения .NET MAUI.

Копирование ресурсов в приложение .NET MAUI

Один проект .NET MAUI позволяет хранить файлы ресурсов в одном расположении при использовании на каждой платформе. К ним относятся шрифты, изображения, значок приложения, экран-заставка, необработанные ресурсы и CSS-файлы для стилизации приложений MAUI .NET.

Файлы ресурсов обычно помещаются в папку "Ресурсы " проекта приложения .NET MAUI или дочерние папки папки "Ресурсы " и должны иметь правильный набор действий сборки. В следующей таблице показаны действия сборки для каждого типа файла ресурсов:

Ресурс Действие сборки
Значок приложения MauiIcon
Шрифты MauiFont
Изображения MauiImage
Экран-заставка MauiSplashScreen
Необработанные ресурсы MauiAsset
CSS-файлы MauiCss

Замечание

ФАЙЛЫ XAML также хранятся в проекте приложения .NET MAUI и автоматически назначаются действию сборки MauiXaml . Однако в папку "Ресурсы " проекта приложения обычно помещаются только словари ресурсов XAML.

На следующем снимка экрана показана типичная папка Resources, содержащая дочерние папки для каждого типа ресурса:

Снимок экрана: ресурсы изображений и шрифтов.

Действие сборки для файла ресурсов будет правильно задано, если ресурс был добавлен в правильную дочернюю папку Resources .

Это важно

Ресурсы, зависящие от платформы, будут иметь приоритет над общими ресурсами. Например, если на платформах\Android\Resources\drawable-xhdpi\logo.pngразмещено изображение, определенное для Android, и вы также предоставляете общий образ Resources\Images\logo.svg , масштабируемое векторное изображение (SVG) будет использоваться для создания необходимых образов Android, за исключением образа XHDPI, который уже существует в качестве образа для конкретной платформы.

Значки приложения

Значок Xamarin.Forms приложения следует добавить в проект приложения .NET MAUI, перетащив изображение в папку проекта Resources\AppIcon, где действие сборки автоматически устанавливается на MauiIcon. Во время сборки значок приложения изменяется на правильный размер целевой платформы и устройства. Значки приложений изменяются до нескольких разрешений, так как они используют несколько вариантов использования, включая использование для представления приложения на устройстве и в магазине приложений.

Дополнительные сведения см. в разделе "Добавление значка приложения" в проект приложения .NET MAUI.

Экран-заставка

Если у Xamarin.Forms вашего приложения есть экран-заставка , его следует добавить в проект приложения .NET MAUI, перетащив изображение в папку Resources\Splash проекта, где его действие сборки автоматически будет установлено на MauiSplashScreen. Во время сборки изображение экрана-заставки изменяется до правильного размера для целевой платформы и устройства.

Для получения дополнительной информации см. раздел "Добавление экрана-заставки в проект приложения .NET MAUI".

Изображения

Устройства имеют диапазон размеров экрана и плотностей экрана, а каждая платформа имеет функциональные возможности для отображения изображений, зависящих от плотности. Как правило, изображения, зависящие от плотности, помещаются в основные проекты и применяют соглашение об именовании для конкретной платформы. Существует два подхода, которые можно использовать для переноса этих образов в .NET MAUI.

Рекомендуется скопировать версию каждого изображения с наивысшим разрешением из Xamarin.Forms вашего решения в проект приложения .NET MAUI, перетащив его в папку Resources\Images проекта, где его действие при сборке автоматически будет установлено на MauiImage. Кроме того, необходимо задать BaseSize атрибут каждого растрового изображения, чтобы обеспечить изменение размера. Это устраняет необходимость в наличии нескольких версий каждого образа на каждой платформе. Во время сборки все изображения будут изменены в несколько изображений с различной плотностью, которые будут соответствовать требованиям платформы. Дополнительные сведения см. в разделе "Добавление изображений в проект приложения .NET MAUI".

Кроме того, вы можете скопировать изображения, зависящие от плотности, из Xamarin.Forms решения в идентично названные папки в папке Platforms\{Platform} проекта приложения .NET MAUI и задать их действия сборки такими же, как используются в Xamarin.Forms решении. В следующей таблице перечислены примеры расположений изображений для решения Xamarin.Forms, и их эквиваленты в проекте приложения .NET MAUI.

Xamarin.Forms расположение изображения Расположение образа .NET MAUI Действие сборки образа платформы .NET MAUI
{MyApp.Android}\Resources\drawable-xhdpi\image.png Платформы\Android\Resources\drawable-xhdpi\image.png AndroidResource
\image.jpg{MyApp.iOS} *Платформы\iOS\Resources\image.jpg BundleResource
{MyApp.UWP}\Assets\Images\image.gif *Платформы\Windows\Assets\Images\image.gif Содержимое

При условии, что вы приняли то же соглашение об именовании изображений, что и в решении Xamarin.Forms , соответствующий образ будет выбран во время выполнения на основе возможностей устройства. Недостатком этого подхода является то, что на каждой платформе по-прежнему существует несколько версий каждого образа.

Шрифты

Любые шрифты из Xamarin.Forms решения можно добавить в решение .NET MAUI, перетащив их в папку Resources\Fonts проекта приложения .NET MAUI, где их действие сборки автоматически будет установлено на MauiFont.

Дополнительные сведения см. в разделе "Шрифты".

CSS-файлы

Все CSS-файлы из Xamarin.Forms решения можно добавить в решение .NET MAUI, перетащив их в папку с одинаковым именем и задав действие сборки MauiCss в окне свойств .

Дополнительные сведения об использовании CSS-файлов в приложении .NET MAUI см. в статье " Стили приложений с помощью каскадных таблиц стилей".

Необработанные ресурсы

Все файлы необработанных ресурсов, такие как HTML, JSON и видео, должны быть скопированы из вашего решения в проект приложения .NET MAUI путем перетаскивания в папку Xamarin.Forms вашего проекта, где действие сборки автоматически будет установлено на MauiAsset.

Локализованные ресурсы

В приложении .NET MAUI строки локализованы с помощью того же подхода, что и в Xamarin.Forms приложении. Поэтому файлы ресурсов .NET (RESX) должны быть скопированы из Xamarin.Forms решения в папку с одинаковым именем в решении .NET MAUI. Затем необходимо указать нейтральный язык приложения .NET MAUI. Дополнительные сведения см. в разделе "Указание нейтрального языка приложения".

Замечание

Файлы ресурсов .NET не должны размещаться в папке ресурсов проекта приложения .NET MAUI.

В приложении .NET MAUI изображения локализованы с помощью того же подхода, что и в Xamarin.Forms приложении. Таким образом, ваши локализованные изображения и папки, в которых они находятся, должны быть скопированы из вашего Xamarin.Forms решения в проект приложения .NET MAUI.

  • В Android корневая папка в проекте приложения .NET MAUI для локализованных образов — Platform\Android\Resources.
  • В iOS корневая папка в проекте приложения .NET MAUI для локализованных образов — Platform\iOS\Resources.
  • В Windows корневая папка в проекте приложения .NET MAUI для локализованных образов — Platform\Windows\Assets\Images.

Локализованные образы должны иметь свои действия сборки, заданные для действий сборки, используемых в Xamarin.Forms решении. Дополнительные сведения см. в разделе "Локализация изображений".

В приложении .NET MAUI имена приложений локализованы с помощью того же подхода, что и в Xamarin.Forms приложении:

  • В Android локализованное имя приложения можно хранить с помощью соглашения об именовании на основе папок в папке Platform\Android\Resources . Папки и файлы локализации приложения должны быть скопированы в эту папку из Xamarin.Forms решения.
  • В iOS локализованное имя приложения сохраняется с помощью соглашения об именовании на основе папок в папке Platform\iOS\Resources . Папки и файлы локализации приложения должны быть скопированы в эту папку из Xamarin.Forms решения.
  • В Windows локализованное имя приложения хранится в манифесте пакета приложения.

Дополнительные сведения см. в разделе "Локализация имени приложения". Дополнительные сведения о локализации приложений .NET MAUI см. в разделе "Локализация".

Изменения пространства имен

В процессе перехода из Xamarin.Forms в .NET MAUI пространства имён изменились, и функции Xamarin.Essentials теперь являются частью .NET MAUI. Чтобы обновить пространства имен, выполните поиск и замену для следующих пространств имен:

пространство имен Xamarin.Forms Пространства имен .NET MAUI
Xamarin.Forms Microsoft.Maui и Microsoft.Maui.Controls.
Xamarin.Forms.DualScreen Microsoft.Maui.Controls.Foldable
Xamarin.Forms.Maps Microsoft.Maui.Controls.Maps и Microsoft.Maui.Maps.
Xamarin.Forms.PlatformConfiguration Microsoft.Maui.Controls.PlatformConfiguration
Xamarin.Forms.PlatformConfiguration.AndroidSpecific Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific
Xamarin.Forms.PlatformConfiguration.AndroidSpecific.AppCompat Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific.AppCompat
Xamarin.Forms.PlatformConfiguration.TizenSpecific Microsoft.Maui.Controls.PlatformConfiguration.TizenSpecific
Xamarin.Forms.PlatformConfiguration.WindowsSpecific Microsoft.Maui.Controls.PlatformConfiguration.WindowsSpecific
Xamarin.Forms.PlatformConfiguration.iOSSpecific Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific
Xamarin.Forms.Shapes Microsoft.Maui.Controls.Shapes
Xamarin.Forms.StyleSheets Microsoft.Maui.Controls.StyleSheets
Xamarin.Forms.Xaml Microsoft.Maui.Controls.Xaml

Проекты .NET MAUI используют неявные директивы global using. Эта функция позволяет вам удалять директивы using для пространства имен Xamarin.Essentials, без необходимости замены их эквивалентными пространствами имен .NET MAUI.

Кроме того, начальный пространство имен XAML изменился с http://xamarin.com/schemas/2014/forms в Xamarin.Forms на http://schemas.microsoft.com/dotnet/2021/maui в .NET MAUI. Поэтому вам следует заменить все вхождения xmlns="http://xamarin.com/schemas/2014/forms" на xmlns="http://schemas.microsoft.com/dotnet/2021/maui".

Замечание

Вы можете быстро обновить свои Xamarin.Forms пространства имен до Microsoft.Maui, используя Быстрые действия в Visual Studio, при условии, что у вас установлен Upgrade Assistant.

Изменения API

Некоторые API изменились при переходе с Xamarin.Forms на .NET MAUI. Существует несколько причин для этого, включая удаление дублирующегося функционала, вызванного тем, что Xamarin.Essentials стал частью .NET MAUI, и обеспечение того, чтобы API соответствовали руководствам по именованию .NET. В следующих разделах рассматриваются эти изменения.

Изменения цвета

В Xamarin.Forms структура Xamarin.Forms.Color позволяет создавать объекты Color с использованием значений double, а также предоставляет именованные цвета, такие как Xamarin.Forms.Color.AliceBlue. В .NET MAUI эта функциональность была разделена на класс Microsoft.Maui.Graphics.Color и класс Microsoft.Maui.Graphics.Colors.

Класс Microsoft.Maui.Graphics.Color, в пространстве имен Microsoft.Maui.Graphics, позволяет создавать объекты Color используя значения float, значения byte, и значения int. Класс Microsoft.Maui.Graphics.Colors, который также находится в пространстве имен Microsoft.Maui.Graphics, в значительной степени предоставляет те же именованные цвета. Например, используйте Colors.AliceBlue, чтобы указать цвет AliceBlue.

Следующая таблица показывает изменения API между структурой Xamarin.Forms.Color и классом Microsoft.Maui.Graphics.Color.

Xamarin.Forms API-интерфейс API для .NET MAUI Комментарий
Xamarin.Forms.Color.R Microsoft.Maui.Graphics.Color.Red
Xamarin.Forms.Color.G Microsoft.Maui.Graphics.Color.Green
Xamarin.Forms.Color.B Microsoft.Maui.Graphics.Color.Blue
Xamarin.Forms.Color.A Microsoft.Maui.Graphics.Color.Alpha
Xamarin.Forms.Color.Hue Microsoft.Maui.Graphics.Color.GetHue Свойство Xamarin.Forms было заменено методом в .NET MAUI.
Xamarin.Forms.Color.Saturation Microsoft.Maui.Graphics.Color.GetSaturation Свойство Xamarin.Forms было заменено методом в .NET MAUI.
Xamarin.Forms.Color.Luminosity Microsoft.Maui.Graphics.Color.GetLuminosity Свойство Xamarin.Forms было заменено методом в .NET MAUI.
Xamarin.Forms.Color.Default Нет эквивалента .NET MAUI. Вместо этого объекты Microsoft.Maui.Graphics.Color по умолчанию являются null.
Xamarin.Forms.Color.Accent Нет эквивалента .NET MAUI.
Xamarin.Forms.Color.FromHex Microsoft.Maui.Graphics.Color.FromArgb Microsoft.Maui.Graphics.Color.FromHex устарел и будет удален в будущей версии.

Кроме того, все числовые значения в Microsoft.Maui.Graphics.Color являются float, а не double, как используется в Xamarin.Forms.Color.

Замечание

В отличие от Xamarin.Forms, Microsoft.Maui.Graphics.Color не имеет неявного преобразования в System.Drawing.Color.

Изменения в расположении

Следующая таблица перечисляет API для компоновки, которые были удалены при переходе с Xamarin.Forms на .NET MAUI:

Xamarin.Forms API API .NET MAUI Комментарии
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add Перегрузка Add , принимающая три аргумента, отсутствует в .NET MAUI.
Xamarin.Forms.Grid.IGridList<T>.AddHorizontal Нет эквивалента .NET MAUI.
Xamarin.Forms.Grid.IGridList<T>.AddVertical Нет эквивалента .NET MAUI.
Xamarin.Forms.RelativeLayout Microsoft.Maui.Controls.Compatibility.RelativeLayout В .NET MAUI RelativeLayout существует только как элемент совместимости для пользователей, переходящих с Xamarin.Forms. Используйте Grid вместо этого или добавьте xmlns для пространства имен совместимости.

Кроме того, добавление подчиненных элементов в компоновку с помощью кода в Xamarin.Forms выполняется путем добавления этих элементов в коллекцию Children компоновки.

Grid grid = new Grid();
grid.Children.Add(new Label { Text = "Hello world" });

В .NET MAUI коллекция Children предназначена для внутреннего использования .NET MAUI и не должна изменяться напрямую. Следовательно, в коде дочерние элементы должны быть добавлены непосредственно в макет.

Grid grid = new Grid();
grid.Add(new Label { Text = "Hello world" });

Это важно

Любые методы расширения макета, такие как Add, вызываются на самом макете, а не на коллекции макетов GridExtensions.Add.

Вы можете заметить, что при запуске обновленного приложения .NET MAUI поведение макета стало другим. Чтобы получить дополнительную информацию, см. изменения в поведении макета из Xamarin.Forms.

Изменения настраиваемого макета

Процесс создания пользовательского макета в Xamarin.Forms включает создание класса, который наследует от Layout<View>, с переопределением методов VisualElement.OnMeasure и Layout.LayoutChildren. Для получения дополнительной информации см. Создание пользовательского макета в Xamarin.Forms.

В .NET MAUI классы компоновки наследуются от абстрактного класса Layout. Этот класс передает управление макетом и измерениями между платформами классу менеджера макета. Каждый класс менеджера компоновки реализует интерфейс ILayoutManager, который определяет, что должны быть предусмотрены реализации Measure и ArrangeChildren.

  • Реализация Measure вызывает IView.Measure для каждого представления в макете и возвращает общий размер макета с учетом ограничений.
  • Реализация ArrangeChildren определяет, где каждое представление должно быть размещено в пределах границ макета, и вызывает Arrange для каждого представления с его соответствующими границами. Возвращаемое значение — это фактический размер макета.

Для получения дополнительной информации смотрите Пользовательские макеты.

Изменения устройства

Xamarin.Forms имеет класс Xamarin.Forms.Device, который помогает взаимодействовать с устройством и платформой, на которой работает приложение. Эквивалентный класс в .NET MAUI, Microsoft.Maui.Controls.Device, устарел, и его функциональность заменена несколькими типами.

В следующей таблице показаны замены MAUI .NET для функциональных возможностей Xamarin.Forms.Device класса:

Xamarin.Forms API API .NET MAUI Комментарии
Xamarin.Forms.Device.Android Microsoft.Maui.Devices.DevicePlatform.Android
Xamarin.Forms.Device.iOS Microsoft.Maui.Devices.DevicePlatform.iOS
Xamarin.Forms.Device.GTK Нет эквивалента .NET MAUI.
Xamarin.Forms.Device.macOS Нет эквивалента .NET MAUI. Вместо этого используйте Microsoft.Maui.Devices.DevicePlatform.MacCatalyst.
Xamarin.Forms.Device.Tizen Microsoft.Maui.Devices.DevicePlatform.Tizen
Xamarin.Forms.Device.UWP Microsoft.Maui.Devices.DevicePlatform.WinUI
Xamarin.Forms.Device.WPF Нет эквивалента .NET MAUI.
Xamarin.Forms.Device.Flags Нет эквивалента .NET MAUI.
Xamarin.Forms.Device.FlowDirection Microsoft.Maui.ApplicationModel.AppInfo.RequestedLayoutDirection
Xamarin.Forms.Device.Idiom Microsoft.Maui.Devices.DeviceInfo.Idiom
Xamarin.Forms.Device.IsInvokeRequired Microsoft.Maui.Dispatching.Dispatcher.IsDispatchRequired
Xamarin.Forms.Device.OS Microsoft.Maui.Devices.DeviceInfo.Platform
Xamarin.Forms.Device.RuntimePlatform Microsoft.Maui.Devices.DeviceInfo.Platform
Xamarin.Forms.Device.BeginInvokeOnMainThread Microsoft.Maui.ApplicationModel.MainThread.BeginInvokeOnMainThread
Xamarin.Forms.Device.GetMainThreadSynchronizationContextAsync Microsoft.Maui.ApplicationModel.MainThread.GetMainThreadSynchronizationContextAsync
Xamarin.Forms.Device.GetNamedColor Нет эквивалента .NET MAUI.
Xamarin.Forms.Device.GetNamedSize Нет эквивалента .NET MAUI.
Xamarin.Forms.Device.Invalidate Microsoft.Maui.Controls.VisualElement.InvalidateMeasure
Xamarin.Forms.Device.InvokeOnMainThreadAsync Microsoft.Maui.ApplicationModel.MainThread.InvokeOnMainThreadAsync
Xamarin.Forms.Device.OnPlatform Microsoft.Maui.Devices.DeviceInfo.Platform
Xamarin.Forms.Device.OpenUri Microsoft.Maui.ApplicationModel.Launcher.OpenAsync
Xamarin.Forms.Device.SetFlags Нет эквивалента .NET MAUI.
Xamarin.Forms.Device.SetFlowDirection Microsoft.Maui.Controls.Window.FlowDirection
Xamarin.Forms.Device.StartTimer Microsoft.Maui.Dispatching.DispatcherExtensions.StartTimer или Microsoft.Maui.Dispatching.Dispatcher.DispatchDelayed

Изменения карты

В Xamarin.Forms управление Map и связанные типы находятся в пространстве имен Xamarin.Forms.Maps. В .NET MAUI эта функциональность перемещена в пространства имен Microsoft.Maui.Controls.Maps и Microsoft.Maui.Maps. Некоторые свойства были переименованы, а некоторые типы были заменены эквивалентными типами из Xamarin.Essentials.

Следующая таблица показывает замены .NET MAUI для функциональности в пространстве имен Xamarin.Forms.Maps:

Xamarin.Forms Интерфейс программирования приложений (API) API .NET MAUI Комментарий
Xamarin.Forms.Maps.Map.HasScrollEnabled Microsoft.Maui.Controls.Maps.Map.IsScrollEnabled
Xamarin.Forms.Maps.Map.HasZoomEnabled Microsoft.Maui.Controls.Maps.Map.IsZoomEnabled
Xamarin.Forms.Maps.Map.TrafficEnabled Microsoft.Maui.Controls.Maps.Map.IsTrafficEnabled
Xamarin.Forms.Maps.Map.MoveToLastRegionOnLayoutChange Нет эквивалента .NET MAUI.
Xamarin.Forms.Maps.Pin.Id Microsoft.Maui.Controls.Maps.Pin.MarkerId
Xamarin.Forms.Maps.Pin.Position Microsoft.Maui.Controls.Maps.Pin.Location
Xamarin.Forms.Maps.MapClickedEventArgs.Position Microsoft.Maui.Controls.Maps.MapClickedEventArgs.Location
Xamarin.Forms.Maps.Position Microsoft.Maui.Devices.Sensors.Location Элементы типа Xamarin.Forms.Maps.Position были изменены на тип Microsoft.Maui.Devices.Sensors.Location.
Xamarin.Forms.Maps.Geocoder Microsoft.Maui.Devices.Sensors.Geocoding Элементы типа Xamarin.Forms.Maps.Geocoder были изменены на тип Microsoft.Maui.Devices.Sensors.Geocoding.

.NET MAUI имеет два типа Map — Microsoft.Maui.Controls.Maps.Map и Microsoft.Maui.ApplicationModel.Map. Так как пространство имен Microsoft.Maui.ApplicationModel является одной из директив global using в .NET MAUI, при использовании элемента управления Microsoft.Maui.Controls.Maps.Map из кода необходимо полностью квалифицировать использование Map или воспользоваться с псевдонимом.

В XAML следует добавить определение пространства имен для контрола xmlns. Хотя это не обязательно, это предотвращает конфликт между типами Polygon и Polyline, которые существуют как в пространствах имен Microsoft.Maui.Controls.Maps, так и в Microsoft.Maui.Controls.Shapes. Для получения дополнительной информации см. Display a map.

Другие изменения

Небольшое количество других API было объединено при переходе с Xamarin.Forms на .NET MAUI. В следующей таблице показаны эти изменения:

Xamarin.Forms API API .NET MAUI Комментарии
Xamarin.Forms.Application.Properties Microsoft.Maui.Storage.Preferences
Xamarin.Forms.Button.Image Microsoft.Maui.Controls.Button.ImageSource
Xamarin.Forms.Frame.OutlineColor Microsoft.Maui.Controls.Frame.BorderColor
Xamarin.Forms.IQueryAttributable.ApplyQueryAttributes Microsoft.Maui.Controls.IQueryAttributable.ApplyQueryAttributes Метод ApplyQueryAttributes, в Xamarin.Forms принимающий аргумент IDictionary<string, string>, . В .NET MAUI метод ApplyQueryAttributes принимает аргумент IDictionary<string, object>.
Xamarin.Forms.MenuItem.Icon Microsoft.Maui.Controls.MenuItem.IconImageSource Xamarin.Forms.MenuItem.Icon является базовым классом для Xamarin.Forms.ToolbarItem, поэтому ToolbarItem.Icon становится ToolbarItem.IconImageSource.
Xamarin.Forms.OrientationStateTrigger.Orientation Microsoft.Maui.Controls.OrientationStateTrigger.Orientation В Xamarin.Forms свойство OrientationStateTrigger.Orientation имеет тип Xamarin.Forms.Internals.DeviceOrientation. В .NET MAUI свойство OrientationStateTrigger.Orientation имеет тип DisplayOrientation.
Xamarin.Forms.OSAppTheme Microsoft.Maui.ApplicationModel.AppTheme
Xamarin.Forms.Span.ForegroundColor Microsoft.Maui.Controls.Span.TextColor
Xamarin.Forms.ToolbarItem.Name Microsoft.Maui.Controls.MenuItem.Text Microsoft.Maui.Controls.MenuItem.Text является базовым классом для Microsoft.Maui.Controls.ToolbarItem, поэтому ToolbarItem.Name становится ToolbarItem.Text.

Кроме того, в Xamarin.Forms вызов переопределения Page.OnAppearing на Android происходит, когда приложение переводится в фоновый режим, а затем возвращается на передний план. Однако этот оверрайд не вызывается на iOS и Windows в той же ситуации. В .NET MAUI переопределение OnAppearing() не вызывается на любых платформах, когда приложение переводится в фоновый режим, а затем возвращается в передний план. Вместо этого вы должны отслеживать события жизненного цикла на Window, чтобы получать уведомления, когда приложение возвращается на передний план. Для получения дополнительной информации см. .NET MAUI windows.

Изменения в родных формах

Собственные формы стали собственным внедрением в Xamarin.Forms .NET MAUI и использует другой подход инициализации и различные методы расширения для преобразования кроссплатформенных элементов управления в собственные типы. Для получения дополнительной информации см. Native embedding.

Изменения в AssemblyInfo

Свойства, которые обычно задаются в файле AssemblyInfo.cs, теперь доступны в вашем проекте в стиле SDK. Мы рекомендуем перенести их из AssemblyInfo.cs в файл проекта в каждом проекте и удалить файл AssemblyInfo.cs.

При желании вы можете оставить файл AssemblyInfo.cs и установить свойство GenerateAssemblyInfo в вашем файле проекта на false:

<PropertyGroup>
  <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>

Чтобы получить дополнительную информацию о свойстве GenerateAssemblyInfo, см. GenerateAssemblyInfo.

Обновление зависимостей приложений

Как правило, Xamarin.Forms пакеты NuGet несовместимы с .NET 8, если они не были перекомпилированы с использованием обозначений целевой платформы .NET (TFM). Однако приложения Android могут использовать пакеты NuGet, предназначенные для платформ monoandroid и monoandroidXX.X.

Вы можете убедиться, что пакет совместим с .NET 8, посмотрев на вкладку Frameworks на NuGet для используемого вами пакета и проверив, что он содержит один из совместимых фреймворков, указанных в следующей таблице:

Совместимые фреймворки Несовместимые фреймворки
net8.0-android, monoandroid, monoandroidXX.X
net8.0-ios monotouch, xamarinios, xamarinios10
net8.0-macos monomac, xamarinmac, xamarinmac20
net8.0-tvos xamarintvos
xamarinwatchos

Замечание

Библиотеки .NET Standard, которые не имеют зависимостей от несовместимых фреймворков, перечисленных выше, по-прежнему совместимы с .NET 8.

Если пакет на NuGet указывает на совместимость с любыми из перечисленных выше совместимых фреймворков, то он считается совместимым, даже если он также содержит несовместимые фреймворки. Совместимые пакеты NuGet могут быть добавлены в ваш проект библиотеки .NET MAUI с помощью диспетчера пакетов NuGet в Visual Studio.

Если вы не можете найти совместимую с .NET 8 версию пакета NuGet, вам следует:

  • Перекомпилируйте пакет с .NET TFMs, если вы являетесь владельцем кода.
  • Ищите предварительный выпуск версии пакета .NET 8.
  • Замените зависимость на совместимую с .NET 8 альтернативу.

Компиляция и устранение неполадок

После разрешения ваших зависимостей, вам следует собрать проект. Любые ошибки помогут вам определить следующие шаги.

Подсказка

  • Удалите все папки bin и obj из всех проектов перед открытием и сборкой проектов в Visual Studio, особенно при изменении версий .NET.
  • Удалите сгенерированный файл Resource.designer.cs из проекта Android.

Следующая таблица предоставляет рекомендации для преодоления распространенных проблем сборки или времени выполнения.

Проблема Подсказка
Xamarin.* Пространство имен не существует. Обновите пространство имен на его эквивалент в .NET MAUI. Для получения дополнительной информации см. Изменения пространства имен.
API не существует. Обновите использование API до его эквивалента в .NET MAUI. Для получения дополнительной информации см. Изменения API.
Приложение не может быть развернуто. Убедитесь, что необходимый проект платформы установлен для развертывания в Configuration Manager Visual Studio.
Приложение не запускается. Обновите класс точки входа каждого проекта платформы и точку входа приложения. Для получения дополнительной информации см. раздел Bootstrap your migrated app.
CollectionView не прокручивается. Проверьте компоновку контейнера и измеренный размер CollectionView. По умолчанию элемент управления займет столько места, сколько позволяет контейнер. Grid ограничивает свои дочерние элементы своим собственным размером. Однако StackLayout позволяет детям занимать пространство за его пределами.
Всплывающее окно отображается под страницей на iOS. Во Xamarin.Formsвсех всплывающих окнах iOS являются UIWindow экземплярами, но во .NET MAUI всплывающие окна отображаются, сначала находя текущий элемент ViewController, который выполняет представление, а затем отображая всплывающее окно.PresentViewControllerAsync В таких плагинах, как Mopups, чтобы убедиться, что ваши всплывающие окна отображаются правильно, вам следует вызвать DisplayAlert (или DisplayAlertAsync в .NET 10+), DisplayActionSheet (или DisplayActionSheetAsync в .NET 10+) или DisplayPromptAsync из ContentPage, который используется внутри всплывающего окна Mopup.
BoxView не отображается. ** Размер по умолчанию для BoxView в Xamarin.Forms составляет 40x40. Размер по умолчанию BoxView в .NET MAUI составляет 0x0. Установите WidthRequest и HeightRequest на 40.
В макете отсутствуют отступы, поля или интервалы. Добавьте в ваш проект значения по умолчанию на основе ресурс стиля .NET MAUI. Для получения дополнительной информации, см. Изменения значений по умолчанию от Xamarin.Forms.
Пользовательская раскладка не работает. Код пользовательского макета нуждается в обновлении для работы в .NET MAUI. Для получения дополнительной информации смотрите Изменения пользовательского макета.
Пользовательский рендерер не работает. Код рендерера требует обновления для работы в .NET MAUI. Для получения дополнительной информации см. статью Использование пользовательских рендереров в .NET MAUI.
Эффект не работает. Код эффекта нуждается в обновлении для работы в .NET MAUI. Дополнительные сведения см. в статье "Использование эффектов в .NET MAUI".
SkiaSharp код не работает. SkiaSharp код требует небольших обновлений для работы в .NET MAUI. Для получения дополнительной информации см. SkiaSharp.
Не удается получить доступ к данным ранее созданных свойств приложения. Перенесите данные свойств приложения в предпочтения .NET MAUI. Дополнительную информацию см. в разделе Перенос данных из словаря свойств приложения Xamarin.Forms в настройки .NET MAUI.
Не удается получить доступ к ранее созданным защищенным данным хранилища. Перенесите данные безопасного хранилища в .NET MAUI. Дополнительную информацию см. в разделе Перенос из Xamarin.Essentials безопасного хранилища в безопасное хранилище .NET MAUI.
Невозможно получить доступ к данным отслеживания версий, созданным ранее. Перенесите данные отслеживания версий на .NET MAUI. Дополнительные сведения см. в разделе "Миграция данных отслеживания версий Xamarin.Forms " из приложения в приложение .NET MAUI.