Ręczne uaktualnianie Xamarin.Forms aplikacji do wieloprojektowej aplikacji .NET MAUI
Uaktualnianie aplikacji wieloprojektowej Xamarin.Forms do wieloprojektowej aplikacji wieloplatformowej interfejsu użytkownika aplikacji platformy .NET (.NET MAUI) odbywa się zgodnie z tymi samymi krokami co projekt platformy Xamarin.Android i Xamarin.iOS z dodatkowymi krokami w celu skorzystania ze zmian w programie .NET MAUI.
W tym artykule opisano sposób ręcznego Xamarin.Forms migrowania projektu biblioteki do projektu biblioteki MAUI platformy .NET. Przed wykonaniem tej czynności należy zaktualizować Xamarin.Forms projekty platformy tak, aby były projektami w stylu zestawu SDK. Projekty w stylu zestawu SDK są tym samym formatem projektu używanym przez wszystkie obciążenia platformy .NET, a w porównaniu z wieloma projektami platformy Xamarin są znacznie mniej pełne. Aby uzyskać informacje na temat aktualizowania projektów aplikacji, zobacz Uaktualnianie projektów Xamarin.Android, Xamarin.iOS i Xamarin.Mac do projektów .NET, Xamarin.Android, migracja projektów Xamarin Apple i Xamarin.Forms migracja projektów platformy UWP.
Aby przeprowadzić migrację Xamarin.Forms projektu biblioteki do projektu biblioteki MAUI platformy .NET, musisz:
- Zaktualizuj aplikację Xamarin.Forms do użycia Xamarin.Forms 5.
- Zaktualizuj zależności aplikacji do najnowszych wersji.
- Upewnij się, że aplikacja nadal działa.
- Zaktualizuj plik projektu tak, aby był w stylu zestawu SDK.
- Aktualizowanie przestrzeni nazw.
- Rozwiąż wszelkie zmiany interfejsu API.
- Skonfiguruj program .NET MAUI.
- Uaktualnij lub zastąp niezgodne zależności wersjami platformy .NET 8.
- Skompiluj i przetestuj aplikację.
Aby uprościć proces uaktualniania, należy utworzyć nowy projekt biblioteki MAUI platformy .NET o tej samej nazwie co Xamarin.Forms projekt biblioteki, a następnie skopiować kod, konfigurację i zasoby. Jest to podejście opisane poniżej.
Aktualizowanie aplikacji Xamarin.Forms
Przed uaktualnieniem Xamarin.Forms aplikacji do programu .NET MAUI należy najpierw zaktualizować Xamarin.Forms aplikację do użycia Xamarin.Forms 5 i upewnić się, że nadal działa prawidłowo. Ponadto należy zaktualizować zależności używane przez aplikację do najnowszych wersji.
Pomoże to uprościć resztę procesu migracji, ponieważ zminimalizuje różnice między interfejsem Xamarin.Forms API a programem .NET MAUI i zapewni, że używasz zgodnych wersji zależności platformy .NET, jeśli istnieją.
Tworzenie nowego projektu
W programie Visual Studio utwórz nowy projekt biblioteki klas .NET MAUI o tej samej nazwie co Xamarin.Forms projekt biblioteki. Ten projekt będzie hostować kod z Xamarin.Forms projektu biblioteki. Otwarcie pliku projektu potwierdzi, że masz projekt w stylu zestawu SDK platformy .NET:
<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>
W projektach platformy dodaj odwołanie do tego nowego projektu biblioteki. Następnie skopiuj Xamarin.Forms pliki biblioteki do projektu biblioteki .NET MAUI.
Zmiany przestrzeni nazw
Przestrzenie nazw zmieniły się w przejściu z Xamarin.Forms do .NET MAUI, a Xamarin.Essentials funkcje są teraz częścią interfejsu MAUI platformy .NET. Aby wprowadzić aktualizacje przestrzeni nazw, wykonaj wyszukiwanie i zastępowanie następujących przestrzeni nazw:
Projekty MAUI platformy .NET korzystają z niejawnych global using dyrektyw. Ta funkcja umożliwia usuwanie using dyrektyw dla Xamarin.Essentials przestrzeni nazw bez konieczności zastępowania ich równoważnymi przestrzeniami nazw .NET MAUI.
Ponadto domyślna przestrzeń nazw XAML zmieniła się z http://xamarin.com/schemas/2014/forms na w Xamarin.Forms http://schemas.microsoft.com/dotnet/2021/maui .NET MAUI. W związku z tym należy zastąpić wszystkie wystąpienia elementu xmlns="http://xamarin.com/schemas/2014/forms" ciągiem xmlns="http://schemas.microsoft.com/dotnet/2021/maui".
Uwaga
Przestrzenie nazw można szybko zaktualizować Xamarin.Forms przy użyciu szybkich Microsoft.Maui akcji w programie Visual Studio, pod warunkiem że masz zainstalowanego Asystenta uaktualniania.
Zmiany w interfejsie API
Niektóre interfejsy API zmieniły się w przejściu z Xamarin.Forms do .NET MAUI. Jest to wiele powodów, w tym usunięcie zduplikowanych funkcji spowodowanych Xamarin.Essentials przez bycie częścią interfejsu MAUI platformy .NET i zapewnienie, że interfejsy API są zgodne z wytycznymi dotyczącymi nazewnictwa platformy .NET. W poniższych sekcjach omówiono te zmiany.
Zmiany kolorów
W Xamarin.Formssystemie Xamarin.Forms.Color struktura umożliwia konstruowanie Color obiektów przy użyciu double wartości i udostępnia nazwane kolory, takie jak Xamarin.Forms.Color.AliceBlue. W programie .NET MAUI ta funkcja została podzielona na klasę Microsoft.Maui.Graphics.Color i klasę Microsoft.Maui.Graphics.Colors .
Klasa Microsoft.Maui.Graphics.Color w Microsoft.Maui.Graphics przestrzeni nazw umożliwia konstruowanie Color obiektów przy użyciu float wartości, byte wartości i int wartości. Klasa Microsoft.Maui.Graphics.Colors , która znajduje się również w Microsoft.Maui.Graphics przestrzeni nazw, w dużej mierze zapewnia takie same nazwy kolorów. Na przykład użyj polecenia Colors.AliceBlue , aby określić AliceBlue kolor.
W poniższej tabeli przedstawiono zmiany interfejsu API między strukturą Xamarin.Forms.Color a klasą Microsoft.Maui.Graphics.Color :
| Xamarin.Forms API | Interfejs API MAUI platformy .NET | Komentarz |
|---|---|---|
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 właściwość została zastąpiona metodą w programie .NET MAUI. |
Xamarin.Forms.Color.Saturation |
Microsoft.Maui.Graphics.Color.GetSaturation | Xamarin.Forms właściwość została zastąpiona metodą w programie .NET MAUI. |
Xamarin.Forms.Color.Luminosity |
Microsoft.Maui.Graphics.Color.GetLuminosity | Xamarin.Forms właściwość została zastąpiona metodą w programie .NET MAUI. |
Xamarin.Forms.Color.Default |
Brak odpowiednika interfejsu MAUI platformy .NET. Microsoft.Maui.Graphics.Color Zamiast tego obiekty domyślnie mają wartość null. |
|
Xamarin.Forms.Color.Accent |
Brak odpowiednika interfejsu MAUI platformy .NET. | |
Xamarin.Forms.Color.FromHex |
Microsoft.Maui.Graphics.Color.FromArgb | Microsoft.Maui.Graphics.Color.FromHex jest przestarzały i zostanie usunięty w przyszłej wersji. |
Ponadto wszystkie wartości liczbowe w elemecie Microsoft.Maui.Graphics.Color to float, a nie double jako używane w elem Xamarin.Forms.Color.
Uwaga
W przeciwieństwie do Xamarin.Formselementu nie Microsoft.Maui.Graphics.Color ma niejawnej konwersji na System.Drawing.Color.
Zmiany układu
W poniższej tabeli wymieniono interfejsy API układu, które zostały usunięte w przeniesieniu z Xamarin.Forms do programu .NET MAUI:
| Xamarin.Forms API | Interfejs API MAUI platformy .NET | Komentarze |
|---|---|---|
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add |
Przeciążenie Add akceptujące 3 argumenty nie jest obecne w interfejsie MAUI platformy .NET. |
|
Xamarin.Forms.Grid.IGridList<T>.AddHorizontal |
Brak odpowiednika interfejsu MAUI platformy .NET. | |
Xamarin.Forms.Grid.IGridList<T>.AddVertical |
Brak odpowiednika interfejsu MAUI platformy .NET. | |
Xamarin.Forms.RelativeLayout |
Microsoft.Maui.Controls.Compatibility.RelativeLayout | W programie .NET MAUI RelativeLayout istnieje tylko jako kontrola zgodności dla użytkowników migrujących z Xamarin.Formsprogramu . Zamiast tego użyj Grid polecenia lub dodaj element xmlns dla przestrzeni nazw zgodności. |
Ponadto dodanie elementów podrzędnych do układu w kodzie w Xamarin.Forms programie jest realizowane przez dodanie elementów podrzędnych do kolekcji układu Children :
Grid grid = new Grid();
grid.Children.Add(new Label { Text = "Hello world" });
W programie .NET MAUI Children kolekcja służy do użytku wewnętrznego przez program .NET MAUI i nie powinna być manipulowana bezpośrednio. W związku z tym w elementach podrzędnych kodu należy dodać bezpośrednio do układu:
Grid grid = new Grid();
grid.Add(new Label { Text = "Hello world" });
Ważne
Wszystkie Add metody rozszerzenia układu, takie jak GridExtensions.Add, są wywoływane w układzie, a nie w kolekcji układów Children .
Podczas uruchamiania uaktualnionej aplikacji .NET MAUI można zauważyć, że zachowanie układu jest inne. Aby uzyskać więcej informacji, zobacz Zmiany zachowania układu z Xamarin.Forms.
Zmiany układu niestandardowego
Proces tworzenia niestandardowego układu w programie Xamarin.Forms obejmuje utworzenie klasy pochodzącej z Layout<View>klasy , a także zastąpienie VisualElement.OnMeasure metod i Layout.LayoutChildren . Aby uzyskać więcej informacji, zobacz Tworzenie niestandardowego układu w programie Xamarin.Forms.
W programie .NET MAUI klasy układu pochodzą z klasy abstrakcyjnej Layout . Ta klasa deleguje układ i pomiar międzyplatformowy do klasy menedżera układu. Każda klasa menedżera układów implementuje ILayoutManager interfejs, który określa, że ArrangeChildren Measure i należy podać implementacje:
- Implementacja Measure wywołuje IView.Measure każdy widok w układzie i zwraca całkowity rozmiar układu, biorąc pod uwagę ograniczenia.
- Implementacja ArrangeChildren określa, gdzie każdy widok powinien być umieszczony w granicach układu, i wywołuje Arrange każdy widok z odpowiednimi granicami. Wartość zwracana jest rzeczywistym rozmiarem układu.
Aby uzyskać więcej informacji, zobacz Niestandardowe układy.
Zmiany urządzenia
Xamarin.Forms ma klasę, która ułatwia interakcję Xamarin.Forms.Device z urządzeniem i platformą, na której działa aplikacja. Równoważna klasa w programie .NET MAUI, Microsoft.Maui.Controls.Device, jest przestarzała, a jej funkcjonalność jest zastępowana przez wiele typów.
W poniższej Xamarin.Forms.Device tabeli przedstawiono zamiany interfejsu MAUI platformy .NET dla funkcji w klasie:
| Xamarin.Forms API | Interfejs API MAUI platformy .NET | Komentarze |
|---|---|---|
Xamarin.Forms.Device.Android |
Microsoft.Maui.Devices.DevicePlatform.Android | |
Xamarin.Forms.Device.iOS |
Microsoft.Maui.Devices.DevicePlatform.iOS | |
Xamarin.Forms.Device.GTK |
Brak odpowiednika interfejsu MAUI platformy .NET. | |
Xamarin.Forms.Device.macOS |
Brak odpowiednika interfejsu MAUI platformy .NET. Zamiast tego użyj polecenia 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 |
Brak odpowiednika interfejsu MAUI platformy .NET. | |
Xamarin.Forms.Device.Flags |
Brak odpowiednika interfejsu MAUI platformy .NET. | |
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 |
Brak odpowiednika interfejsu MAUI platformy .NET. | |
Xamarin.Forms.Device.GetNamedSize |
Brak odpowiednika interfejsu MAUI platformy .NET. | |
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 |
Brak odpowiednika interfejsu MAUI platformy .NET. | |
Xamarin.Forms.Device.SetFlowDirection |
Microsoft.Maui.Controls.Window.FlowDirection | |
Xamarin.Forms.Device.StartTimer |
Microsoft.Maui.Dispatching.DispatcherExtensions.StartTimer lub Microsoft.Maui.Dispatching.Dispatcher.DispatchDelayed |
Zmiany mapy
W Xamarin.Formssystemie kontrolka Map i skojarzone typy znajdują się w Xamarin.Forms.Maps przestrzeni nazw. W programie .NET MAUI ta funkcja została przeniesiona do Microsoft.Maui.Controls.Maps przestrzeni nazw i Microsoft.Maui.Maps . Niektóre właściwości zostały zmienione i niektóre typy zostały zastąpione równoważnymi typami z .Xamarin.Essentials
W poniższej tabeli przedstawiono zamiany interfejsu MAUI platformy .NET dla funkcji w Xamarin.Forms.Maps przestrzeni nazw:
| Xamarin.Forms API | Interfejs API MAUI platformy .NET | Komentarz |
|---|---|---|
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 |
Brak odpowiednika interfejsu MAUI platformy .NET. | |
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 | Elementy członkowskie typu Xamarin.Forms.Maps.Position zmieniły się na Microsoft.Maui.Devices.Sensors.Location typ. |
Xamarin.Forms.Maps.Geocoder |
Microsoft.Maui.Devices.Sensors.Geocoding | Elementy członkowskie typu Xamarin.Forms.Maps.Geocoder zmieniły się na Microsoft.Maui.Devices.Sensors.Geocoding typ. |
Program .NET MAUI ma dwa Map typy — Microsoft.Maui.Controls.Maps.Map i Microsoft.Maui.ApplicationModel.Map. Microsoft.Maui.ApplicationModel Ponieważ przestrzeń nazw jest jedną z dyrektyw .NET MAUIglobal using, podczas korzystania z Microsoft.Maui.Controls.Maps.Map kontrolki z kodu musisz w pełni zakwalifikować Map użycie lub użyć aliasu.
W języku XAML należy dodać definicję xmlns przestrzeni nazw dla kontrolki Map . Chociaż nie jest to wymagane, zapobiega kolizji między Polygon typami i Polyline , które istnieją zarówno Microsoft.Maui.Controls.Maps w przestrzeniach nazw, jak i Microsoft.Maui.Controls.Shapes . Aby uzyskać więcej informacji, zobacz Wyświetlanie mapy.
Inne zmiany
Niewielka liczba innych interfejsów API została skonsolidowana w przeniesieniu z Xamarin.Forms do .NET MAUI. W poniższej tabeli przedstawiono następujące zmiany:
| Xamarin.Forms API | Interfejs API MAUI platformy .NET | Komentarze |
|---|---|---|
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 | W Xamarin.Formsmetodzie ApplyQueryAttributes metoda akceptuje IDictionary<string, string> argument. W programie .NET MAUI ApplyQueryAttributes metoda akceptuje IDictionary<string, object> argument. |
Xamarin.Forms.MenuItem.Icon |
Microsoft.Maui.Controls.MenuItem.IconImageSource | Xamarin.Forms.MenuItem.Icon jest klasą bazową dla Xamarin.Forms.ToolbarItemklasy , a więc ToolbarItem.Icon staje się ToolbarItem.IconImageSource. |
Xamarin.Forms.OrientationStateTrigger.Orientation |
Microsoft.Maui.Controls.OrientationStateTrigger.Orientation | W Xamarin.Formspliku OrientationStateTrigger.Orientation właściwość ma typ Xamarin.Forms.Internals.DeviceOrientation. W programie .NET MAUI OrientationStateTrigger.Orientation właściwość ma typ 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 jest klasą bazową dla Microsoft.Maui.Controls.ToolbarItemklasy , a więc ToolbarItem.Name staje się ToolbarItem.Text. |
Ponadto w systemie Xamarin.FormsPage.OnAppearing zastąpienie jest wywoływane w systemie Android, gdy aplikacja jest w tle, a następnie jest wprowadzana na pierwszy plan. Jednak to zastąpienie nie jest wywoływane w systemach iOS i Windows w tym samym scenariuszu. W programie .NET MAUI przesłonięcia nie jest wywoływane na żadnych platformach, gdy aplikacja jest w tle, OnAppearing() a następnie przeniesiona na pierwszy plan. Zamiast tego należy nasłuchiwać zdarzeń Window cyklu życia, aby otrzymywać powiadomienia, gdy aplikacja powróci na pierwszy plan. Aby uzyskać więcej informacji, zobacz .NET MAUI windows.
Zmiany formularzy natywnych
Natywne formularze w programie Xamarin.Forms stały się natywnym osadzaniem w programie .NET MAUI i używa innego podejścia inicjalizacji i różnych metod rozszerzeń do konwertowania kontrolek międzyplatformowych na ich typy natywne. Aby uzyskać więcej informacji, zobacz Osadzanie natywne.
Uruchamianie migrowanej aplikacji
Podczas ręcznego aktualizowania Xamarin.Forms aplikacji do programu .NET MAUI należy włączyć obsługę interfejsu MAUI platformy .NET w każdym projekcie platformy, zaktualizować klasę punktu wejścia każdego projektu platformy, a następnie skonfigurować uruchamianie aplikacji .NET MAUI.
Włączanie interfejsu MAUI platformy .NET w projektach platformy
Przed zaktualizowaniem klasy punktu wejścia każdego projektu platformy należy najpierw włączyć obsługę programu .NET MAUI. Można to osiągnąć, ustawiając właściwość kompilacji $(UseMaui) na true wartość w każdym projekcie platformy:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
...
<UseMaui>true</UseMaui>
</PropertyGroup>
</Project>
Ważne
Aby włączyć obsługę interfejsu MAUI platformy .NET, należy dodać <UseMaui>true</UseMaui> plik projektu. Ponadto upewnij się, że dodano <EnableDefaultMauiItems>false</EnableDefaultMauiItems> cię do pliku projektu WinUI. Spowoduje to zatrzymanie otrzymywania błędów kompilacji dotyczących już zdefiniowanej InitializeComponent metody.
Dodawanie odwołań do pakietu
Na platformie .NET 8 program .NET MAUI jest dostarczany jako obciążenie platformy .NET i wiele pakietów NuGet. Zaletą tego podejścia jest możliwość łatwego przypinania projektów do określonych wersji, a także umożliwia łatwe wyświetlanie podglądu nieopublikowanych lub eksperymentalnych kompilacji.
Należy dodać następujące jawne <ItemGroup> odwołania do pakietu w każdym pliku projektu:
<PackageReference Include="Microsoft.Maui.Controls" Version="$(MauiVersion)" />
<PackageReference Include="Microsoft.Maui.Controls.Compatibility" Version="$(MauiVersion)" />
Zmienna $(MauiVersion) jest przywoływane z zainstalowanej wersji programu .NET MAUI. Można to zastąpić, dodając właściwość kompilacji $(MauiVersion) do każdego pliku projektu:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<UseMaui>True</UseMaui>
<MauiVersion>8.0.3</MauiVersion>
</PropertyGroup>
</Project>
Konfiguracja projektu systemu Android
W projekcie .NET MAUI Android zaktualizuj klasę tak, aby odpowiadała MainApplication poniższemu kodowi:
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();
}
}
Zaktualizuj również klasę MainActivity , aby dziedziczyła z MauiAppCompatActivityklasy :
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);
}
}
}
Następnie zaktualizuj plik manifestu, aby określić wartość minSdKVersion 21, czyli minimalną wersję zestawu ANDROID SDK wymaganą przez program .NET MAUI. Można to osiągnąć, modyfikując <uses-sdk /> węzeł, który jest elementem podrzędnym węzła <manifest> :
<uses-sdk android:minSdkVersion="21" android:targetSdkVersion="32" />
Konfiguracja projektu systemu iOS
W projekcie .NET MAUI dla systemu iOS zaktualizuj klasę AppDelegate , aby dziedziczyła z MauiUIApplicationDelegateklasy :
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();
}
}
Następnie zaktualizuj plik Info.plist tak, MinimumOSVersion aby był to 11.0, czyli minimalna wersja systemu iOS wymagana przez program .NET MAUI.
Konfiguracja projektu platformy UWP
W projekcie .NET MAUI WinUI 3 zaktualizuj plik App.xaml , aby był zgodny z poniższym kodem:
<?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>
Uwaga
Jeśli projekt zawierał zasoby w istniejącym pliku App.xaml , należy je zmigrować do nowej wersji pliku.
Ponadto zaktualizuj App.xaml.cs , aby pasować do poniższego kodu:
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();
}
Uwaga
Jeśli projekt zawierał logikę biznesową w App.xaml.cs należy przeprowadzić migrację tej logiki do nowej wersji pliku.
Następnie dodaj plik launchSettings.json do folderu Properties projektu i dodaj następujący kod JSON do pliku:
{
"profiles": {
"Windows Machine": {
"commandName": "MsixPackage",
"nativeDebugging": true
}
}
}
Punkt wejścia aplikacji
Aplikacje MAUI platformy .NET mają jeden międzyplatformowy punkt wejścia aplikacji. Każdy punkt wejścia platformy wywołuje metodę CreateMauiApp w klasie statycznej MauiProgram i zwraca wartość MauiApp.
W związku z tym dodaj nową klasę o nazwie MauiProgram zawierającą następujący kod:
namespace YOUR_NAMESPACE_HERE;
public static class MauiProgram
{
public static MauiApp CreateMauiApp()
{
var builder = MauiApp.CreateBuilder();
builder
.UseMauiApp<App>();
return builder.Build();
}
}
Uwaga
W przypadku Xamarin.Forms projektów App platformy UWP odwołanie builder.UseMauiApp<App>() można znaleźć w pliku MainPage.xaml.cs .
Jeśli istnieją usługi specyficzne dla platformy, które muszą zostać zmigrowane do programu .NET MAUI, użyj AddTransient(IServiceCollection, Type) metody , aby dodać usługę przejściową określonego typu do określonego IServiceCollectiontypu .
Uwaga
Przestrzenie nazw można szybko zaktualizować Xamarin.Forms przy użyciu szybkich Microsoft.Maui akcji w programie Visual Studio, pod warunkiem że masz zainstalowanego Asystenta uaktualniania.
Zmiany informacji o zestawie
Właściwości, które są zwykle ustawiane w pliku AssemblyInfo.cs, są teraz dostępne w projekcie w stylu zestawu SDK. Zalecamy migrowanie ich z AssemblyInfo.cs do pliku projektu w każdym projekcie i usunięcie pliku AssemblyInfo.cs .
Opcjonalnie możesz zachować plik AssemblyInfo.cs i ustawić GenerateAssemblyInfo właściwość w pliku projektu na wartość false:
<PropertyGroup>
<GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>
Aby uzyskać więcej informacji na temat GenerateAssemblyInfo właściwości, zobacz GenerateAssemblyInfo.
Aktualizowanie zależności aplikacji
Ogólnie rzecz biorąc, pakiety NuGet nie są zgodne z platformą .NET 8, Xamarin.Forms chyba że zostały ponownie skompilowane przy użyciu programów monikers platformy docelowej .NET (TFMs). Jednak aplikacje systemu Android mogą używać pakietów NuGet przeznaczonych dla platform monoandroid i monoandroidXX.X .
Możesz potwierdzić, że pakiet jest zgodny z platformą .NET 8, przeglądając kartę Struktury w narzędziu NuGet dla używanego pakietu i sprawdzając, czy zawiera jedną z zgodnych struktur pokazanych w poniższej tabeli:
| Zgodne struktury | Niezgodne struktury |
|---|---|
| net8.0-android, monoandroid, monoandroidXX.X | |
| net8.0-ios | monotouch, xamarinios, xamarinios10 |
| net8.0-macos | monomac, xamarinmac, xamarinmac20 |
| net8.0-tvos | xamarintvos |
| xamarinwatchos |
Uwaga
Biblioteki .NET Standard, które nie mają zależności od niezgodnych platform wymienionych powyżej, są nadal zgodne z platformą .NET 8.
Jeśli pakiet w pakiecie NuGet wskazuje zgodność z dowolną z powyższych platform zgodnych, niezależnie od tego, czy zawiera również niezgodne struktury, pakiet jest zgodny. Zgodne pakiety NuGet można dodać do projektu biblioteki MAUI platformy .NET przy użyciu menedżera pakietów NuGet w programie Visual Studio.
Jeśli nie możesz znaleźć zgodnej wersji pakietu NuGet platformy .NET 8, należy wykonać następujące czynności:
- Ponownie skompiluj pakiet za pomocą programu .NET TFMs, jeśli jesteś właścicielem kodu.
- Poszukaj wersji zapoznawczej pakietu .NET 8.
- Zastąp zależność alternatywą zgodną z platformą .NET 8.
Kompilowanie i rozwiązywanie problemów
Po rozwiązaniu zależności należy skompilować projekt. Wszelkie błędy spowodują przejście do następnych kroków.
Napiwek
- Przed otwarciem i utworzeniem projektów w programie Visual Studio usuń wszystkie foldery bin i obj , szczególnie podczas zmieniania wersji platformy .NET.
- Usuń Resource.designer.cs wygenerowany plik z projektu systemu Android.
Poniższa tabela zawiera wskazówki dotyczące przezwyciężenia typowych problemów z kompilacją lub środowiskiem uruchomieniowym:
| Problem | Napiwek |
|---|---|
Xamarin.* Przestrzeń nazw nie istnieje. |
Zaktualizuj przestrzeń nazw do odpowiednika .NET MAUI. Aby uzyskać więcej informacji, zobacz Zmiany przestrzeni nazw. |
| Interfejs API nie istnieje. | Zaktualizuj użycie interfejsu API do odpowiednika interfejsu MAUI platformy .NET. Aby uzyskać więcej informacji, zobacz Zmiany interfejsu API. |
| Aplikacja nie zostanie wdrożona. | Upewnij się, że wymagany projekt platformy został ustawiony na wdrożenie w programie Visual Studio Configuration Manager. |
| Aplikacja nie zostanie uruchomiona. | Zaktualizuj klasę punktu wejścia każdego projektu platformy i punkt wejścia aplikacji. Aby uzyskać więcej informacji, zobacz Bootstrap twoja zmigrowana aplikacja. |
| CollectionView nie przewija się. | Sprawdź układ kontenera i mierzony rozmiar elementu CollectionView. Domyślnie kontrolka zajmie tyle miejsca, ile pozwala kontener. Ograniczenie Grid elementów podrzędnych o własnym rozmiarze. StackLayout Jednak pozwala dzieciom zabrać miejsce poza granice. |
| Wyskakujące okienko jest wyświetlane pod stroną w systemie iOS. | W Xamarin.Formssystemie wszystkie wyskakujące okienka w systemie iOS to UIWindow wystąpienia, ale w wyskakujących oknach podręcznych platformy .NET MAUI są wyświetlane, lokalizując bieżące prezentowanie ViewController i wyświetlając wyskakujące okienko za PresentViewControllerAsyncpomocą polecenia . W wtyczkach, takich jak Mopups, aby upewnić się, że wyskakujące okienka są poprawnie wyświetlane, należy wywołać DisplayAlertmetodę , DisplayActionSheetlub DisplayPromptAsync z ContentPage okna podręcznego używanego w oknie podręcznym Mopup . |
| BoxView nie jest wyświetlany. | Domyślny rozmiar elementu BoxView Xamarin.Forms to 40x40. Domyślny rozmiar obiektu BoxView w programie .NET MAUI jest 0x0. Ustaw WidthRequest wartość i HeightRequest na 40. |
| Brak wypełnienia, marginesu lub odstępu w układzie. | Dodaj wartości domyślne do projektu na podstawie zasobu w stylu .NET MAUI. Aby uzyskać więcej informacji, zobacz Zmiany wartości domyślnej z Xamarin.Forms. |
| Układ niestandardowy nie działa. | Kod układu niestandardowego wymaga aktualizacji, aby działał w programie .NET MAUI. Aby uzyskać więcej informacji, zobacz Zmiany układu niestandardowego. |
| Niestandardowy moduł renderowania nie działa. | Kod modułu renderowania wymaga aktualizacji, aby działał w programie .NET MAUI. Aby uzyskać więcej informacji, zobacz Use custom renderers in .NET MAUI (Używanie niestandardowych programów renderujących na platformie .NET MAUI). |
| Efekt nie działa. | Kod efektu wymaga aktualizacji, aby działał w programie .NET MAUI. Aby uzyskać więcej informacji, zobacz Use effects in .NET MAUI (Używanie efektów w programie .NET MAUI). |
| SkiaSharp kod nie działa. | SkiaSharp Kod wymaga drobnych aktualizacji, aby działały w programie .NET MAUI. Aby uzyskać więcej informacji, zobacz Ponowne używanie SkiaSharp kodu na platformie .NET MAUI. |
| Nie można uzyskać dostępu do wcześniej utworzonych danych właściwości aplikacji. | Migrowanie danych właściwości aplikacji do preferencji .NET MAUI. Aby uzyskać więcej informacji, zobacz Migrowanie danych ze słownika Xamarin.Forms właściwości aplikacji do preferencji .NET MAUI. |
| Nie można uzyskać dostępu do wcześniej utworzonych bezpiecznych danych magazynu. | Migrowanie bezpiecznych danych magazynu do programu .NET MAUI. Aby uzyskać więcej informacji, zobacz Migrowanie z Xamarin.Essentials bezpiecznego magazynu do bezpiecznego magazynu programu .NET MAUI. |
| Nie można uzyskać dostępu do wcześniej utworzonych danych śledzenia wersji. | Migrowanie danych śledzenia wersji do programu .NET MAUI. Aby uzyskać więcej informacji, zobacz Migrowanie danych śledzenia wersji z Xamarin.Forms aplikacji do aplikacji .NET MAUI. |
