Manuelles Upgrade einer Xamarin.Forms App auf eine .NET MAUI-App mit mehreren Projekten

Das Upgrade einer Multi-Project-Xamarin.Forms-App zu einer .NET Multi-platform App UI (.NET MAUI)-App folgt den gleichen Schritten wie ein Xamarin.Android- und Xamarin.iOS-Projekt, mit zusätzlichen Schritten, um die Vorteile von Änderungen in .NET MAUI zu nutzen.

In diesem Artikel wird beschrieben, wie Sie ein Xamarin.Forms Bibliotheksprojekt manuell zu einem .NET MAUI-Bibliotheksprojekt migrieren. Bevor Sie dies tun, müssen Sie Ihre Xamarin.Forms Plattformprojekte so aktualisieren, dass es sich um PROJEKTE im SDK-Stil handelt. Projekte im SDK-Stil sind dieselbe Projektformatierung, die von allen .NET-Workloads verwendet wird, und sind im Vergleich zu vielen Xamarin-Projekten deutlich weniger ausführlich. Informationen zum Aktualisieren Ihrer App-Projekte finden Sie unter Upgrade Xamarin.Android, Xamarin.iOS und Xamarin.Mac-Projekte auf .NET, Xamarin.Android-Projektmigration, Xamarin Apple-Projektmigration und Xamarin.Forms UWP-Projektmigration.

Um ein Xamarin.Forms Bibliotheksprojekt zu einem .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 aufgeführte Ansatz.

Aktualisieren Sie Ihre Xamarin.Forms-App

Bevor Sie Ihre Xamarin.Forms-App auf .NET MAUI aktualisieren, sollten Sie zuerst Ihre Xamarin.Forms-App auf Xamarin.Forms 5 aktualisieren 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.

Dies wird helfen, den Rest des Migrationsprozesses zu vereinfachen, da es die API-Unterschiede zwischen Xamarin.Forms und .NET MAUI minimieren wird und sicherstellen wird, dass Sie, falls vorhanden, .NET-kompatible Versionen Ihrer Abhängigkeiten verwenden.

Erstellen eines neuen Projekts

Erstellen Sie in Visual Studio ein neues .NET MAUI-Klassenbibliotheksprojekt mit demselben Namen wie Ihr Xamarin.Forms Bibliotheksprojekt. Dieses Projekt hostt den Code aus Ihrem Xamarin.Forms Bibliotheksprojekt. Beim Öffnen der Projektdatei wird bestätigt, dass Sie über ein .NET SDK-Formatprojekt verfügen:

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

Namensraumänderungen

Namespaces wurden beim Wechsel von Xamarin.Forms zu .NET MAUI geändert, und Xamarin.Essentials Funktionen sind jetzt Teil von .NET MAUI. Um Namespace-Updates durchzuführen, führen Sie eine Suche und Ersetzung für die folgenden Namespaces durch:

.NET MAUI-Projekte verwenden implizite global using-Direktiven. Diese Funktion ermöglicht es Ihnen, using-Direktiven für den Xamarin.Essentials-Namensraum zu entfernen, ohne sie durch die entsprechenden .NET MAUI-Namensräume ersetzen zu müssen.

Außerdem 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 beim Wechsel von Xamarin.Forms zu .NET MAUI geändert. Es gibt mehrere Gründe, darunter das Entfernen von doppelter Funktionalität, verursacht durch Xamarin.Essentials, die Teil von .NET MAUI wird, sowie die Sicherstellung, dass APIs den .NET-Namenrichtlinien folgen. Die folgenden Abschnitte erörtern diese Änderungen.

Farbänderungen

In Xamarin.Forms ermöglicht Ihnen die Xamarin.Forms.Color-Struktur, Color-Objekte mithilfe von double-Werten zu erstellen und bietet benannte Farben wie Xamarin.Forms.Color.AliceBlue. In .NET MAUI wurde diese Funktionalität auf die Microsoft.Maui.Graphics.Color-Klasse und die Microsoft.Maui.Graphics.Colors-Klasse aufgeteilt.

Die Microsoft.Maui.Graphics.Color Klasse im Microsoft.Maui.Graphics Namensraum ermöglicht es Ihnen, Color Objekte mithilfe von float Werten, byte Werten und int Werten zu erstellen. Die Microsoft.Maui.Graphics.Colors-Klasse, die sich auch im Microsoft.Maui.Graphics-Namespace befindet, bietet weitgehend die gleichen benannten Farben. Verwenden Sie beispielsweise Colors.AliceBlue, um die AliceBlue-Farbe anzugeben.

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

Zusätzlich sind alle numerischen Werte in einem Microsoft.Maui.Graphics.Colorfloat, statt double wie in Xamarin.Forms.Color verwendet.

Layoutänderungen

Die folgende Tabelle listet die Layout-APIs auf, die beim Wechsel von Xamarin.Forms zu .NET MAUI entfernt wurden.

Darüber hinaus wird das Hinzufügen von Kindern zu einem Layout im Code in Xamarin.Forms dadurch erreicht, dass die Kinder zur Children-Sammlung des Layouts hinzugefügt werden.

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

In .NET MAUI ist die Children-Sammlung für den internen Gebrauch durch .NET MAUI vorgesehen und sollte nicht direkt bearbeitet werden. Daher sollten im Code Kinder direkt zum Layout hinzugefügt werden.

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

Ihnen könnte auffallen, dass das Layout-Verhalten anders ist, wenn Sie Ihre aktualisierte .NET MAUI-App ausführen. Weitere Informationen finden Sie unter Layoutverhaltensänderungen von Xamarin.Forms.

Benutzerdefinierte Layoutänderungen

Der Prozess zum Erstellen eines benutzerdefinierten Layouts in Xamarin.Forms umfasst das Erstellen einer Klasse, die von Layout<View> abgeleitet wird, und das Überschreiben der Methoden VisualElement.OnMeasure und Layout.LayoutChildren. Für weitere Informationen siehe Eigene Layouts erstellen in Xamarin.Forms.

In .NET MAUI leiten sich die Layout-Klassen von der abstrakten Layout Klasse ab. Diese Klasse delegiert plattformübergreifendes Layout und Messungen an eine Layout-Manager-Klasse. Jede Layout-Manager-Klasse implementiert die ILayoutManager-Schnittstelle, die vorgibt, dass Measure- und ArrangeChildren-Implementierungen bereitgestellt werden müssen.

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

Für weitere Informationen siehe Custom layouts.

Geräteänderungen

Xamarin.Forms verfügt über eine Xamarin.Forms.Device-Klasse, die Ihnen hilft, mit dem Gerät und der Plattform zu interagieren, auf der die App ausgeführt wird. 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 Funktionalität in der Xamarin.Forms.Device-Klasse:

Kartenänderungen

In Xamarin.Forms befinden sich die Map-Steuerelemente und zugehörigen Typen im Xamarin.Forms.Maps-Namespace. In .NET MAUI wurde diese Funktionalität in die Microsoft.Maui.Controls.Maps und Microsoft.Maui.Maps Namensräume verschoben. 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 Funktionalität im Xamarin.Forms.Maps-Namespace:

.NET MAUI verfügt über 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, wenn Sie das Microsoft.Maui.Controls.Maps.Map-Steuerelement aus dem Code verwenden, Ihre Verwendung von Map vollständig qualifizieren oder einen -Alias mitverwenden.

In XAML sollte eine xmlns Namensraumdefinition für das Map Steuerelement hinzugefügt werden. Obwohl dies nicht erforderlich ist, verhindert es eine Kollision zwischen den Polygon- und Polyline-Typen, die sowohl im Microsoft.Maui.Controls.Maps- als auch im Microsoft.Maui.Controls.Shapes-Namensraum existieren. ** Weitere Informationen finden Sie unter Display a map.

Andere Änderungen

Eine kleine Anzahl anderer APIs wurde im Zuge des Wechsels von Xamarin.Forms zu .NET MAUI konsolidiert. Die folgende Tabelle zeigt diese Änderungen:

Darüber hinaus wird in Xamarin.Forms das Page.OnAppearing-Override auf Android aufgerufen, wenn eine App im Hintergrund läuft und dann in den Vordergrund gebracht wird. In dieser Situation wird das Überschreiben jedoch nicht auf iOS und Windows aufgerufen. In .NET MAUI wird das OnAppearing()-Override auf keiner Plattform aufgerufen, wenn eine App in den Hintergrund gestellt und dann in den Vordergrund gebracht wird. Stattdessen sollten Sie auf Lebenszyklusereignisse von Window hören, um benachrichtigt zu werden, wenn eine App in den Vordergrund zurückkehrt. Für weitere Informationen siehe .NET MAUI windows.

Änderungen der nativen Formulare

Native Forms in Xamarin.Forms sind in .NET MAUI zu einer nativen Einbettung geworden und verwenden einen anderen Initialisierungsansatz sowie unterschiedliche Erweiterungsmethoden, um plattformübergreifende Steuerelemente in ihre nativen Typen zu konvertieren. Für weitere Informationen siehe Native embedding.

Starten Sie Ihre migrierte 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. Dies kann erreicht werden, indem die Buildeigenschaft $(UseMaui) in jedem Plattformprojekt auf true festgelegt wird.

<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 mehrere NuGet-Pakete ausgeliefert. Der Vorteil dieses Ansatzes besteht darin, dass Sie Ihre Projekte auf einfache Weise an bestimmte Versionen anheften und gleichzeitig einfach eine Vorschau unveröffentlichter und experimenteller Builds anzeigen können.

Sie sollten die folgenden expliziten Paketverweise in eine <ItemGroup> in jede Projektdatei hinzufügen.

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

Auf die $(MauiVersion) Variable wird aus der Version von .NET MAUI verwiesen, die Sie installiert haben. Sie können dies ändern, indem Sie die Buildeigenschaft $(MauiVersion) 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 MainApplication Klasse so, dass sie dem folgenden 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 außerdem die MainActivity-Klasse, um von MauiAppCompatActivity zu erben.

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 die minSdKVersion Version 21 ist, bei der es sich um die minimale Android SDK-Version handelt, die von .NET MAUI benötigt wird. Dies kann durch Ändern des <uses-sdk /> Knotens erreicht werden, der ein untergeordnetes Element des <manifest> Knotens ist:

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

iOS-Projektkonfiguration

Aktualisieren Sie in Ihrem .NET MAUI iOS-Projekt die AppDelegate-Klasse, um von MauiUIApplicationDelegate abzuleiten.

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 so, dass MinimumOSVersion 11.0 ist, was die mindeste iOS-Version ist, die von .NET MAUI erforderlich ist.

UWP-Projektkonfiguration

Aktualisieren Sie in Ihrem .NET MAUI WinUI 3-Projekt "App.xaml " so, dass er dem folgenden Code entspricht:

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

Außerdem aktualisieren Sie App.xaml.cs entsprechend dem folgenden Code:

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 "Eigenschaften" 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
    }
  }
}

App-Einstiegspunkt

.NET MAUI-Apps verfügen über einen einzigen plattformübergreifenden App-Einstiegspunkt. Jeder Plattformeinstiegspunkt ruft eine CreateMauiApp Methode für die statische MauiProgram Klasse auf und gibt eine MauiApp.

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 einen vorübergehenden Dienst des angegebenen Typs zum angegebenen IServiceCollection hinzuzufügen.

Änderungen an AssemblyInfo

In einem SDK-Projekt im Stil Ihrer Vorgaben sind nun Eigenschaften verfügbar, die normalerweise in einer AssemblyInfo.cs-Datei festgelegt werden. Wir empfehlen, in jedem Projekt die AssemblyInfo.cs zu entfernen und auf die Projektdatei zu übertragen.

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

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

Weitere Informationen über die GenerateAssemblyInfo-Eigenschaft finden Sie unter GenerateAssemblyInfo.

Aktualisieren Sie die Abhängigkeiten der App

Generell sind Xamarin.Forms NuGet-Pakete mit .NET 8 nicht kompatibel, es sei denn, sie wurden unter Verwendung von .NET-Ziel-Framework-Monikern (TFMs) neu kompiliert. Allerdings können Android-Apps NuGet-Pakete verwenden, die für die monoandroid- und monoandroidXX.X-Frameworks bestimmt sind.

Sie können bestätigen, dass ein Paket mit .NET 8 kompatibel ist, indem Sie auf der Registerkarte Frameworks auf NuGet nachsehen, ob eines der kompatiblen Frameworks aufgelistet ist, die in der folgenden Tabelle dargestellt sind.

Wenn ein Paket auf NuGet Kompatibilität mit einem der oben genannten kompatiblen Frameworks anzeigt, unabhängig davon, ob auch inkompatible Frameworks enthalten sind, dann ist das Paket kompatibel. Kompatible NuGet-Pakete können Ihrem .NET MAUI-Bibliotheksprojekt mit dem NuGet-Paket-Manager in Visual Studio hinzugefügt werden.

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

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

Kompilieren und Fehlerbehebung

Sobald Ihre Abhängigkeiten gelöst sind, sollten Sie Ihr Projekt bauen. Jegliche Fehler werden Ihnen die nächsten Schritte aufzeigen.

Die folgende Tabelle bietet eine Anleitung zur Behebung häufiger Build- oder Laufzeitprobleme:

Siehe auch

• Portieren von .NET Framework zu .NET
• .NET-Upgrade-Assistent