Bagikan melalui

Meningkatkan aplikasi secara Xamarin.Forms manual ke aplikasi .NET MAUI multi-proyek

  • Artikel

Meningkatkan aplikasi multi-proyek Xamarin.Forms ke aplikasi .NET Multi-platform App UI (.NET MAUI) multiproyeksi mengikuti langkah yang sama seperti proyek Xamarin.Android dan Xamarin.iOS, dengan langkah tambahan untuk memanfaatkan perubahan di .NET MAUI.

Artikel ini menjelaskan cara memigrasikan Xamarin.Forms proyek pustaka secara manual ke proyek pustaka .NET MAUI. Sebelum melakukan ini, Anda harus memperbarui proyek platform Anda Xamarin.Forms menjadi proyek bergaya SDK. Proyek bergaya SDK adalah format proyek yang sama yang digunakan oleh semua beban kerja .NET, dan dibandingkan dengan banyak proyek Xamarin jauh lebih sedikit verbose. Untuk informasi tentang memperbarui proyek aplikasi Anda, lihat Meningkatkan proyek Xamarin.Android, Xamarin.iOS, dan Xamarin.Mac ke migrasi proyek .NET, Xamarin.Android, migrasi proyek Xamarin Apple, dan Xamarin.Forms migrasi proyek UWP.

Untuk memigrasikan Xamarin.Forms proyek pustaka ke proyek pustaka .NET MAUI, Anda harus:

  • Perbarui aplikasi Anda Xamarin.Forms untuk menggunakan Xamarin.Forms 5.
  • Perbarui dependensi aplikasi ke versi terbaru.
  • Pastikan aplikasi masih berfungsi.
  • Perbarui file proyek Anda agar bergaya SDK.
  • Memperbarui namespace layanan.
  • Atasi perubahan API apa pun.
  • Mengonfigurasi .NET MAUI.
  • Tingkatkan atau ganti dependensi yang tidak kompatibel dengan versi .NET 8.
  • Kompilasi dan uji aplikasi Anda.

Untuk menyederhanakan proses peningkatan, Anda harus membuat proyek pustaka .NET MAUI baru dengan nama yang sama dengan proyek pustaka Anda Xamarin.Forms , lalu menyalin dalam kode Anda. Ini adalah pendekatan yang diuraikan di bawah ini.

Memperbarui aplikasi Anda Xamarin.Forms

Sebelum memutakhirkan aplikasi ke Xamarin.Forms .NET MAUI, Anda harus terlebih dahulu memperbarui Xamarin.Forms aplikasi untuk menggunakan Xamarin.Forms 5 dan memastikan bahwa aplikasi masih berjalan dengan benar. Selain itu, Anda harus memperbarui dependensi yang digunakan aplikasi Anda ke versi terbaru.

Ini akan membantu menyederhanakan sisa proses migrasi, karena akan meminimalkan perbedaan API antara Xamarin.Forms dan .NET MAUI, dan akan memastikan bahwa Anda menggunakan versi dependensi yang kompatibel .NET jika ada.

Membuat proyek baru

Di Visual Studio, buat proyek pustaka kelas .NET MAUI baru dengan nama yang sama dengan proyek pustaka Anda Xamarin.Forms . Proyek ini akan menghosting kode dari proyek pustaka Anda Xamarin.Forms . Membuka file proyek akan mengonfirmasi bahwa Anda memiliki proyek gaya .NET SDK:

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFrameworks>net8.0;net8.0-android;net8.0-ios;net8.0-maccatalyst</TargetFrameworks>
        <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net8.0-windows10.0.19041.0</TargetFrameworks>
        <!-- Uncomment to also build the tizen app. You will need to install tizen by following this: https://github.com/Samsung/Tizen.NET -->
        <!-- <TargetFrameworks>$(TargetFrameworks);net8.0-tizen</TargetFrameworks> -->
        <UseMaui>true</UseMaui>
        <SingleProject>true</SingleProject>
        <ImplicitUsings>enable</ImplicitUsings>

        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">11.0</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">13.1</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">21.0</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.17763.0</SupportedOSPlatformVersion>
        <TargetPlatformMinVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.17763.0</TargetPlatformMinVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'tizen'">6.5</SupportedOSPlatformVersion>
    </PropertyGroup>

</Project>

Di proyek platform Anda, tambahkan referensi ke proyek pustaka baru ini. Kemudian salin file pustaka Anda Xamarin.Forms ke dalam proyek pustaka .NET MAUI.

Perubahan namespace

Namespace telah berubah dalam pemindahan dari Xamarin.Forms ke .NET MAUI, dan Xamarin.Essentials fitur sekarang menjadi bagian dari .NET MAUI. Untuk membuat pembaruan namespace layanan, lakukan pencarian dan ganti untuk namespace berikut:

Xamarin.Forms Namespace Namespace layanan MAUI .NET
Xamarin.Forms Microsoft.Maui dan Microsoft.Maui.Controls
Xamarin.Forms.DualScreen Microsoft.Maui.Controls.Foldable
Xamarin.Forms.Maps Microsoft.Maui.Controls.Maps dan 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

Proyek MAUI .NET menggunakan arahan implisit global using . Fitur ini memungkinkan Anda menghapus using direktif untuk Xamarin.Essentials namespace layanan, tanpa harus menggantinya dengan namespace .NET MAUI yang setara.

Selain itu, namespace XAML default telah berubah dari http://xamarin.com/schemas/2014/forms masuk Xamarin.Forms ke http://schemas.microsoft.com/dotnet/2021/maui di .NET MAUI. Oleh karena itu, Anda harus mengganti semua kemunculan xmlns="http://xamarin.com/schemas/2014/forms" dengan xmlns="http://schemas.microsoft.com/dotnet/2021/maui".

Catatan

Anda dapat dengan cepat memperbarui namespace layanan Anda Xamarin.Forms dengan menggunakan Tindakan cepat di Visual Studio, asalkan Anda telah menginstal AsistenMicrosoft.Maui Peningkatan.

Perubahan API

Beberapa API telah berubah dalam perpindahan dari Xamarin.Forms ke .NET MAUI. Ini adalah beberapa alasan termasuk menghapus fungsionalitas duplikat yang disebabkan oleh Xamarin.Essentials menjadi bagian dari .NET MAUI, dan memastikan bahwa API mengikuti pedoman penamaan .NET. Bagian berikut membahas perubahan ini.

Perubahan warna

Dalam Xamarin.Forms, Xamarin.Forms.Color struct memungkinkan Anda membuat Color objek menggunakan double nilai, dan menyediakan warna bernama, seperti Xamarin.Forms.Color.AliceBlue. Di .NET MAUI, fungsionalitas ini telah dipisahkan ke Microsoft.Maui.Graphics.Color dalam kelas, dan Microsoft.Maui.Graphics.Colors kelas .

Kelas Microsoft.Maui.Graphics.Color , di Microsoft.Maui.Graphics namespace, memungkinkan Anda membuat Color objek menggunakan float nilai, byte nilai, dan int nilai. Kelas Microsoft.Maui.Graphics.Colors , yang juga berada di Microsoft.Maui.Graphics namespace, sebagian besar menyediakan warna bernama yang sama.

Tabel berikut menunjukkan perubahan API antara Xamarin.Forms.Color struktur dan Microsoft.Maui.Graphics.Color kelas:

Xamarin.Forms API .NET MAUI API Komentar
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 properti diganti dengan metode di .NET MAUI.
Xamarin.Forms.Color.Saturation Microsoft.Maui.Graphics.Color.GetSaturation Xamarin.Forms properti diganti dengan metode di .NET MAUI.
Xamarin.Forms.Color.Luminosity Microsoft.Maui.Graphics.Color.GetLuminosity Xamarin.Forms properti diganti dengan metode di .NET MAUI.
Xamarin.Forms.Color.Default Tidak setara .NET MAUI. Sebagai gantinya, Microsoft.Maui.Graphics.Color objek default ke null.
Xamarin.Forms.Color.Accent Tidak setara .NET MAUI.
Xamarin.Forms.Color.FromHex Microsoft.Maui.Graphics.Color.FromArgb Microsoft.Maui.Graphics.Color.FromHex usang dan akan dihapus dalam rilis mendatang.

Selain itu, semua nilai numerik dalam adalah Microsoft.Maui.Graphics.Color , bukan double seperti yang floatdigunakan dalam Xamarin.Forms.Color.

Catatan

Tidak seperti Xamarin.Forms, Microsoft.Maui.Graphics.Color tidak memiliki konversi implisit ke System.Drawing.Color.

Perubahan tata letak

Tabel berikut mencantumkan API tata letak yang telah dihapus dalam pemindahan dari Xamarin.Forms ke .NET MAUI:

Xamarin.Forms API .NET MAUI API Komentar
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add Kelebihan Add beban yang menerima 3 argumen tidak ada di .NET MAUI.
Xamarin.Forms.Grid.IGridList<T>.AddHorizontal Tidak setara .NET MAUI.
Xamarin.Forms.Grid.IGridList<T>.AddVertical Tidak setara .NET MAUI.
Xamarin.Forms.RelativeLayout Microsoft.Maui.Controls.Compatibility.RelativeLayout Di .NET MAUI, RelativeLayout hanya ada sebagai kontrol kompatibilitas untuk pengguna yang bermigrasi dari Xamarin.Forms. Gunakan Grid sebagai gantinya xmlns , atau tambahkan untuk namespace kompatibilitas.

Selain itu, menambahkan turunan ke tata letak dalam kode di Xamarin.Forms dicapai dengan menambahkan anak-anak ke koleksi tata letak Children :

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

Di .NET MAUI, Children koleksi ini untuk penggunaan internal oleh .NET MAUI dan tidak boleh dimanipulasi secara langsung. Oleh karena itu, dalam kode turunan harus ditambahkan langsung ke tata letak:

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

Penting

Metode ekstensi tata letak apa pun Add , seperti GridExtensions.Add, dipanggil pada tata letak alih-alih Children koleksi tata letak.

Anda mungkin melihat saat menjalankan aplikasi .NET MAUI yang ditingkatkan bahwa perilaku tata letak berbeda. Untuk informasi selengkapnya, lihat Perubahan perilaku tata letak dari Xamarin.Forms.

Perubahan tata letak kustom

Proses untuk membuat tata letak kustom melibatkan Xamarin.Forms pembuatan kelas yang berasal dari Layout<View>, dan mengesampingkan VisualElement.OnMeasure metode dan Layout.LayoutChildren . Untuk informasi selengkapnya, lihat Membuat tata letak kustom di Xamarin.Forms.

Di .NET MAUI, kelas tata letak berasal dari kelas abstrak Layout . Kelas ini mendelegasikan tata letak dan pengukuran lintas platform ke kelas manajer tata letak. Setiap kelas manajer tata letak mengimplementasikan ILayoutManager antarmuka, yang menentukan bahwa Measure dan ArrangeChildren implementasi harus disediakan:

  • Implementasi Measure memanggil IView.Measure pada setiap tampilan dalam tata letak, dan mengembalikan ukuran total tata letak mengingat batasan.
  • Implementasi ArrangeChildren menentukan di mana setiap tampilan harus ditempatkan dalam batas tata letak, dan panggilan Arrange pada setiap tampilan dengan batas yang sesuai. Nilai yang dikembalikan adalah ukuran tata letak yang sebenarnya.

Untuk informasi selengkapnya, lihat Tata letak kustom.

Perubahan perangkat

Xamarin.Forms memiliki Xamarin.Forms.Device kelas yang membantu Anda berinteraksi dengan perangkat dan platform tempat aplikasi berjalan. Kelas yang setara di .NET MAUI, Microsoft.Maui.Controls.Device, tidak digunakan lagi dan fungsinya digantikan oleh beberapa jenis.

Tabel berikut menunjukkan penggantian MAUI .NET untuk fungsionalitas di Xamarin.Forms.Device kelas :

Xamarin.Forms API .NET MAUI API Komentar
Xamarin.Forms.Device.Android Microsoft.Maui.Devices.DevicePlatform.Android
Xamarin.Forms.Device.iOS Microsoft.Maui.Devices.DevicePlatform.iOS
Xamarin.Forms.Device.GTK Tidak setara .NET MAUI.
Xamarin.Forms.Device.macOS Tidak setara .NET MAUI. Sebagai gantinya, gunakan 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 Tidak setara .NET MAUI.
Xamarin.Forms.Device.Flags Tidak setara .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 Tidak setara .NET MAUI.
Xamarin.Forms.Device.GetNamedSize Tidak setara .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 Tidak setara .NET MAUI.
Xamarin.Forms.Device.SetFlowDirection Microsoft.Maui.Controls.Window.FlowDirection
Xamarin.Forms.Device.StartTimer Microsoft.Maui.Dispatching.DispatcherExtensions.StartTimer atau Microsoft.Maui.Dispatching.Dispatcher.DispatchDelayed

Memetakan perubahan

Di Xamarin.Forms, Map kontrol dan jenis terkait berada di Xamarin.Forms.Maps namespace layanan. Di .NET MAUI, fungsionalitas ini telah berpindah ke Microsoft.Maui.Controls.Maps namespace layanan dan Microsoft.Maui.Maps . Beberapa properti telah diganti namanya dan beberapa jenis telah diganti dengan jenis yang setara dari Xamarin.Essentials.

Tabel berikut ini memperlihatkan penggantian MAUI .NET untuk fungsionalitas di Xamarin.Forms.Maps namespace:

Xamarin.Forms API .NET MAUI API Komentar
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 Tidak setara .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 Anggota jenis Xamarin.Forms.Maps.Position telah berubah menjadi Microsoft.Maui.Devices.Sensors.Location jenis.
Xamarin.Forms.Maps.Geocoder Microsoft.Maui.Devices.Sensors.Geocoding Anggota jenis Xamarin.Forms.Maps.Geocoder telah berubah menjadi Microsoft.Maui.Devices.Sensors.Geocoding jenis.

.NET MAUI memiliki dua Map jenis - Microsoft.Maui.Controls.Maps.Map dan Microsoft.Maui.ApplicationModel.Map. Microsoft.Maui.ApplicationModel Karena namespace layanan adalah salah satu arahan .NET MAUIglobal using, saat menggunakan Microsoft.Maui.Controls.Maps.Map kontrol dari kode, Anda harus sepenuhnya memenuhi syarat penggunaan Anda Map atau menggunakan alias menggunakan.

Di XAML, xmlns definisi namespace harus ditambahkan untuk Map kontrol. Meskipun ini tidak diperlukan, ini mencegah tabrakan antara Polygon jenis dan Polyline , yang ada di Microsoft.Maui.Controls.Maps namespace layanan dan Microsoft.Maui.Controls.Shapes . Untuk informasi selengkapnya, lihat Menampilkan peta.

Perubahan lainnya

Sejumlah kecil API lain telah dikonsolidasikan dalam pemindahan dari Xamarin.Forms ke .NET MAUI. Tabel berikut ini memperlihatkan perubahan ini:

Xamarin.Forms API .NET MAUI API Komentar
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 Dalam Xamarin.Forms, ApplyQueryAttributes metode menerima IDictionary<string, string> argumen. Di .NET MAUI, ApplyQueryAttributes metode menerima IDictionary<string, object> argumen.
Xamarin.Forms.MenuItem.Icon Microsoft.Maui.Controls.MenuItem.IconImageSource Xamarin.Forms.MenuItem.Icon adalah kelas dasar untuk Xamarin.Forms.ToolbarItem, dan menjadi ToolbarItem.IconToolbarItem.IconImageSource.
Xamarin.Forms.OrientationStateTrigger.Orientation Microsoft.Maui.Controls.OrientationStateTrigger.Orientation Dalam Xamarin.Forms, OrientationStateTrigger.Orientation properti berjenis Xamarin.Forms.Internals.DeviceOrientation. Di .NET MAUI, OrientationStateTrigger.Orientation properti berjenis 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 adalah kelas dasar untuk Microsoft.Maui.Controls.ToolbarItem, dan menjadi ToolbarItem.NameToolbarItem.Text.

Perubahan formulir asli

Formulir asli di Xamarin.Forms telah menjadi penyematan asli di .NET MAUI, dan menggunakan pendekatan inisialisasi yang berbeda dan metode ekstensi yang berbeda untuk mengonversi kontrol lintas platform ke jenis aslinya. Untuk informasi selengkapnya, lihat Penyematan asli.

Bootstrap aplikasi anda yang dimigrasikan

Saat memperbarui Xamarin.Forms ke .NET MAUI secara manual, Anda harus mengaktifkan dukungan .NET MAUI di setiap proyek platform, memperbarui kelas titik masuk setiap proyek platform, lalu mengonfigurasi bootstrapping aplikasi .NET MAUI Anda.

Aktifkan .NET MAUI dalam proyek platform

Sebelum memperbarui setiap kelas titik masuk proyek platform, Anda harus terlebih dahulu mengaktifkan dukungan .NET MAUI. Ini dapat dicapai dengan mengatur $(UseMaui) properti build ke true di setiap proyek platform:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <UseMaui>true</UseMaui>
  </PropertyGroup>
</Project>

Penting

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 WinUI Anda. Ini akan menghentikan Anda menerima kesalahan build tentang metode yang InitializeComponent sudah ditentukan.

Menambahkan referensi paket

Di .NET 8, .NET MAUI dikirim sebagai beban kerja .NET dan beberapa paket NuGet. Keuntungan dari pendekatan ini adalah memungkinkan Anda untuk dengan mudah menyematkan proyek Anda ke versi tertentu, sekaligus memungkinkan Anda untuk dengan mudah mempratinjau build yang belum dilepas atau eksperimental.

Anda harus menambahkan referensi paket eksplisit berikut ke <ItemGroup> dalam setiap file proyek:

<PackageReference Include="Microsoft.Maui.Controls" Version="$(MauiVersion)" />
<PackageReference Include="Microsoft.Maui.Controls.Compatibility" Version="$(MauiVersion)" />

Variabel $(MauiVersion) dirujuk dari versi .NET MAUI yang telah Anda instal. Anda dapat mengambil alih ini dengan menambahkan $(MauiVersion) properti build ke setiap file proyek:

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <UseMaui>True</UseMaui>
        <MauiVersion>8.0.3</MauiVersion>
    </PropertyGroup>
</Project>

Konfigurasi proyek Android

Dalam proyek Android .NET MAUI Anda, perbarui MainApplication kelas agar sesuai dengan kode di bawah ini:

using System;
using Android.App;
using Android.Runtime;
using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.Droid
{
    [Application]
    public class MainApplication : MauiApplication
    {
        public MainApplication(IntPtr handle, JniHandleOwnership ownership) : base(handle, ownership)
        {
        }

        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
    }
}

Perbarui MainActivity juga kelas untuk diwarisi dari MauiAppCompatActivity:

using System;
using Microsoft.Maui;
using Android.App;
using Android.Content.PM;
using Android.Runtime;
using Android.OS;

namespace YOUR_NAMESPACE_HERE.Droid
{
    [Activity(Label = "MyTitle", Icon = "@mipmap/icon", Theme = "@style/MainTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize)]
    public class MainActivity : MauiAppCompatActivity
    {
        protected override void OnCreate(Bundle savedInstanceState)
        {
            base.OnCreate(savedInstanceState);
        }
    }
}

Kemudian, perbarui file manifes Anda untuk menentukan bahwa minSdKVersion adalah 21, yang merupakan versi Android SDK minimum yang diperlukan oleh .NET MAUI. Ini dapat dicapai dengan memodifikasi simpul <uses-sdk /> , yang merupakan anak dari simpul <manifest> :

<uses-sdk android:minSdkVersion="21" android:targetSdkVersion="32" />

Konfigurasi proyek iOS

Dalam proyek .NET MAUI iOS Anda, perbarui AppDelegate kelas untuk mewarisi dari MauiUIApplicationDelegate:

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Maui;
using Foundation;
using UIKit;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.iOS
{
    [Register("AppDelegate")]
    public partial class AppDelegate : MauiUIApplicationDelegate
    {
        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
    }
}

Kemudian, perbarui Info.plist sehingga MinimumOSVersion adalah 11.0, yang merupakan versi iOS minimum yang diperlukan oleh .NET MAUI.

Konfigurasi proyek UWP

Dalam proyek .NET MAUI WinUI 3 Anda, perbarui App.xaml agar sesuai dengan kode di bawah ini:

<?xml version="1.0" encoding="utf-8"?>
<maui:MauiWinUIApplication
    x:Class="YOUR_NAMESPACE_HERE.WinUI.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:maui="using:Microsoft.Maui"
    xmlns:local="using:YOUR_NAMESPACE_HERE.WinUI">
    <maui:MauiWinUIApplication.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
                <!-- Other merged dictionaries here -->
            </ResourceDictionary.MergedDictionaries>
            <!-- Other app resources here -->
        </ResourceDictionary>
    </maui:MauiWinUIApplication.Resources>
</maui:MauiWinUIApplication>

Catatan

Jika proyek Anda menyertakan sumber daya di App.xaml yang ada, Anda harus memigrasikannya ke versi baru file.

Selain itu, perbarui App.xaml.cs agar sesuai dengan kode di bawah ini:

using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.WinUI;

public partial class App : MauiWinUIApplication
{
    public App()
    {
        InitializeComponent();
    }

    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}

Catatan

Jika proyek Anda menyertakan logika bisnis dalam App.xaml.cs Anda harus memigrasikan logika tersebut ke versi baru file.

Kemudian tambahkan file peluncuran Pengaturan.json ke folder Properti proyek, dan tambahkan JSON berikut ke file:

{
  "profiles": {
    "Windows Machine": {
      "commandName": "MsixPackage",
      "nativeDebugging": true
    }
  }
}

Titik entri aplikasi

Aplikasi .NET MAUI memiliki satu titik masuk aplikasi lintas platform. Setiap titik masuk platform memanggil CreateMauiApp metode pada kelas statis MauiProgram , dan mengembalikan MauiApp.

Oleh karena itu, tambahkan kelas baru bernama MauiProgram yang berisi kode berikut:

namespace YOUR_NAMESPACE_HERE;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>();

        return builder.Build();
    }
}

Catatan

Untuk Xamarin.Forms proyek UWP, App referensi di builder.UseMauiApp<App>() dapat ditemukan dalam file MainPage.xaml.cs .

Jika ada layanan khusus platform yang perlu dimigrasikan ke .NET MAUI, gunakan AddTransient(IServiceCollection, Type) metode untuk menambahkan layanan sementara dari jenis yang ditentukan ke yang ditentukan IServiceCollection.

Catatan

Anda dapat dengan cepat memperbarui namespace layanan Anda Xamarin.Forms dengan menggunakan Tindakan cepat di Visual Studio, asalkan Anda telah menginstal AsistenMicrosoft.Maui Peningkatan.

Perubahan AssemblyInfo

Properti yang biasanya diatur dalam file AssemblyInfo.cs sekarang tersedia di proyek gaya SDK Anda. Sebaiknya migrasikan dari AssemblyInfo.cs ke file proyek Anda di setiap proyek, dan hapus file AssemblyInfo.cs .

Secara opsional, Anda dapat menyimpan file AssemblyInfo.cs dan mengatur GenerateAssemblyInfo properti dalam file proyek Anda ke false:

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

Untuk informasi selengkapnya tentang GenerateAssemblyInfo properti , lihat GenerateAssemblyInfo.

Memperbarui dependensi aplikasi

Umumnya, Xamarin.Forms paket NuGet tidak kompatibel dengan .NET 8 kecuali telah dikompilasi ulang menggunakan moniker kerangka kerja target .NET (TFM). Namun, aplikasi Android dapat menggunakan paket NuGet yang menargetkan monoandroid kerangka kerja dan monoandroidXX.X .

Anda dapat mengonfirmasi paket kompatibel .NET 8 dengan melihat tab Kerangka Kerja di NuGet untuk paket yang Anda gunakan, dan memeriksa apakah paket tersebut mencantumkan salah satu kerangka kerja yang kompatibel yang diperlihatkan dalam tabel berikut:

Kerangka kerja yang kompatibel Kerangka kerja yang tidak kompatibel
net8.0-android, monoandroid, monoandroidXX.X
net8.0-ios monotouch, xamarinios, xamarinios10
net8.0-macos monomac, xamarinmac, xamarinmac20
net8.0-tvos xamarintvos
xamarinwatchos

Catatan

Pustaka .NET Standard yang tidak memiliki dependensi pada kerangka kerja yang tidak kompatibel yang tercantum di atas masih kompatibel dengan .NET 8.

Jika paket di NuGet menunjukkan kompatibilitas dengan salah satu kerangka kerja yang kompatibel di atas, terlepas dari juga termasuk kerangka kerja yang tidak kompatibel, maka paket tersebut kompatibel. Paket NuGet yang kompatibel dapat ditambahkan ke proyek pustaka .NET MAUI Anda menggunakan manajer paket NuGet di Visual Studio.

Jika Anda tidak dapat menemukan versi paket NuGet yang kompatibel dengan .NET 8, Anda harus:

  • Kompilasi ulang paket dengan .NET TFM, jika Anda memiliki kode.
  • Cari rilis pratinjau paket versi .NET 8.
  • Ganti dependensi dengan alternatif yang kompatibel dengan .NET 8.

Mengkompilasi dan memecahkan masalah

Setelah dependensi Anda diselesaikan, Anda harus membangun proyek Anda. Kesalahan apa pun akan memandu Anda menuju langkah berikutnya.

Tip

  • Hapus semua folder bin dan obj dari semua proyek sebelum membuka dan membangun proyek di Visual Studio, terutama saat mengubah versi .NET.
  • Hapus file Resource.designer.cs yang dihasilkan dari proyek Android.

Tabel berikut ini menyediakan panduan untuk mengatasi masalah build atau runtime umum:

Masalah Tip
Xamarin.* namespace tidak ada. Perbarui namespace layanan ke setara .NET MAUI-nya. Untuk informasi selengkapnya, lihat Perubahan namespace layanan.
API tidak ada. Perbarui penggunaan API ke setara .NET MAUI-nya. Untuk informasi selengkapnya, lihat Perubahan API.
Aplikasi tidak akan disebarkan. Pastikan bahwa proyek platform yang diperlukan diatur untuk disebarkan di Manajer Konfigurasi Visual Studio.
Aplikasi tidak akan diluncurkan. Perbarui kelas titik masuk setiap proyek platform, dan titik masuk aplikasi. Untuk informasi selengkapnya, lihat Bootstrap aplikasi anda yang dimigrasikan.
CollectionView tidak menggulir. Periksa tata letak kontainer dan ukuran terukur dari CollectionView. Secara default kontrol akan memakan ruang sebanyak yang diizinkan kontainer. Membatasi Grid anak-anak pada ukurannya sendiri. Namun memungkinkan StackLayout anak-anak untuk mengambil ruang di luar batasnya.
Pop-up ditampilkan di bawah halaman di iOS. Di Xamarin.Forms, semua pop-up di iOS adalah UIWindow instans tetapi di pop-up .NET MAUI ditampilkan dengan menemukan penyajian ViewController saat ini dan menampilkan pop-up dengan PresentViewControllerAsync. Dalam plugin seperti Mopups, untuk memastikan bahwa pop-up Anda ditampilkan dengan benar, Anda harus memanggil DisplayAlert, , DisplayActionSheetatau DisplayPromptAsync dari ContentPage yang digunakan di dalam Mopup popup.
BoxView tidak muncul. Ukuran default dari in BoxViewXamarin.Forms adalah 40x40. Ukuran default di BoxView .NET MAUI adalah 0x0. Atur WidthRequest dan HeightRequest ke 40.
Tata letak tidak memiliki padding, margin, atau penspasian. Tambahkan nilai default ke proyek Anda berdasarkan sumber daya gaya .NET MAUI. Untuk informasi selengkapnya, lihat Perubahan nilai default dari Xamarin.Forms.
Tata letak kustom tidak berfungsi. Kode tata letak kustom perlu diperbarui agar berfungsi di .NET MAUI. Untuk informasi selengkapnya, lihat Perubahan tata letak kustom.
Perender kustom tidak berfungsi. Kode perender perlu diperbarui untuk bekerja di .NET MAUI. Untuk informasi selengkapnya, lihat Menggunakan perender kustom di .NET MAUI.
Efek tidak berfungsi. Kode efek perlu diperbarui agar berfungsi di .NET MAUI. Untuk informasi selengkapnya, lihat Menggunakan efek di .NET MAUI.
SkiaSharp kode tidak berfungsi. SkiaSharp kode memerlukan pembaruan kecil untuk bekerja di .NET MAUI. Untuk informasi selengkapnya, lihat Menggunakan SkiaSharp kembali kode di .NET MAUI.
Tidak dapat mengakses data properti aplikasi yang dibuat sebelumnya. Migrasikan data properti aplikasi ke preferensi MAUI .NET. Untuk informasi selengkapnya, lihat Memigrasikan Xamarin.Forms data dari kamus properti aplikasi ke preferensi MAUI .NET.
Tidak dapat mengakses data penyimpanan aman yang dibuat sebelumnya. Migrasikan data penyimpanan aman ke .NET MAUI. Untuk informasi selengkapnya, lihat Migrasi dari Xamarin.Essentials penyimpanan aman ke penyimpanan aman .NET MAUI.
Tidak dapat mengakses data pelacakan versi yang dibuat sebelumnya. Migrasikan data pelacakan versi ke .NET MAUI. Untuk informasi selengkapnya, lihat Memigrasikan data pelacakan versi dari Xamarin.Forms aplikasi ke aplikasi .NET MAUI.

Lihat juga