Migrasi proyek UWP Xamarin.Forms

Artikel
05/14/2024

Untuk memperbarui proyek UWP Xamarin.Forms Anda ke proyek WinUI 3, Anda harus:

Perbarui file proyek Anda agar bergaya SDK.
Memperbarui namespace layanan
Mengatasi perubahan API apa pun
Perbarui atau ganti dependensi yang tidak kompatibel dengan versi .NET 8.
Kompilasi dan uji aplikasi Anda.

Memperbarui ke file proyek bergaya SDK

Proyek UWP Xamarin.Forms Anda yang ada dapat diperbarui ke proyek WinUI 3 bergaya SDK di tempat. Proyek bergaya SDK untuk aplikasi .NET MAUI WinUI 3 mirip dengan contoh berikut:

<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>

Penting

Moniker kerangka kerja target (TFM) adalah yang menunjukkan proyek sebagai menggunakan .NET, dalam hal ini .NET 8. Untuk informasi tentang kerangka kerja target dalam proyek bergaya SDK, lihat Kerangka kerja target dalam proyek bergaya SDK.

Anda harus menambahkan <UseMaui>true</UseMaui> ke file proyek Anda untuk mengaktifkan dukungan .NET MAUI. Selain itu, pastikan Anda telah menambahkan <EnableDefaultMauiItems>false</EnableDefaultMauiItems> ke file proyek. Ini akan menghentikan Anda menerima kesalahan build tentang metode yang InitializeComponent sudah ditentukan.

Perubahan pada properti MSBuild

Saat meningkatkan proyek Anda, disarankan untuk menghapus properti MSBuild UWP berikut dari file proyek Anda:

WindowsXamlEnableOverview
AppxPackageSigningEnabled
GenerateAssemblyInfo

Anda juga harus memastikan bahwa arsitektur platform dalam proyek target ditentukan dengan pengidentifikasi runtime .NET berikut:

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

Untuk informasi selengkapnya tentang pengidentifikasi runtime, lihat Katalog .NET RID.

Perubahan namespace

Ada perbedaan nama namespace layanan antara UWP dan WinUI 3. Dalam banyak kasus, mudah untuk mengubah nama namespace layanan dan kemudian kode Anda akan dikompilasi. Misalnya, Anda harus mengganti Windows.UI.Xaml namespace dengan Microsoft.UI.Xaml namespace. Demikian pula, Anda harus mengganti Windows.UI.Xaml.Controls namespace dengan Microsoft.UI.Xaml.Controls namespace.

Di lain waktu, pemetaan membutuhkan sedikit lebih banyak pekerjaan, dan dalam kasus yang jarang terjadi membutuhkan perubahan pendekatan. Untuk informasi selengkapnya, lihat Memetakan API dan pustaka UWP ke SDK Aplikasi Windows.

Perubahan API

Anda harus mengatasi perubahan API apa pun yang dapat memengaruhi aplikasi Anda. Misalnya, beberapa jenis, metode, dan properti mungkin telah diganti namanya, tidak digunakan lagi, atau dihapus. Untuk informasi tentang apa yang didukung saat meningkatkan proyek UWP Anda ke WinUI 3, lihat Apa yang didukung saat bermigrasi dari UWP ke WinUI 3. Untuk informasi tentang pemetaan fitur dan API UWP ke WinUI 3, lihat Memetakan fitur UWP ke SDK Aplikasi Windows dan Memetakan API dan pustaka UWP ke SDK Aplikasi Windows.

Proyek Anda dapat dibuat kompatibel dengan versi OS sebelumnya dengan mengatur $(SupportedOSPlatformVersion) properti dalam file proyek Anda:

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

Properti $(SupportedOSPlatformVersion) menunjukkan versi OS minimum yang diperlukan untuk menjalankan aplikasi atau pustaka Anda. Jika Anda tidak secara eksplisit menentukan versi OS runtime minimum ini dalam proyek Anda, versi tersebut default ke versi platform dari Target Framework Moniker (TFM).

Jika proyek Anda hanya menargetkan Windows, cukup untuk menghilangkan kondisi pemeriksaan platform dan mengatur properti secara $(SupportedOSPlatformVersion) langsung:

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

Untuk informasi selengkapnya tentang properti ini $(SupportedOSPlatformVersion) , lihat Mendukung versi OS yang lebih lama.

Agar aplikasi berjalan dengan benar pada versi OS yang lebih lama, aplikasi tidak dapat memanggil API yang tidak ada pada versi OS tersebut. Namun, Anda dapat menambahkan penjaga di sekitar panggilan ke API yang lebih baru sehingga hanya dipanggil saat berjalan pada versi OS yang mendukungnya. Ini dapat dicapai dengan IsWindowsVersionAtLeast metode :

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

Menghapus berkas

File berikut, yang ada dalam proyek UWP Xamarin.Forms, tidak ada dalam proyek WinUI 3:

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

Oleh karena itu, Anda harus menghapus file-file ini jika ada di proyek WinUI 3 Anda. Setiap logika bisnis yang diperlukan yang terkandung dalam file-file ini harus dipindahkan ke tempat lain.

Perubahan pada Package.appxmanifest

Perubahan berikut harus dilakukan pada file Package.appxmanifest proyek yang dimigrasikan:

Atur titik entri aplikasi ke $targetentrypoint$ . Untuk informasi selengkapnya, lihat Titik masuk target.
runFullTrust Tambahkan kemampuan. Untuk informasi selengkapnya, lihat Menjalankan kemampuan kepercayaan penuh.
Windows.Universal Tambahkan keluarga perangkat target dan Windows.Desktop . Untuk informasi selengkapnya, lihat Keluarga perangkat target universal dan Keluarga perangkat target desktop.

Membuat perubahan ini memperbaiki kesalahan penyebaran umum untuk aplikasi Anda di Windows.

Untuk contoh file Package.appxmanifest yang sesuai, lihat Package.appxmanifest.

Perilaku runtime

Ada perubahan perilaku pada String.IndexOf() metode di .NET 5+ pada platform yang berbeda. Untuk informasi selengkapnya, lihat globalisasi .NET dan ICU.

Langkah berikutnya

Bootstrap aplikasi Anda

Bagikan melalui