Manuelles Upgrade einer Xamarin.Forms-App zu einer projektübergreifenden .NET MAUI-App

Das Upgrade einer Multiprojekt-Xamarin.Forms-App auf eine Multiprojekt-.NET Multiplatform App UI (.NET MAUI)-App erfolgt in denselben Schritten wie bei einem Xamarin.Android- und Xamarin.iOS-Projekt, mit zusätzlichen Schritten, um die Vorteile der Änderungen in .NET MAUI zu nutzen.

In diesem Artikel wird beschrieben die manuelle Migration eines Xamarin.Forms-Bibliotheksprojekts in ein .NET MAUI-Bibliotheksprojekt. Bevor Sie dies tun, müssen Sie Ihre Xamarin.Forms-Plattformprojekte so aktualisieren, dass es sich um Projekte im SDK-Stil handelt. SDK-Projekte sind das gleiche Projektformat, das von allen .NET-Workloads verwendet wird, und im Vergleich zu vielen Xamarin-Projekten sind sie viel weniger umfangreich. Informationen zum Aktualisieren Ihrer App-Projekte finden Sie unter Upgraden von Xamarin.Android-, Xamarin.iOS- und Xamarin.Mac-Projekten auf .NET, Xamarin.Android-Projektmigration, Xamarin Apple-Projektmigration und Xamarin.Forms-UWP-Projektmigration.

Um ein Xamarin.Forms-Bibliotheksprojekt in ein .NET MAUI-Bibliotheksprojekt zu migrieren, müssen Sie:

Um den Upgradevorgang zu vereinfachen, sollten Sie ein neues .NET MAUI-Bibliotheksprojekt mit demselben Namen wie Ihr Xamarin.Forms Bibliotheksprojekt erstellen und dann in Code, Konfiguration und Ressourcen kopieren. 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 eines neuen Projekts

Erstellen Sie in Visual Studio ein neues .NET MAUI-Klassenbibliotheksprojekt mit demselben Namen wie Ihr Xamarin.Forms-Bibliotheksprojekt. Dieses Projekt wird den Code Ihres Xamarin.Forms-Bibliotheksprojekts enthalten. Wenn Sie die Projektdatei öffnen, wird bestätigt, dass Sie ein Projekt im Stil des .NET SDK haben:

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

Fügen Sie in Ihren Plattformprojekten einen Verweis auf dieses neue Bibliotheksprojekt hinzu. Kopieren Sie dann Ihre Xamarin.Forms-Bibliotheksdateien in das .NET MAUI-Bibliotheksprojekt.

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:

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

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:

Darüber hinaus sind alle numerischen Werte in einem Microsoft.Maui.Graphics.Color float und nicht double wie in Xamarin.Forms.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:

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" });

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:

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:

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

Außerdem wird die Außerkraftsetzung von Page.OnAppearing in Xamarin.Forms auf Android aufgerufen, wenn eine App im Hintergrund und dann im Vordergrund ausgeführt wird. Diese Außerkraftsetzung wird bei iOS und Windows jedoch nicht im selben Szenario aufgerufen. In .NET MAUI wird die OnAppearing()-Außerkraftsetzung nicht auf Plattformen aufgerufen, wenn eine App zunächst im Hintergrund und dann im Vordergrund ausgeführt wird. Stattdessen sollten Sie unter Window auf Lebenszyklusereignissen lauschen, um benachrichtigt zu werden, wenn eine App wieder im Vordergrund ausgeführt wird. Weitere Informationen finden Sie unter .NET MAUI – Window-Klasse.

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

Bootstrappen Ihrer migrierten App

Wenn Sie eine Xamarin.Forms App manuell auf .NET MAUI aktualisieren, müssen Sie die .NET MAUI-Unterstützung in jedem Plattformprojekt aktivieren, die Einstiegspunktklasse jedes Plattformprojekts aktualisieren und dann das Bootstrapping Ihrer .NET MAUI-App konfigurieren.

Aktivieren von .NET MAUI in Plattformprojekten

Bevor Sie die Einstiegspunktklasse jedes Plattformprojekts aktualisieren, müssen Sie zuerst die .NET MAUI-Unterstützung aktivieren. Legen Sie hierzu die $(UseMaui)-Buildeigenschaft in jedem Plattformprojekt auf true fest:

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

Hinzufügen von Paketverweisen

In .NET 8 wird .NET MAUI als .NET-Workload und als mehrere NuGet-Pakete ausgeliefert. Der Vorteil dieses Ansatzes besteht darin, dass Sie Ihre Projekte einfach an bestimmte Versionen anheften können, während Sie gleichzeitig eine Vorschau auf unveröffentlichte oder experimentelle Builds erhalten.

Sie sollten die folgenden expliziten Paketverweise zu <ItemGroup> in jeder Projektdatei hinzufügen:

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

Die Variable $(MauiVersion) wird von der Version von .NET MAUI referenziert, die Sie installiert haben. Sie können dies überschreiben, indem Sie die $(MauiVersion)-Buildeigenschaft zu jeder Projektdatei hinzufügen:

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

Android-Projektkonfiguration

Aktualisieren Sie in Ihrem .NET MAUI Android-Projekt die Klasse MainApplication so, dass sie dem unten stehenden Code entspricht:

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();
    }
}

Aktualisieren Sie auch die Klasse MainActivity, damit sie von MauiAppCompatActivity erbt:

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);
        }
    }
}

Aktualisieren Sie dann Ihre Manifestdatei, um anzugeben, dass minSdKVersion 21 ist, was die minimale Android SDK-Version ist, die von .NET MAUI benötigt wird. Dies kann durch Änderung des Knotens <uses-sdk /> erreicht werden, der ein untergeordnetes Element des Knotens <manifest> ist:

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

iOS-Projektkonfiguration

Aktualisieren Sie in Ihrem .NET MAUI iOS-Projekt die Klasse AppDelegate so, dass sie von MauiUIApplicationDelegate erbt:

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();
    }
}

Aktualisieren Sie dann Info.plist, sodass MinimumOSVersion 11.0 ist, was die minimale iOS-Version ist, die von .NET MAUI benötigt wird.

UWP-Projektkonfiguration

Passen Sie in Ihrem .NET MAUI-Projekt für WinUI 3 die Datei App.xaml an den folgenden Code an:

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

Passen Sie außerdem App.xaml.cs an den folgenden Code an:

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();
}

Fügen Sie dann dem Ordner Properties des Projekts eine launchSettings.json-Datei hinzu, und fügen Sie der Datei den folgenden JSON-Code hinzu:

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

Anwendungseinstiegspunkt

.NET MAUI-Apps verfügen über einen einzigen plattformübergreifenden App-Einstiegspunkt. Jeder Plattform-Einstiegspunkt ruft eine CreateMauiApp-Methode der statischen MauiProgram-Klasse auf und gibt ein MauiApp zurück.

Fügen Sie daher eine neue Klasse mit dem Namen MauiProgram hinzu, die den folgenden Code enthält:

namespace YOUR_NAMESPACE_HERE;

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

        return builder.Build();
    }
}

Wenn plattformspezifische Dienste vorhanden sind, die zu .NET MAUI migriert werden müssen, verwenden Sie die AddTransient(IServiceCollection, Type)-Methode, um der angegebenen IServiceCollection-Schnittstelle einen vorübergehenden Dienst des angegebenen Typs hinzuzufügen.

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:

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.

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

Weitere Informationen

• Portierung von .NET Framework auf .NET
• .NET-Upgrade-Assistent