Миграция проекта UWP в Xamarin.Forms

Статья
05/14/2024

Чтобы обновить проект UWP Xamarin.Forms до проекта WinUI 3, необходимо:

Обновите файл проекта, чтобы он был стилем пакета SDK.
Обновление пространств имен
Устранение изменений API
Обновите или замените несовместимые зависимости версиями .NET 8.
Скомпилируйте и протестируйте приложение.

Обновление файла проекта в стиле ПАКЕТА SDK

Существующий проект UWP Xamarin.Forms можно обновить до проекта WinUI 3 в стиле пакета SDK. Проект в стиле ПАКЕТА SDK для приложения .NET MAUI WinUI 3 аналогичен следующему примеру:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType> <!-- in Xamarin.Forms this was AppContainerExe -->
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RootNamespace>YOUR_NAMESPACE_HERE.WinUI</RootNamespace>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <Platforms>x86;x64;ARM64</Platforms>
    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
    <UseMaui>true</UseMaui>
    <!-- We do not want XAML files to be processed as .NET MAUI XAML -->
    <EnableDefaultMauiItems>false</EnableDefaultMauiItems>
  </PropertyGroup>
  ...
</Project>

Важно!

Моникер целевой платформы (TFM) — это то, что обозначает проект как использование .NET, в данном случае .NET 8. Сведения о целевых платформах в проектах в стиле SDK см. в разделе "Целевые платформы" в проектах в стиле SDK.

Чтобы включить поддержку .NET MAUI, необходимо добавить <UseMaui>true</UseMaui> в файл проекта файл проекта. Кроме того, убедитесь, что вы добавили <EnableDefaultMauiItems>false</EnableDefaultMauiItems> в файл проекта. Это приведет к остановке получения ошибок сборки о том, что InitializeComponent метод уже определен.

Изменения свойств MSBuild

При обновлении проекта рекомендуется удалить следующие свойства MSBuild UWP из файла проекта:

WindowsXamlEnableOverview
AppxPackageSigningEnabled
GenerateAssemblyInfo

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

<PropertyGroup>
   <!-- Used in .NET MAUI WinUI projects -->
   <Platforms>x86;x64;ARM64</Platforms>
</PropertyGroup>

Дополнительные сведения об идентификаторах среды выполнения см . в каталоге .NET RID.

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

Существуют различия в именах пространств имен между UWP и WinUI 3. Во многих случаях это так просто, как изменение имени пространства имен, а затем код скомпилируется. Например, необходимо заменить Windows.UI.Xaml пространство имен пространством Microsoft.UI.Xaml имен. Аналогичным образом необходимо заменить Windows.UI.Xaml.Controls пространство имен пространством Microsoft.UI.Xaml.Controls имен.

В других случаях сопоставление занимает немного больше работы, и в редких случаях требуется изменение подхода. Дополнительные сведения см. в разделе Сопоставления API и библиотек UWP с пакетом SDK для приложений Windows.

Изменения API

Вам потребуется устранить любые изменения API, которые могут повлиять на ваше приложение. Например, некоторые типы, методы и свойства могут быть переименованы, устарели или удалены. Сведения о том, что поддерживается при обновлении проекта UWP до WinUI 3, см. в статье "Что поддерживается при миграции с UWP на WinUI 3". Сведения о сопоставлении функций И API UWP с WinUI 3 см. в разделе "Сопоставление функций UWP" с пакетом SDK приложений Windows и сопоставлением API и библиотек UWP с пакетом SDK для приложений Windows.

Проект можно сделать совместимым с более ранними версиями ОС, задав $(SupportedOSPlatformVersion) свойство в файле проекта:

<PropertyGroup>
   <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

Свойство $(SupportedOSPlatformVersion) указывает минимальную версию ОС, необходимую для запуска приложения или библиотеки. Если эта минимальная версия ОС среды выполнения в проекте явно не указана, она по умолчанию используется для версии платформы из Moniker Целевой платформы (TFM).

Если проект предназначен только для Windows, достаточно опустить условие проверка платформы и задать свойство напрямую$(SupportedOSPlatformVersion):

<PropertyGroup>
   <SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>
</PropertyGroup>

Дополнительные сведения о свойстве $(SupportedOSPlatformVersion) см. в разделе "Поддержка старых версий ОС".

Чтобы приложение выполнялось правильно в старой версии ОС, оно не может вызывать API, которые не существуют в этой версии ОС. Однако можно добавить условия для вызовов к более новым API-интерфейсам, чтобы они вызывались только при работе в той версии ОС, которая их поддерживает. Это можно сделать с помощью IsWindowsVersionAtLeast метода:

if (OperatingSystem.IsWindowsVersionAtLeast(10))
{
    // Use the API here
}

Удаление файлов

Следующие файлы, которые присутствуют в проектах UWP Xamarin.Forms, не существуют в проектах WinUI 3:

MainPage.xaml и MainPage.xaml.cs
AssemblyInfo.cs
Default.rd.xml

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

Изменения в Package.appxmanifest

В файл Package.appxmanifest проекта необходимо вносить следующие изменения:

Задайте точку $targetentrypoint$ входа приложения. Дополнительные сведения см. в разделе "Целевая точка входа".
runFullTrust Добавьте возможность. Дополнительные сведения см. в разделе "Запуск полного доверия".
Добавьте семейства устройств и Windows.Desktop целевых Windows.Universal устройств. Дополнительные сведения см. в разделе "Семейство универсальных целевых устройств" и семейство целевых устройств для настольных компьютеров.

Внесение этих изменений устраняет распространенные ошибки развертывания для приложения в Windows.

Пример соответствующего файла Package.appxmanifest см. в статье Package.appxmanifest.

Поведение среды выполнения

Существуют изменения String.IndexOf() в поведении метода в .NET 5+ на разных платформах. Дополнительные сведения см. в статье о глобализации .NET и ICU.

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

Загрузка приложения

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