Meningkatkan aplikasi secara Xamarin.Forms manual ke aplikasi .NET MAUI multi-proyek
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 kode, konfigurasi, dan sumber daya 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:
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 Asisten Microsoft.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. Misalnya, gunakan Colors.AliceBlue untuk menentukan AliceBlue warna.
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.Icon ToolbarItem.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.Name ToolbarItem.Text. |
Selain itu, dalam Xamarin.Forms, penimpaan Page.OnAppearing dipanggil di Android ketika aplikasi di latar belakang dan kemudian dibawa ke latar depan. Namun, penimpaan ini tidak dipanggil di iOS dan Windows dalam skenario yang sama. Di .NET MAUI, OnAppearing() penimpaan tidak dipanggil pada platform apa pun ketika aplikasi di latar belakang dan kemudian dibawa ke latar depan. Sebagai gantinya, Anda harus mendengarkan peristiwa Window siklus hidup untuk diberi tahu saat aplikasi kembali ke latar depan. Untuk informasi selengkapnya, lihat jendela .NET MAUI.
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 aplikasi secara manual ke .NET MAUI, 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 launchSettings.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 Asisten Microsoft.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 BoxView Xamarin.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. |
