Freigeben über

Manuelles Upgrade einer Xamarin.Forms-App zu einer .NET MAUI-App mit einem Projekt

  • Artikel

Um eine Xamarin.Forms-App in eine .NET Multi-platform App UI (.NET MAUI) App für ein einzelnes Projekt zu migrieren, müssen Sie folgendes tun:

  • Aktualisieren Sie Ihre Xamarin.Forms-App, um Xamarin.Forms zu verwenden 5.
  • Aktualisieren Sie alle Abhängigkeiten auf die neueste Version.
  • Stellen Sie sicher, dass die App weiterhin funktioniert.
  • Erstellen Sie eine .NET MAUI-App.
  • Kopieren Sie Code und Konfiguration aus der Xamarin.Forms-App in die .NET MAUI-App.
  • Kopieren Sie Ressourcen aus Ihrer Xamarin.Forms-App in die .NET MAUI-App.
  • Aktualisieren von Namespaces.
  • Behandeln Sie alle API-Änderungen.
  • Aktualisieren oder ersetzen Sie inkompatible Abhängigkeiten durch .NET 8-Versionen.
  • Kompilieren und Testen Der App.

Um den Upgrade-Prozess zu vereinfachen, sollten Sie eine neue .NET MAUI-App mit demselben Namen wie Ihre Xamarin.Forms-App erstellen und dann Ihren Code, Ihre Konfiguration und Ihre Ressourcen hineinkopieren. Dies ist der unten beschriebene Ansatz.

Aktualisieren Ihrer Xamarin.Forms-App

Bevor Sie Ihre Xamarin.Forms-App auf .NET MAUI aktualisieren, sollten Sie zunächst Ihre Xamarin.Forms-App aktualisieren, um Xamarin.Forms 5 zu verwenden, und sicherstellen, dass sie weiterhin korrekt läuft. Darüber hinaus sollten Sie die Abhängigkeiten, die Ihre App verwendet, auf die neuesten Versionen aktualisieren.

Dadurch wird der restliche Migrationsprozess vereinfacht, da die API-Unterschiede zwischen Xamarin.Forms und .NET MAUI minimiert werden und sichergestellt wird, dass Sie .NET-kompatible Versionen Ihrer Abhängigkeiten verwenden, falls diese existieren.

Erstellen einer .NET MAUI-App

Erstellen Sie in Visual Studio eine neue .NET MAUI-App mit demselben Namen wie Ihre Xamarin.Forms-App:

Screenshot der Erstellung einer .NET MAUI-App in Visual Studio

Wenn Sie die Projektdatei öffnen, wird bestätigt, dass Sie ein Projekt im Stil des .NET SDK haben.

Code in die .NET MAUI-App kopieren

Der gesamte plattformübergreifende Code aus Ihrem Xamarin.Forms-Bibliotheksprojekt sollte in Ihr .NET MAUI-Appsprojekt in gleichnamige Ordner und Dateien kopiert werden.

Benutzerdefinierte Renderer können entweder in einer .NET MAUI-App wiederverwendet oder in einen .NET MAUI-Handler migriert werden. Weitere Informationen finden Sie unter Wiederverwendung von benutzerdefinierten Renderern in .NET MAUI und Migrieren eines Xamarin.Forms benutzerdefinierten Renderers zu einem .NET MAUI-Handler.

Effekte können in einer .NET MAUI-App wiederverwendet werden. Weitere Informationen finden Sie unter Wiederverwendungseffekte.

Hinweis

Sie können Ihre Xamarin.Forms-Namespaces schnell auf Microsoft.Maui aktualisieren, indem Sie Schnelle Aktionen in Visual Studio verwenden, vorausgesetzt, Sie haben Upgrade-Assistent installiert.

Plattformspezifischer Code

Ein .NET MAUI-Appsprojekt enthält einen Ordner Plattformen, wobei jeder untergeordnete Ordner eine Plattform darstellt, die .NET MAUI ansteuern kann:

Screenshot der Plattformordner

Die Ordner für jede Plattform enthalten plattformspezifische Ressourcen und den Code, der die App auf jeder Plattform startet:

Screenshot des plattformspezifischen Codes

Der Code und die darin enthaltenen Ordner aus Ihren Xamarin.Forms-Hauptprojekten sollten in diese Ordner kopiert werden:

  • Der Code aus dem Xamarin.Forms Android-Hauptprojekten sollte in den Ordner Platform\Android des .NET MAUI-App-Projekts kopiert werden. Kopieren Sie außerdem jeglichen benutzerdefinierten Code aus Ihren Xamarin.FormsMainActivity- und MainApplication-Klassen in dieselben Klassen in Ihrem .NET MAUI-Appsprojekt.

  • Der Code aus dem Xamarin.Forms iOS-Hauptprojekt sollte in den Ordner Platforms\iOS des .NET MAUI-App-Projekts kopiert werden. Kopieren Sie außerdem jeglichen benutzerdefinierten Code aus Ihrer Xamarin.FormsAppDelegate-Klasse in dieselbe Klasse in Ihrem .NET MAUI-App-Projekt.

    Hinweis

    Eine Liste der bahnbrechenden Änderungen in .NET for iOS finden Sie unter Breaking Changes in .NET for iOS.

  • Der Code aus dem Xamarin.Forms UWP-Kopfprojekt sollte in den Ordner Platforms\Windows des .NET MAUI-App-Projekts kopiert werden. Kopieren Sie außerdem jeglichen benutzerdefinierten Code aus Ihrer Xamarin.FormsApp-Klasse in dieselbe Klasse in Ihrem .NET MAUI-App-Projekt.

Das Buildsystem bezieht zum Zeitpunkt der Erstellung nur den Code aus jedem Ordner ein, wenn es für die jeweilige Plattform erstellt wird. Wenn Sie zum Beispiel für Android bauen, werden die Dateien im Ordner Platforms\Android in das App-Paket eingebaut, aber die Dateien in den anderen Platforms-Ordnern werden nicht eingebaut. Dieser Ansatz verwendet Multi-Targeting, um mehrere Plattformen mit einem einzigen Projekt zu erreichen. .NET MAUI-Apps können auch auf der Grundlage Ihrer eigenen Kriterien für Dateinamen und Ordner auf mehrere Ziele ausgerichtet werden. Dadurch können Sie Ihr .NET MAUI-Appsprojekt so strukturieren, dass Sie Ihren Plattformcode nicht in Unterordnern des Ordners Platforms unterbringen müssen. Weitere Informationen finden Sie unter Konfigurieren von Multi-Targeting.

Kopieren der Konfiguration in die .NET MAUI-App

Jede Plattform verwendet ihre eigene App-Manifestdatei, um Informationen wie den App-Titel, die ID, die Version und mehr anzugeben. NET MAUI-Einzelprojekt ermöglicht es Ihnen, diese gemeinsamen Appsdaten an einem einzigen Ort in der Projektdatei anzugeben.

Um die gemeinsamen App-Manifestdaten für ein Projekt festzulegen, öffnen Sie das Kontextmenü für das Projekt im Projektmappen-Explorer und wählen Sie anschließend Eigenschaften aus. Der App-Titel, die ID und die Version können dann in MAUI Shared > Allgemein angegeben werden:

Screenshot des .NET MAUI-App-Manifests

Zum Zeitpunkt der Erstellung werden die gemeinsamen App-Manifestdaten mit den plattformspezifischen Daten in der nativen App-Manifestdatei zusammengeführt, um die Manifestdatei für das App-Paket zu erstellen. Weitere Informationen finden Sie unter Projektkonfiguration in .NET MAUI – MAUI Shared.

Die restlichen Daten aus Ihren Xamarin.Forms-Appsmanifesten sollten in Ihr .NET MAUI-Appsmanifest kopiert werden:

  • Kopieren Sie unter Android alle zusätzlichen Daten aus der Datei AndroidManifest.xml in Ihrem Xamarin.Forms Android-Hauptprojekt in die Datei Platforms\Android\AndroidManifest.xml in Ihrem .NET MAUI-App-Projekt.
  • Unter iOS kopieren Sie alle zusätzlichen Daten aus der Datei Info.plist in Ihrem Xamarin.Forms iOS-Hauptprojekt in die Datei Platforms\iOS\Info.plist in Ihrem .NET MAUI-App-Projekt. Kopieren Sie außerdem die Datei Entitlements.plist in Ihrem Xamarin.Forms iOS-Hauptprojekt in den Ordner Platforms\iOS in Ihrem .NET MAUI-App-Projekt.
  • Kopieren Sie unter Windows zusätzliche Daten aus der Datei Package.appxmanifest in Ihrem Xamarin.Forms UWP-Kopfprojekt in die Datei Platforms\Windows\Package.appxmanifest in Ihrem .NET MAUI-App-Projekt.

Kopieren von Ressourcen in die .NET MAUI-App

NET MAUI ermöglicht es, Ressourcendateien an einem einzigen Ort zu speichern, während sie auf jeder Plattform genutzt werden. Dazu gehören Schriftarten, Bilder, das Appssymbol, der Startbildschirm, Rohdaten und CSS-Dateien für die Gestaltung von .NET MAUI-Apps.

Ressourcendateien sollten in der Regel im Ordner Ressourcen Ihres .NET MAUI-Appsprojekts oder in untergeordneten Ordnern des Ordners Ressourcen abgelegt werden und müssen ihre Build-Aktion korrekt eingestellt haben. Die folgende Tabelle zeigt die Build-Aktionen für jeden Ressourcendateityp:

Ressource Buildvorgang
App-Symbol MauiIcon
Schriftarten MauiFont
Bilder MauiImage
Begrüßungsbildschirm MauiSplashScreen
Rohressourcen MauiAsset
CSS-Dateien MauiCss

Hinweis

XAML-Dateien werden ebenfalls in Ihrem .NET MAUI-Appsprojekt gespeichert und erhalten automatisch die MauiXaml Build-Aktion. In der Regel werden jedoch nur XAML-Ressourcenverzeichnisse im Ordner Ressourcen des Appsprojekts abgelegt.

Der folgende Screenshot zeigt einen typischen Ressourcen-Ordner, der Unterordner für jeden Ressourcentyp enthält:

Screenshot der Bild- und Schriftartressourcen

Die Build-Aktion für eine Ressourcendatei wird korrekt gesetzt, wenn die Ressource dem richtigen Ressourcen-Unterordner hinzugefügt wurde.

Wichtig

Plattformspezifische Ressourcen haben Vorrang vor den entsprechenden gemeinsamen Ressourcen. Wenn Sie zum Beispiel ein Android-spezifisches Bild unter Platforms\Android\Resources\drawable-xhdpi\logo.png haben und auch ein gemeinsames Resources\Images\logo.svg-Bild bereitstellen, wird die Scalable Vector Graphics (SVG)-Datei verwendet, um die erforderlichen Android-Bilder zu generieren, mit Ausnahme des XHDPI-Bildes, das bereits als plattformspezifisches Bild existiert.

App-Symbole

Ihr Xamarin.Forms-App-Symbol sollte zu Ihrem .NET MAUI App-Projekt hinzugefügt werden, indem Sie das Bild in den Ordner Resources\AppIcon des Projekts ziehen, wo seine Build-Aktion automatisch auf MauiIcon gesetzt wird. Bei der Erstellung wird die Größe des App-Symbols an die richtige Größe für die Zielplattform und das Zielgerät angepasst. App-Symbole werden auf mehrere Auflösungen angepasst, da sie mehrfach verwendet werden, unter anderem zur Darstellung der App auf dem Gerät und im App-Store.

Weitere Informationen finden Sie unter Hinzufügen eines Appssymbols zu einem .NET MAUI-Appsprojekt.

Begrüßungsbildschirm

Wenn Ihre Xamarin.Forms App einen Begrüßungsbirldschirm hat, sollte dieser zu Ihrem .NET MAUI App-Projekt hinzugefügt werden, indem Sie das Bild in den Ordner Resources\Splash des Projekts ziehen, wo seine Build-Aktion automatisch auf MauiSplashScreen gesetzt wird. Bei der Erstellung wird das Bild des Startbildschirms auf die richtige Größe für die Zielplattform und das Zielgerät angepasst.

Weitere Informationen finden Sie unter Hinzufügen eines Begrüßungsbildschirms zu einem .NET MAUI-Appsprojekt.

Bilder

Geräte haben eine Reihe von Bildschirmgrößen und -dichten, und jede Plattform verfügt über Funktionen zur Anzeige von dichteabhängigen Bildern. In Xamarin.Forms werden dichteabhängige Bilder typischerweise in Kopfprojekten platziert und nehmen eine plattformspezifische Namenskonvention an. Es gibt zwei Ansätze, um diese Bilder nach .NET MAUI zu migrieren.

Es wird empfohlen, die höchstauflösende Version jedes Bildes aus Ihrer Xamarin.Forms-Lösung in Ihr .NET-MAUI-App-Projekt zu kopieren, indem Sie es in den Ordner Resources\Images des Projekts ziehen, wo seine Build-Aktion automatisch auf MauiImage gesetzt wird. Außerdem muss das BaseSize-Attribut jedes Bitmap-Bildes gesetzt werden, um sicherzustellen, dass eine Größenänderung erfolgt. Damit entfällt die Notwendigkeit, mehrere Versionen jedes Bildes auf jeder Plattform zu haben. Zum Zeitpunkt der Erstellung werden die Bilder dann in mehrere dichteabhängige Bilder umgewandelt, die den Anforderungen der Plattform entsprechen. Weitere Informationen finden Sie unter Hinzufügen von Bildern zu einem .NET MAUI-Appsprojekt.

Alternativ können Sie dichteabhängige Bilder aus Ihrer Xamarin.Forms-Lösung in gleichnamige Ordner im Ordner Platforms\{Platform} Ihres .NET MAUI-Appsprojekts kopieren und ihre Build-Aktionen auf die Build-Aktionen setzen, die in Ihrer Xamarin.Forms-Lösung verwendet werden. In der folgenden Tabelle sind die Speicherorte von Beispielbildern für eine Xamarin.Forms-Lösung und der entsprechende Speicherort in einem .NET MAUI-Appsprojekt aufgeführt:

Xamarin.Forms-Imagespeicherort .NET MAUI-Bildspeicherort .NET MAUI Plattform-Image-Build-Aktion
{MyApp.Android}\Resources\drawable-xhdpi\image.png Platforms\Android\Resources\drawable-xhdpi\image.png AndroidResource
{MyApp.iOS}\image.jpg *Platforms\iOS\Resources\image.jpg BundleResource
{MyApp.UWP}\Assets\Images\image.gif *Platforms\Windows\Assets\Images\image.gif Inhalt

Vorausgesetzt, Sie haben die gleiche Namenskonvention für das Bild wie in Ihrer Xamarin.Forms-Lösung übernommen, wird das passende Bild zur Laufzeit auf der Grundlage der Fähigkeiten des Geräts ausgewählt. Der Nachteil dieses Ansatzes ist, dass Sie immer noch mehrere Versionen jedes Bildes auf jeder Pl

Schriftarten

Alle Schriftarten aus Ihrer Xamarin.Forms-Lösung können zu Ihrer .NET MAUI-Lösung hinzugefügt werden, indem Sie sie in den Ordner Resources\Fonts Ihres .NET MAUI-App-Projekts ziehen, wo ihre Build-Aktion automatisch auf MauiFont gesetzt wird.

Weitere Informationen finden Sie unter Schriftarten.

CSS-Dateien

Alle CSS-Dateien aus Ihrer Xamarin.Forms-Lösung können zu Ihrer .NET MAUI-Lösung hinzugefügt werden, indem Sie sie in einen gleichnamigen Ordner ziehen und ihre Build-Aktion im Fenster Eigenschaften auf MauiCss setzen.

Weitere Informationen zur Verwendung von CSS-Dateien in einer .NET MAUI-App finden Sie unter Apps mit Cascading Style Sheets gestalten.

Rohressourcen

Alle Raw-Asset-Dateien, wie HTML, JSON und Video, sollten von Ihrer Xamarin.Forms-Lösung in Ihr .NET MAUI-App-Projekt kopiert werden, indem Sie sie in den Ordner Resources\Raw Ihres Projekts ziehen, wo ihre Build-Aktion automatisch auf MauiAsset gesetzt wird.

Lokalisierte Ressourcen

In einer .NET MAUI-App werden Zeichenketten nach demselben Ansatz wie in einer Xamarin.Forms-App lokalisiert. Daher sollten Ihre .NET-Ressourcendateien (.resx) von Ihrer Xamarin.Forms-Lösung in einen gleichnamigen Ordner in Ihrer .NET MAUI-Lösung kopiert werden. Dann muss die neutrale Sprache Ihrer .NET MAUI-App angegeben werden. Weitere Informationen finden Sie unter Bestimmen der neutralen Sprache der App.

Hinweis

.NET-Ressourcendateien müssen nicht im Ordner Ressourcen Ihres .NET MAUI-Appsprojekts abgelegt werden.

In einer .NET-MAUI-App werden Bilder mit demselben Ansatz wie in einer Xamarin.Forms-App lokalisiert. Daher sollten Ihre lokalisierten Bilder und die Ordner, in denen sie sich befinden, von Ihrer Xamarin.Forms-Lösung in Ihr .NET MAUI-App-Projekt kopiert werden:

  • Unter Android ist der Stammordner in Ihrem .NET MAUI-App-Projekt für lokalisierte Bilder Platforms\Android\Resources.
  • Unter iOS ist der Stammordner in Ihrem .NET MAUI-App-Projekt für lokalisierte Bilder Platforms\iOS\Resources.
  • Unter Windows lautet der Stammordner in Ihrem .NET MAUI-Appsprojekt für lokalisierte Bilder Plattformen\Windows\Assets\Images.

Bei lokalisierten Bildern sollten die Build-Aktionen auf die Build-Aktionen gesetzt werden, die in Ihrer Xamarin.Forms-Lösung verwendet werden. Weitere Informationen finden Sie unter Bilder lokalisieren.

In einer .NET MAUI-App werden die Appsnamen nach demselben Ansatz wie in einer Xamarin.Forms-App lokalisiert:

  • Unter Android kann der lokalisierte App-Name mithilfe einer ordnerbasierten Namenskonvention im Ordner Platforms\Android\Resources gespeichert werden. Die Lokalisierungsordner und -dateien der App-Namen sollten aus Ihrer Xamarin.Forms-Lösung in diesen Ordner kopiert werden.
  • Unter iOS wird der lokalisierte App-Name unter Verwendung einer ordnerbasierten Namenskonvention im Ordner Platforms\iOS\Resources gespeichert. Die Lokalisierungsordner und -dateien der App-Namen sollten aus Ihrer Xamarin.Forms-Lösung in diesen Ordner kopiert werden.
  • Unter Windows wird der lokalisierte Appsname im Manifest des Appspakets gespeichert.

Weitere Informationen finden Sie unter Lokalisieren des Appsnamens. Weitere Informationen zur Lokalisierung von .NET MAUI-Apps finden Sie unter Lokalisierung.

Namespaceänderungen

Die Namensräume haben sich mit dem Übergang von Xamarin.Forms zu .NET MAUI geändert, und die Xamarin.Essentials-Funktionen sind jetzt Teil von .NET MAUI. Führen Sie zum Erstellen von Namespaceupdates einen Such- und Ersetzungsvorgang für die folgenden Namespaces aus:

Xamarin.Forms-Namespace .NET MAUI-Namespace(s)
Xamarin.Forms Microsoft.Maui und Microsoft.Maui.Controls
Xamarin.Forms.DualScreen Microsoft.Maui.Controls.Foldable
Xamarin.Forms.Maps Microsoft.Maui.Controls.Maps und 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

.NET MAUI-Projekte verwenden implizite global using-Anweisungen. Mit dieser Funktion können Sie using-Anweisungen für den Xamarin.Essentials-Namespace entfernen, ohne sie durch die entsprechenden .NET MAUI-Namensräume ersetzen zu müssen.

Darüber hinaus hat sich der Standard-XAML-Namespace von http://xamarin.com/schemas/2014/forms in Xamarin.Forms zu http://schemas.microsoft.com/dotnet/2021/maui in .NET MAUI geändert. Daher sollten Sie alle Vorkommen von xmlns="http://xamarin.com/schemas/2014/forms" durch xmlns="http://schemas.microsoft.com/dotnet/2021/maui" ersetzen.

Hinweis

Sie können Ihre Xamarin.Forms-Namespaces schnell auf Microsoft.Maui aktualisieren, indem Sie Schnelle Aktionen in Visual Studio verwenden, vorausgesetzt, Sie haben Upgrade-Assistent installiert.

API-Änderungen

Einige APIs haben sich durch den Übergang von Xamarin.Forms zu .NET MAUI geändert. Dafür gibt es mehrere Gründe, darunter die Beseitigung doppelter Funktionalität, die dadurch entstanden ist, dass Xamarin.Essentials Teil von .NET MAUI geworden ist, und die Sicherstellung, dass APIs den .NET-Namensrichtlinien folgen. Diese Faktoren werden in den folgenden Abschnitten erläutert.

Farbänderungen

In Xamarin.Forms ermöglicht die Xamarin.Forms.Color-Struktur die Konstruktion von Color-Objekten unter Verwendung von double-Werten und bietet benannte Farben, wie Xamarin.Forms.Color.AliceBlue. In .NET MAUI wurde diese Funktionalität in die Klasse Microsoft.Maui.Graphics.Color und die Klasse Microsoft.Maui.Graphics.Colors aufgeteilt.

Mit der Klasse Microsoft.Maui.Graphics.Color im Microsoft.Maui.Graphics-Namespace können Sie Color-Objekte mit float-Werten, byte-Werten und int-Werten konstruieren. Die Klasse Microsoft.Maui.Graphics.Colors, die sich ebenfalls im Microsoft.Maui.Graphics-Namespace befindet, bietet weitgehend die gleichen benannten Farben. Verwenden Sie z. B. Colors.AliceBlue, um die AliceBlue Farbe anzugeben.

Die folgende Tabelle zeigt die API-Änderungen zwischen der Xamarin.Forms.Color struct und der Microsoft.Maui.Graphics.Color-Klasse:

Xamarin.Forms-API .NET MAUI-App Kommentar
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-Eigenschaft wurde durch eine Methode in .NET MAUI ersetzt.
Xamarin.Forms.Color.Saturation Microsoft.Maui.Graphics.Color.GetSaturation Xamarin.Forms-Eigenschaft wurde durch eine Methode in .NET MAUI ersetzt.
Xamarin.Forms.Color.Luminosity Microsoft.Maui.Graphics.Color.GetLuminosity Xamarin.Forms-Eigenschaft wurde durch eine Methode in .NET MAUI ersetzt.
Xamarin.Forms.Color.Default Keine .NET MAUI-Entsprechung. Stattdessen werden Microsoft.Maui.Graphics.Color-Objekte standardmäßig auf null gesetzt.
Xamarin.Forms.Color.Accent Keine .NET MAUI-Entsprechung.
Xamarin.Forms.Color.FromHex Microsoft.Maui.Graphics.Color.FromArgb Microsoft.Maui.Graphics.Color.FromHex ist veraltet und wird in einer zukünftigen Version entfernt werden.

Darüber hinaus sind alle numerischen Werte in einem Microsoft.Maui.Graphics.Color float und nicht double wie in Xamarin.Forms.Color.

Hinweis

Im Gegensatz zu Xamarin.Forms gibt es bei Microsoft.Maui.Graphics.Color keine implizite Umwandlung in System.Drawing.Color.

Layoutänderungen

In der folgenden Tabelle sind die Layout-APIs aufgeführt, die bei der Umstellung von Xamarin.Forms auf .NET MAUI entfernt wurden:

Xamarin.Forms-API .NET MAUI-App Kommentare
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add Die Add Überladung, die 3 Argumente akzeptiert, ist in .NET MAUI nicht vorhanden.
Xamarin.Forms.Grid.IGridList<T>.AddHorizontal Keine .NET MAUI-Entsprechung.
Xamarin.Forms.Grid.IGridList<T>.AddVertical Keine .NET MAUI-Entsprechung.
Xamarin.Forms.RelativeLayout Microsoft.Maui.Controls.Compatibility.RelativeLayout In .NET MAUI existiert RelativeLayout nur als Kompatibilitätssteuerung für Benutzer, die von Xamarin.Forms migrieren. Verwenden Sie stattdessen Grid, oder fügen Sie xmlns für den Kompatibilitätsnamensraum hinzu.

Darüber hinaus wird das Hinzufügen von untergeordneten Elementen zu einem Layout im Code in Xamarin.Forms durch Hinzufügen der untergeordneten Elementen zur Children-Sammlung des Layouts erreicht:

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

In .NET MAUI ist die Children-Sammlung für die interne Verwendung durch .NET MAUI bestimmt und sollte nicht direkt manipuliert werden. Daher sollten untergeordnete Elemente im Code direkt zum Layout hinzugefügt werden:

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

Wichtig

Alle Add Layout-Erweiterungsmethoden, wie etwa GridExtensions.Add, werden auf das Layout und nicht auf die Children Sammlung von Layouts angewandt.

Möglicherweise stellen Sie fest, dass beim Ausführen der aktualisierten .NET MAUI-App das Layoutverhalten unterschiedlich ist. Weitere Informationen finden Sie unter Layout-Verhaltensänderungen ab Xamarin.Forms.

Benutzerdefinierte Layoutänderungen

Das Verfahren zur Erstellung eines benutzerdefinierten Layouts in Xamarin.Forms umfasst die Erstellung einer Klasse, die von Layout<View> abgeleitet ist, und das Überschreiben der Methoden VisualElement.OnMeasure und Layout.LayoutChildren. Weitere Informationen finden Sie unter Erstellen eines benutzerdefinierten Layouts in Xamarin.Forms.

In .NET MAUI werden die Layoutklassen von der abstrakten Layout-Klasse abgeleitet. Diese Klasse delegiert plattformübergreifendes Layout und Messungen an eine Layout-Manager-Klasse. Jede Layout-Manager-Klasse implementiert die ILayoutManager-Schnittstelle, die angibt, dass Measure- und ArrangeChildren- Implementierungen bereitgestellt werden müssen:

  • Die Measure-Implementierung ruft IView.Measure für jede Ansicht im Layout auf und gibt die Gesamtgröße des Layouts mit den entsprechenden Einschränkungen zurück.
  • Die ArrangeChildren-Implementierung bestimmt, wo jede Ansicht innerhalb der Grenzen des Layouts platziert werden soll, und ruft für jede Ansicht Arrange mit den entsprechenden Grenzen auf. Der Rückgabewert ist die tatsächliche Größe des Layouts.

Weitere Informationen finden Sie unter Benutzerdefinierte Layouts.

Geräteänderungen

Xamarin.Forms hat eine Xamarin.Forms.Device Klasse, die Ihnen hilft, mit dem Gerät und der Plattform, auf der die App läuft, zu interagieren. Die entsprechende Klasse in .NET MAUI, Microsoft.Maui.Controls.Device, ist veraltet und ihre Funktionalität wird durch mehrere Typen ersetzt.

Die folgende Tabelle zeigt die .NET MAUI-Ersetzungen für die Funktionen der Klasse Xamarin.Forms.Device:

Xamarin.Forms-API .NET MAUI-App Kommentare
Xamarin.Forms.Device.Android Microsoft.Maui.Devices.DevicePlatform.Android
Xamarin.Forms.Device.iOS Microsoft.Maui.Devices.DevicePlatform.iOS
Xamarin.Forms.Device.GTK Keine .NET MAUI-Entsprechung.
Xamarin.Forms.Device.macOS Keine .NET MAUI-Entsprechung. Verwenden Sie stattdessen 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 Keine .NET MAUI-Entsprechung.
Xamarin.Forms.Device.Flags Keine .NET MAUI-Entsprechung.
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 Keine .NET MAUI-Entsprechung.
Xamarin.Forms.Device.GetNamedSize Keine .NET MAUI-Entsprechung.
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 Keine .NET MAUI-Entsprechung.
Xamarin.Forms.Device.SetFlowDirection Microsoft.Maui.Controls.Window.FlowDirection
Xamarin.Forms.Device.StartTimer Microsoft.Maui.Dispatching.DispatcherExtensions.StartTimer oder Microsoft.Maui.Dispatching.Dispatcher.DispatchDelayed

Kartenänderungen

In Xamarin.Forms befinden sich das Map-Steuerelement und die zugehörigen Typen im Xamarin.Forms.Maps-Namespace. In .NET MAUI wurde diese Funktionalität in die Namespaces Microsoft.Maui.Controls.Maps und Microsoft.Maui.Maps verlagert. Einige Eigenschaften wurden umbenannt und einige Typen wurden durch gleichwertige Typen aus Xamarin.Essentials ersetzt.

Die folgende Tabelle zeigt die .NET MAUI-Ersetzungen für die Funktionen im Xamarin.Forms.Maps-Namenspace:

Xamarin.Forms-API .NET MAUI-App Kommentar
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 Keine .NET MAUI-Entsprechung.
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 Mitglieder des Typs Xamarin.Forms.Maps.Position haben sich in den Typ Microsoft.Maui.Devices.Sensors.Location geändert.
Xamarin.Forms.Maps.Geocoder Microsoft.Maui.Devices.Sensors.Geocoding Mitglieder des Typs Xamarin.Forms.Maps.Geocoder haben sich in den Typ Microsoft.Maui.Devices.Sensors.Geocoding geändert.

.NET MAUI hat zwei Map-Typen – Microsoft.Maui.Controls.Maps.Map und Microsoft.Maui.ApplicationModel.Map. Da der Microsoft.Maui.ApplicationModel-Namespace eine der global using-Anweisungen von .NET MAUI ist, müssen Sie bei der Verwendung des Microsoft.Maui.Controls.Maps.Map-Steuerelements im Code die Map-Verwendung vollständig qualifizieren oder einen Alias verwenden.

In XAML sollte eine xmlns-Namespace-Definition für das Map-Steuerelement hinzugefügt werden. Dies ist zwar nicht erforderlich, verhindert aber eine Kollision zwischen den Typen Polygon und Polyline, die sowohl in den Namespaces Microsoft.Maui.Controls.Maps als auch Microsoft.Maui.Controls.Shapes existieren. Weitere Informationen finden Sie unter Anzeigen einer Karte.

Weitere Änderungen

Bei der Umstellung von Xamarin.Forms auf .NET MAUI wurde eine kleine Anzahl anderer APIs konsolidiert. Im folgenden Code sind diese Änderungen dargestellt.

Xamarin.Forms-API .NET MAUI-App Kommentare
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 In Xamarin.Forms nimmt die ApplyQueryAttributes-Methode ein IDictionary<string, string>-Argument an. In .NET MAUI akzeptiert die Methode ApplyQueryAttributes ein Argument IDictionary<string, object>.
Xamarin.Forms.MenuItem.Icon Microsoft.Maui.Controls.MenuItem.IconImageSource Xamarin.Forms.MenuItem.Icon ist die Basisklasse für Xamarin.Forms.ToolbarItem, und so wird ToolbarItem.Icon zu ToolbarItem.IconImageSource.
Xamarin.Forms.OrientationStateTrigger.Orientation Microsoft.Maui.Controls.OrientationStateTrigger.Orientation In Xamarin.Forms ist die Eigenschaft OrientationStateTrigger.Orientation vom Typ Xamarin.Forms.Internals.DeviceOrientation. In .NET MAUI ist die Eigenschaft OrientationStateTrigger.Orientation vom 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 ist die Basisklasse für Microsoft.Maui.Controls.ToolbarItem, und so wird ToolbarItem.Name zu ToolbarItem.Text.

Außerdem wird die Außerkraftsetzung von Xamarin.Forms in Page.OnAppearing auf Android aufgerufen, wenn eine App in den Hintergrund und dann in den Vordergrund gebracht wird. Diese Außerkraftsetzung wird jedoch für iOS und Windows nicht im selben Szenario aufgerufen. In .NET MAUI wird die Außerkraftsetzung von OnAppearing() von keiner Plattform aus aufgerufen, wenn eine App in den Hintergrund und dann in den Vordergrund gebracht wird. Stattdessen sollten Sie auf Window nach Lebenszyklusereignissen lauschen, um benachrichtigt zu werden, wenn eine App zum Vordergrund zurückkehrt. Weitere Informationen finden Sie unter .NET MAUI-Fenster.

Änderungen an nativen Formularen

Native Formulare in Xamarin.Forms ist zu einer nativen Einbettung in .NET MAUI geworden und verwendet einen anderen Initialisierungsansatz und andere Erweiterungsmethoden, um plattformübergreifende Steuerelemente in ihre nativen Typen zu konvertieren. Für weitere Informationen siehe Native Einbettung.

AssemblyInfo-Änderungen

Eigenschaften, die normalerweise in einer AssemblyInfo.cs-Datei festgelegt werden, sind jetzt in Ihrem SDK-Projekt verfügbar. Wir empfehlen, sie in jedem Projekt von AssemblyInfo.cs in Ihre Projektdatei zu migrieren und die Datei AssemblyInfo.cs zu entfernen.

Optional können Sie die Datei AssemblyInfo.cs behalten und die Eigenschaft GenerateAssemblyInfo in Ihrer Projektdatei auf false setzen:

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

Für weitere Informationen über die GenerateAssemblyInfo-Eigenschaft, siehe GenerateAssemblyInfo.

Aktualisieren von App-Abhängigkeiten

Im Allgemeinen sind Xamarin.Forms NuGet-Pakete nicht mit .NET 8 kompatibel, es sei denn, sie wurden unter Verwendung von .NET-Ziel-Framework-Monikern (TFMs) neu kompiliert. Android-Apps können jedoch NuGet-Pakete verwenden, die auf die monoandroid- und monoandroidXX.X-Frameworks abzielen.

Sie können sich vergewissern, dass ein Paket mit .NET 8 kompatibel ist, indem Sie auf der Registerkarte Frameworks in NuGet nachsehen, ob eines der in der folgenden Tabelle aufgeführten kompatiblen Frameworks vorhanden ist:

Kompatible Frameworks Inkompatible Frameworks
net8.0-android, Monoandroid, MonoandroidXX.X
net8.0-ios monotouch, xamarinios, xamarinios10
net8.0-macos monomac, xamarinmac, xamarinmac20
net8.0-tvos xamarintvos
xamarinwatchos

Hinweis

.NET Standardbibliotheken, die keine Abhängigkeiten von den oben aufgeführten inkompatiblen Frameworks haben, sind weiterhin mit .NET 8 kompatibel.

Wenn ein Paket auf NuGet die Kompatibilität mit einem der oben aufgeführten kompatiblen Frameworks angibt, unabhängig davon, ob es auch inkompatible Frameworks enthält, ist das Paket kompatibel. Kompatible NuGet-Pakete können mithilfe des NuGet-Paketmanagers in Visual Studio zu Ihrem .NET MAUI-Bibliotheksprojekt hinzugefügt werden.

Wenn Sie eine .NET 8-kompatible Version eines NuGet-Pakets nicht finden können, sollten Sie:

  • Kompilieren Sie das Paket mit .NET TFMs, wenn Sie den Code besitzen.
  • Suchen Sie nach einer Vorschauversion einer .NET 8-Version des Pakets.
  • Ersetzen Sie die Abhängigkeit durch eine .NET 8-kompatible Alternative.

Kompilieren und Problembehandlung

Sobald die Abhängigkeiten aufgelöst sind, sollten Sie Ihr Projekt erstellen. Alle Fehler führen Sie zu den nächsten Schritten.

Tipp

  • Löschen Sie alle bin- und obj-Ordner aus allen Projekten, bevor Sie Projekte in Visual Studio öffnen und erstellen, insbesondere beim Wechsel der .NET-Version.
  • Löschen Sie die generierte Datei Resource.designer.cs aus dem Android-Projekt.

Die folgende Tabelle enthält Anleitungen zur Behebung häufiger Build- oder Laufzeitprobleme:

Abgang Tipp
Xamarin.* Namespace ist nicht vorhanden. Aktualisieren Sie den Namespace auf das .NET MAUI-Äquivalent. Weitere Informationen finden Sie unter Namespace-Änderungen.
API ist nicht vorhanden. Aktualisieren Sie die API-Verwendung auf das .NET MAUI-Äquivalent. Weitere Informationen finden Sie unter API-Änderungen.
Die App wird nicht bereitgestellt. Stellen Sie sicher, dass das erforderliche Plattformprojekt für die Bereitstellung im Configuration Manager von Visual Studio festgelegt ist.
Die App wird nicht gestartet. Aktualisieren Sie die Einstiegspunktklasse jedes Plattformprojekts und den App-Einstiegspunkt. Weitere Informationen finden Sie unter Bootstrappen Ihrer migrierten App.
CollectionView führt keinen Bildlauf durch. Überprüfen Sie das Layout des Containers und die gemessene Größe des CollectionView. Standardmäßig nimmt das Steuerelement so viel Platz ein, wie der Container zulässt. Ein Grid schränkt ungeordnete Elemente auf seine eigene Größe ein. Ein StackLayout ermöglicht es ungeordneten Elementen jedoch, über seine Grenzen hinaus Raum einzunehmen.
Popup wird unter der Seite unter iOS angezeigt. In Xamarin.Forms sind alle Pop-ups auf iOS UIWindow-Instanzen, aber in .NET werden MAUI-Pop-ups angezeigt, indem die aktuelle Darstellung ViewController gefunden und das Pop-up mit PresentViewControllerAsync angezeigt wird. In Plugins wie Mopups sollten Sie DisplayAlert, DisplayActionSheet oder DisplayPromptAsync aus dem ContentPage aufrufen, das innerhalb des Mopup-Popups verwendet wird, um sicherzustellen, dass Ihre Pop-ups korrekt angezeigt werden.
BoxView nicht angezeigt. Die Standardgröße eines BoxView in Xamarin.Forms ist 40x40. Die Standardgröße einer BoxView in .NET MAUI ist 0x0. Setzen Sie WidthRequest und HeightRequest auf 40.
Beim Layout fehlen Padding, Margin oder Abstand. Fügen Sie Ihrem Projekt Standardwerte auf der Grundlage der .NET MAUI-Stilressource hinzu. Weitere Informationen finden Sie unter Standardwertänderungen von Xamarin.Forms.
Benutzerdefiniertes Layout funktioniert nicht. Benutzerdefinierter Layoutcode muss aktualisiert werden, um in .NET MAUI zu funktionieren. Weitere Informationen finden Sie unter Benutzerdefinierte Layoutänderungen.
Benutzerdefinierter Renderer funktioniert nicht. Der Renderer-Code muss aktualisiert werden, damit er in .NET MAUI funktioniert. Weitere Informationen finden Sie unter Verwenden von benutzerdefinierten Renderern in .NET MAUI.
Effekt funktioniert nicht. Effektcode muss aktualisiert werden, um in .NET MAUI zu funktionieren. Weitere Informationen finden Sie unter Verwenden von Effekten in .NET MAUI.
SkiaSharp-Code funktioniert nicht. SkiaSharp-Code benötigt kleinere Updates, um in .NET MAUI zu funktionieren. Weitere Informationen finden Sie unter Wiederverwenden von SkiaSharp-Code in .NET MAUI.
Auf zuvor erstellte App-Eigenschaftendaten kann nicht zugegriffen werden. Migrieren Sie die Daten der Appseigenschaften in die .NET MAUI-Einstellungen. Weitere Informationen finden Sie unter Migrieren von Daten aus dem Xamarin.Forms App-Eigenschaften-Wörterbuch in .NET MAUI-Einstellungen.
Der Zugriff auf zuvor erstellte sichere Speicherdaten ist nicht möglich. Migrieren Sie die Daten des sicheren Speichers nach .NET MAUI. Weitere Informationen finden Sie unter Migrieren von Xamarin.Essentials sicherem Speicher zu .NET MAUI secure storage.
Auf zuvor erstellte Versionsverfolgungsdaten kann nicht zugegriffen werden. Migrieren Sie die Versionsverfolgungsdaten zu .NET MAUI. Weitere Informationen finden Sie unter Migrieren von Versionsverfolgungsdaten von einer Xamarin.Forms App zu einer .NET MAUI App.