Mettre à niveau manuellement une application Xamarin.Forms vers une application .NET MAUI multi-projet

La mise à niveau d’une application Xamarin.Forms multi-projet vers une application multiplateforme .NET (.NET MAUI) suit les mêmes étapes qu’un projet Xamarin.Android ou Xamarin.iOS, avec des étapes supplémentaires pour tirer parti des modifications apportées dans .NET MAUI.

Cet article explique comment migrer manuellement un projet de bibliothèque Xamarin.Forms vers un projet de bibliothèque .NET MAUI. Avant de procéder, vous devez mettre à jour vos projets de plateforme Xamarin.Forms pour en faire des projets de style SDK. Les projets de style SDK sont du même format de projet que celui utilisé par toutes les charges de travail .NET, et par rapport à de nombreux projets Xamarin, sont beaucoup moins détaillés. Pour plus d’informations sur la mise à jour de vos projets d’application, consultez Mettre à niveau les projets Xamarin.Android, Xamarin.iOS et Xamarin.Mac vers .NET, Migration de projet Xamarin.Android, Migration de projet Xamarin Apple etXamarin.FormsMigration de projet UWP.

Pour migrer un projet de bibliothèque Xamarin.Forms vers un projet de bibliothèque .NET MAUI, vous devez :

• Mettre à jour votre application Xamarin.Forms pour qu’elle puisse utiliser Xamarin.Forms 5.
• Mettre à jour les dépendances de l’application vers les dernières versions.
• Vérifier que l’application fonctionne toujours.
• Mettre à jour votre fichier projet pour en faire un fichier de style SDK.
• Mettre à jour les espaces de noms.
• Résoudre toute modification apportée à l’API.
• Configurer .NET MAUI.
• Mettre à niveau ou remplacer les dépendances incompatibles avec les versions .NET 8.
• Compiler et tester votre application.

Pour simplifier le processus de mise à niveau, vous devez créer un projet de bibliothèque .NET MAUI du même nom que votre projet de bibliothèque Xamarin.Forms, puis le copier dans votre code. Cette approche est décrite ci-dessous.

Mettre à jour votre application Xamarin.Forms

Avant de mettre à niveau votre application Xamarin.Forms vers .NET MAUI, vous devez d’abord mettre à jour votre application Xamarin.Forms pour qu’elle puisse utiliser Xamarin.Forms 5 et vous assurer qu’elle s’exécute toujours correctement. En outre, vous devez mettre à jour les dépendances que votre application utilise vers les dernières versions.

Cela permet de simplifier le reste du processus de migration, car il réduit les différences d’API entre Xamarin.Forms et .NET MAUI et garantit que vous utilisez les versions compatibles .NET de vos dépendances si elles existent.

Créer un projet

Dans Visual Studio, créez un nouveau projet de bibliothèque de classes .NET MAUI du même nom que votre projet de bibliothèque Xamarin.Forms. Ce projet hébergera le code de votre projet de bibliothèque Xamarin.Forms. L’ouverture du fichier projet confirmera que vous disposez d’un projet de style SDK .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>

Dans vos projets de plateforme, ajoutez une référence à ce nouveau projet de bibliothèque. Copiez ensuite vos fichiers de bibliothèque Xamarin.Forms dans le projet de bibliothèque .NET MAUI.

Modifications de l’espace de noms

Les espaces de noms ont été modifiés lors du passage de Xamarin.Forms à .NET MAUI et les fonctionnalités Xamarin.Essentials font désormais partie de .NET MAUI. Pour effectuer des mises à jour d’espace de noms, effectuez une recherche et un remplacement des espaces de noms suivants :

Espace de noms Xamarin.Forms	Espace(s) de noms .NET MAUI
Xamarin.Forms	Microsoft.Maui et Microsoft.Maui.Controls
Xamarin.Forms.DualScreen	Microsoft.Maui.Controls.Foldable
Xamarin.Forms.Maps	Microsoft.Maui.Controls.Maps et 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

Les projets .NET MAUI utilisent des directives global using implicites. Cette fonctionnalité vous permet de supprimer les directives using pour l’espace de noms Xamarin.Essentials, sans avoir à les remplacer par les espaces de noms .NET MAUI équivalents.

En outre, l’espace de noms XAML par défaut est passé de http://xamarin.com/schemas/2014/forms dans Xamarin.Forms à http://schemas.microsoft.com/dotnet/2021/maui dans .NET MAUI. Par conséquent, vous devez remplacer toutes les occurrences de xmlns="http://xamarin.com/schemas/2014/forms" par xmlns="http://schemas.microsoft.com/dotnet/2021/maui".

Remarque

Vous pouvez rapidement mettre à jour vos espaces de noms Xamarin.Forms vers Microsoft.Maui en utilisant les Actions rapides dans Visual Studio, à condition que l’Assistant de mise à niveau soit installé.

Modifications d'API

Certaines API ont été modifiées lors du passage de Xamarin.Forms à .NET MAUI. Il y a plusieurs raisons à cela, notamment la suppression des fonctionnalités dupliquées causées par le fait que Xamarin.Essentials fait maintenant partie de .NET MAUI et la nécessité de s’assurer que les API suivent les instructions d’affectation de noms .NET. Les sections suivantes décrivent ces modifications.

Modifications de couleur

Dans Xamarin.Forms, le struct Xamarin.Forms.Color vous permet de construire des objets Color en utilisant des valeurs double et fournit des couleurs nommées, comme Xamarin.Forms.Color.AliceBlue. Dans .NET MAUI, cette fonctionnalité a été séparée entre la classe Microsoft.Maui.Graphics.Color et la classe Microsoft.Maui.Graphics.Colors.

La classe Microsoft.Maui.Graphics.Color, dans l’espace de noms Microsoft.Maui.Graphics, vous permet de construire des objets Color en utilisant des valeurs float, byte et int. La classe Microsoft.Maui.Graphics.Colors, qui se trouve également dans l’espace de noms Microsoft.Maui.Graphics, fournit en grande partie les mêmes couleurs nommées.

Le tableau suivant montre les modifications apportées à l’API entre le struct Xamarin.Forms.Color et la classe Microsoft.Maui.Graphics.Color :

Xamarin.Forms API	API .NET MAUI	Commentaire
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	Propriété Xamarin.Forms remplacée par une méthode dans .NET MAUI.
Xamarin.Forms.Color.Saturation	Microsoft.Maui.Graphics.Color.GetSaturation	Propriété Xamarin.Forms remplacée par une méthode dans .NET MAUI.
Xamarin.Forms.Color.Luminosity	Microsoft.Maui.Graphics.Color.GetLuminosity	Propriété Xamarin.Forms remplacée par une méthode dans .NET MAUI.
Xamarin.Forms.Color.Default		Aucun équivalent .NET MAUI. À la place, les objets Microsoft.Maui.Graphics.Color ont par défaut la valeur null.
Xamarin.Forms.Color.Accent		Aucun équivalent .NET MAUI.
Xamarin.Forms.Color.FromHex	Microsoft.Maui.Graphics.Color.FromArgb	Microsoft.Maui.Graphics.Color.FromHex est obsolète et sera supprimé dans une prochaine version.

En outre, toutes les valeurs numériques d’un Microsoft.Maui.Graphics.Color sont float, plutôt que double comme utilisé dans Xamarin.Forms.Color.

Remarque

À la différence de Xamarin.Forms, une Microsoft.Maui.Graphics.Color n’a pas de conversion implicite en System.Drawing.Color.

Modifications de disposition

Le tableau suivant répertorie les API de disposition qui ont été supprimées lors du passage de Xamarin.Forms à .NET MAUI :

Xamarin.Forms API	API .NET MAUI	Commentaires
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add		La surcharge Add qui accepte 3 arguments n’est pas présente dans .NET MAUI.
Xamarin.Forms.Grid.IGridList<T>.AddHorizontal		Aucun équivalent .NET MAUI.
Xamarin.Forms.Grid.IGridList<T>.AddVertical		Aucun équivalent .NET MAUI.
Xamarin.Forms.RelativeLayout	Microsoft.Maui.Controls.Compatibility.RelativeLayout	Dans .NET MAUI, RelativeLayout n’existe qu’en tant que contrôle de compatibilité pour les utilisateurs qui migrent depuis Xamarin.Forms. Utilisez Grid à la place, ou ajoutez le xmlns comme espace de noms de compatibilité.

En outre, l’ajout d’éléments enfant à une disposition dans le code dans Xamarin.Forms est effectué en ajoutant les éléments enfant à la collection Children de la disposition :

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

Dans .NET MAUI, la collection Children est destinée à une utilisation interne par .NET MAUI et ne doit pas être manipulée directement. Par conséquent, dans le code, les éléments enfant doivent être ajoutés directement à la disposition :

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

Important

Toute méthode d’extension de disposition Add, comme GridExtensions.Add, est appelée sur la disposition plutôt que sur la collection Children de la disposition.

Vous remarquerez peut-être, lors de l’exécution de votre application .NET MAUI mise à niveau, que le comportement de la disposition est différent. Pour plus d’informations, consultez Changements de comportement de disposition par rapport à Xamarin.Forms.

Modifications de disposition personnalisée

Le processus de création d’une disposition personnalisée dans Xamarin.Forms implique la création d’une classe qui dérive de Layout<View>, et la substitution des méthodes VisualElement.OnMeasure et Layout.LayoutChildren. Pour plus d’informations, consultez Créer une disposition personnalisée dans Xamarin.Forms.

Dans .NET MAUI, les classes de disposition dérivent de la classe Layout abstraite. Cette classe délègue la disposition et la mesure multiplateformes à une classe de manager de disposition. Chaque manager de disposition de classe implémente l’interface ILayoutManager, qui spécifie que les implémentations Measure et ArrangeChildren doivent être fournies :

• L’implémentation Measure appelle IView.Measure pour chaque vue dans la disposition et retourne la taille totale de la disposition en fonction des contraintes.
• L’implémentation ArrangeChildren détermine où chaque vue doit être placée dans les limites de la disposition et appelle Arrange pour chaque vue avec ses limites appropriées. La valeur de retour est la taille réelle de la disposition.

Pour plus d’informations, consultez Dispositions personnalisées.

Modifications d’appareil

Xamarin.Forms a une classe Xamarin.Forms.Device qui vous permet d’interagir avec l’appareil et la plateforme sur lesquels l’application s’exécute. La classe équivalente dans .NET MAUI, Microsoft.Maui.Controls.Device, est déconseillée et sa fonctionnalité est remplacée par plusieurs types.

Le tableau suivant présente les remplacements .NET MAUI pour les fonctionnalités de la classe Xamarin.Forms.Device :

Xamarin.Forms API	API .NET MAUI	Commentaires
Xamarin.Forms.Device.Android	Microsoft.Maui.Devices.DevicePlatform.Android
Xamarin.Forms.Device.iOS	Microsoft.Maui.Devices.DevicePlatform.iOS
Xamarin.Forms.Device.GTK		Aucun équivalent .NET MAUI.
Xamarin.Forms.Device.macOS		Aucun équivalent .NET MAUI. Utilisez plutôt 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		Aucun équivalent .NET MAUI.
Xamarin.Forms.Device.Flags		Aucun équivalent .NET MAUI.
Xamarin.Forms.Device.FlowDirection	Microsoft.Maui.ApplicationModel.AppInfo.RequestedLayoutDirection
Xamarin.Forms.Device.Idiom	Microsoft.Maui.Devices.DeviceInfo.Idiom
Xamarin.Forms.Device.IsInvokeRequired	Microsoft.Maui.Dispatching.Dispatcher.IsDispatchRequired
Xamarin.Forms.Device.OS	Microsoft.Maui.Devices.DeviceInfo.Platform
Xamarin.Forms.Device.RuntimePlatform	Microsoft.Maui.Devices.DeviceInfo.Platform
Xamarin.Forms.Device.BeginInvokeOnMainThread	Microsoft.Maui.ApplicationModel.MainThread.BeginInvokeOnMainThread
Xamarin.Forms.Device.GetMainThreadSynchronizationContextAsync	Microsoft.Maui.ApplicationModel.MainThread.GetMainThreadSynchronizationContextAsync
Xamarin.Forms.Device.GetNamedColor		Aucun équivalent .NET MAUI.
Xamarin.Forms.Device.GetNamedSize		Aucun équivalent .NET MAUI.
Xamarin.Forms.Device.Invalidate	Microsoft.Maui.Controls.VisualElement.InvalidateMeasure
Xamarin.Forms.Device.InvokeOnMainThreadAsync	Microsoft.Maui.ApplicationModel.MainThread.InvokeOnMainThreadAsync
Xamarin.Forms.Device.OnPlatform	Microsoft.Maui.Devices.DeviceInfo.Platform
Xamarin.Forms.Device.OpenUri	Microsoft.Maui.ApplicationModel.Launcher.OpenAsync
Xamarin.Forms.Device.SetFlags		Aucun équivalent .NET MAUI.
Xamarin.Forms.Device.SetFlowDirection	Microsoft.Maui.Controls.Window.FlowDirection
Xamarin.Forms.Device.StartTimer	Microsoft.Maui.Dispatching.DispatcherExtensions.StartTimer ou Microsoft.Maui.Dispatching.Dispatcher.DispatchDelayed

Modifications de carte

Dans Xamarin.Forms, le contrôle Map et les types associés se trouvent dans l’espace de noms Xamarin.Forms.Maps. Dans .NET MAUI, cette fonctionnalité a été déplacée vers les espaces de noms Microsoft.Maui.Controls.Maps et Microsoft.Maui.Maps. Certaines propriétés ont été renommées et certains types ont été remplacés par des types équivalents de Xamarin.Essentials.

Le tableau suivant présente les remplacements .NET MAUI pour les fonctionnalités de l’espace de noms Xamarin.Forms.Maps :

Xamarin.Forms API	API .NET MAUI	Commentaire
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		Aucun équivalent .NET MAUI.
Xamarin.Forms.Maps.Pin.Id	Microsoft.Maui.Controls.Maps.Pin.MarkerId
Xamarin.Forms.Maps.Pin.Position	Microsoft.Maui.Controls.Maps.Pin.Location
Xamarin.Forms.Maps.MapClickedEventArgs.Position	Microsoft.Maui.Controls.Maps.MapClickedEventArgs.Location
Xamarin.Forms.Maps.Position	Microsoft.Maui.Devices.Sensors.Location	Les membres de type Xamarin.Forms.Maps.Position ont été modifiés en type Microsoft.Maui.Devices.Sensors.Location.
Xamarin.Forms.Maps.Geocoder	Microsoft.Maui.Devices.Sensors.Geocoding	Les membres de type Xamarin.Forms.Maps.Geocoder ont été modifiés en type Microsoft.Maui.Devices.Sensors.Geocoding.

.NET MAUI a deux types Map : Microsoft.Maui.Controls.Maps.Map et Microsoft.Maui.ApplicationModel.Map. L’espace de noms Microsoft.Maui.ApplicationModel étant l’une des directives global using de .NET MAUI, lorsque vous utilisez le contrôle Microsoft.Maui.Controls.Maps.Map depuis le code, vous devez qualifier entièrement votre utilisation Map ou utiliser un alias d’utilisation.

En XAML, vous devez ajouter une définition d’espace de noms xmlns pour le contrôle Map. Bien que cela ne soit pas obligatoire, cela empêche une collision entre les types Polygon et Polyline, qui existent à la fois dans les espaces de noms Microsoft.Maui.Controls.Maps et Microsoft.Maui.Controls.Shapes. Pour plus d’informations, consultez Afficher une carte.

Autres modifications

Un petit nombre d’autres API ont été consolidées pendant le passage de Xamarin.Forms à .NET MAUI. Le tableau suivant indique ces modifications :

Xamarin.Forms API	API .NET MAUI	Commentaires
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	Dans Xamarin.Forms, la méthode ApplyQueryAttributes accepte un argument IDictionary<string, string>. Dans .NET MAUI, la méthode ApplyQueryAttributes accepte un argument IDictionary<string, object>.
Xamarin.Forms.MenuItem.Icon	Microsoft.Maui.Controls.MenuItem.IconImageSource	Xamarin.Forms.MenuItem.Icon est la classe de base pour Xamarin.Forms.ToolbarItem, et ainsi ToolbarItem.Icon devient ToolbarItem.IconImageSource.
Xamarin.Forms.OrientationStateTrigger.Orientation	Microsoft.Maui.Controls.OrientationStateTrigger.Orientation	Dans Xamarin.Forms, la propriété OrientationStateTrigger.Orientation est de type Xamarin.Forms.Internals.DeviceOrientation. Dans .NET MAUI, la propriété OrientationStateTrigger.Orientation est de type 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 est la classe de base pour Microsoft.Maui.Controls.ToolbarItem, et ainsi ToolbarItem.Name devient ToolbarItem.Text.

Modifications des formulaires natifs

Les formulaires natifs dans Xamarin.Forms sont devenus une incorporation native dans .NET MAUI et utilisent une approche d’initialisation différente et des méthodes d’extension différentes pour convertir les contrôles multiplateformes vers leurs types natifs. Pour plus d’informations, consultez Incorporation native.

Démarrer votre application migrée

Lors de la mise à jour manuelle d’un élément Xamarin.Forms vers .NET MAUI, vous devez activer la prise en charge de .NET MAUI dans chaque projet de plateforme, mettre à jour la classe de point d’entrée de chaque projet de plateforme, puis configurer le démarrage de votre application .NET MAUI .

Activer .NET MAUI dans les projets de plateforme

Avant de mettre à jour la classe de point d’entrée de chaque projet de plateforme, vous devez d’abord activer la prise en charge de .NET MAUI. Pour ce faire, définissez la propriété de build $(UseMaui) sur true dans chaque projet de plateforme :

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

Important

Vous devez ajouter <UseMaui>true</UseMaui> à votre fichier projet pour activer la prise en charge de .NET MAUI. En outre, vérifiez que vous avez ajouté <EnableDefaultMauiItems>false</EnableDefaultMauiItems> à votre fichier projet WinUI. Cela vous empêche de recevoir des erreurs de build sur la méthode InitializeComponent déjà définie.

Ajouter des références de package

Dans .NET 8, .NET MAUI est fourni sous la forme d’une charge de travail .NET et de plusieurs packages NuGet. L’avantage de cette approche est qu’elle vous permet d’épingler facilement vos projets à des versions spécifiques, tout en vous permettant d’avoir facilement un aperçu des builds non publiées ou expérimentales.

Vous devez ajouter les références de package explicites suivantes à un <ItemGroup> dans chaque fichier projet :

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

La variable $(MauiVersion) est référencée à partir de la version de .NET MAUI que vous avez installée. Vous pouvez remplacer cela en ajoutant la propriété de build $(MauiVersion) à chaque fichier projet :

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

Configuration de projet Android

Dans votre projet Android .NET MAUI, mettez à jour la classe MainApplication pour qu’elle corresponde au code ci-dessous :

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

Mettez également à jour la classe MainActivity pour qu’elle hérite de MauiAppCompatActivity :

using System;
using Microsoft.Maui;
using Android.App;
using Android.Content.PM;
using Android.Runtime;
using Android.OS;

namespace YOUR_NAMESPACE_HERE.Droid
{
    [Activity(Label = "MyTitle", Icon = "@mipmap/icon", Theme = "@style/MainTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation | ConfigChanges.UiMode | ConfigChanges.ScreenLayout | ConfigChanges.SmallestScreenSize)]
    public class MainActivity : MauiAppCompatActivity
    {
        protected override void OnCreate(Bundle savedInstanceState)
        {
            base.OnCreate(savedInstanceState);
        }
    }
}

Ensuite, mettez à jour votre fichier manifeste pour spécifier que minSdKVersion est 21, qui est la version Android SDK minimum requise par .NET MAUI. Pour ce faire, modifiez le nœud <uses-sdk />, qui est un élément enfant du nœud <manifest> :

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

Configuration de projet iOS

Dans votre projet iOS .NET MAUI, mettez à jour la classe AppDelegate pour qu’elle hérite de MauiUIApplicationDelegate :

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.Maui;
using Foundation;
using UIKit;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.iOS
{
    [Register("AppDelegate")]
    public partial class AppDelegate : MauiUIApplicationDelegate
    {
        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
    }
}

Ensuite, mettez à jour Info.plist de sorte que MinimumOSVersion soit 11.0, qui est la version iOS minimum requise par .NET MAUI.

Configuration de projet UWP

Dans votre projet .NET MAUI WinUI 3, mettez à jour App.xaml pour correspondre au code ci-dessous :

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

Remarque

Si votre projet incluait des ressources dans votre app.xamlexistant, vous devez les migrer vers la nouvelle version du fichier.

Mettez également à jour App.xaml.cs pour correspondre au code ci-dessous :

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

Remarque

Si votre projet incluait une logique métier dans App.xaml.cs vous devez migrer cette logique vers la nouvelle version du fichier.

Ajoutez ensuite un fichier launchSettings.json au dossier Properties (Propriétés) du projet, puis ajoutez le code JSON suivant au fichier :

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

Point d’entrée de l’application

Les applications .NET MAUI ont un point d’entrée d’application multiplateforme unique. Chaque point d’entrée de plateforme appelle une méthode CreateMauiApp sur la classe MauiProgram statique et retourne une MauiApp.

Par conséquent, ajoutez une nouvelle classe nommée MauiProgram qui contient le code suivant :

namespace YOUR_NAMESPACE_HERE;

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

        return builder.Build();
    }
}

Remarque

Pour les projets UWP Xamarin.Forms, la référence App dans builder.UseMauiApp<App>() se trouve dans le fichier MainPage.xaml.cs.

S’il existe des services spécifiques à la plateforme qui doivent être migrés vers .NET MAUI, utilisez la méthode AddTransient(IServiceCollection, Type) pour ajouter un service temporaire du type spécifié à la IServiceCollection spécifiée.

Remarque

Vous pouvez rapidement mettre à jour vos espaces de noms Xamarin.Forms vers Microsoft.Maui en utilisant les Actions rapides dans Visual Studio, à condition que l’Assistant de mise à niveau soit installé.

Modifications AssemblyInfo

Les propriétés, qui sont généralement définies dans un fichier AssemblyInfo.cs, sont désormais disponibles dans votre projet de style SDK. Nous vous recommandons de les migrer depuis AssemblyInfo.cs vers votre fichier projet dans chaque projet et de supprimer le fichier AssemblyInfo.cs.

Si vous le souhaitez, vous pouvez conserver le fichier AssemblyInfo.cs et définir la propriété GenerateAssemblyInfo dans votre fichier projet sur false :

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

Pour plus d’informations sur la propriété GenerateAssemblyInfo, consultez GenerateAssemblyInfo.

Mettre à jour les dépendances d’application

En règle générale, les packages NuGet Xamarin.Forms ne sont pas compatibles avec .NET 8, sauf s’ils ont été recompilés en utilisant des monikers de framework cible (Target Framework Monikers/TFM) .NET. Toutefois, les applications Android peuvent utiliser des packages NuGet ciblant les infrastructures monoandroid et monoandroidXX.X.

Vous pouvez confirmer qu’un package est compatible avec .NET 8 en examinant l’onglet Infrastructures (Frameworks) sur NuGet pour le package que vous utilisez et en vérifiant qu’il répertorie l’une des infrastructures compatibles indiquées dans le tableau suivant :

Infrastructures compatibles	Infrastructures incompatibles
net8.0-android, monoandroid, monoandroidXX.X
net8.0-ios	monotouch, xamarinios, xamarinios10
net8.0-macos	monomac, xamarinmac, xamarinmac20
net8.0-tvos	xamarintvos
	xamarinwatchos

Remarque

Les bibliothèques .NET Standard qui n’ont aucune dépendance sur les infrastructures incompatibles répertoriées ci-dessus sont toujours compatibles avec .NET 8.

Si un package sur NuGet indique la compatibilité avec l’une des infrastructures compatibles ci-dessus, indépendamment de l’inclusion éventuelle d’infrastructures incompatibles, le package est compatible. Vous pouvez ajouter des packages NuGet compatibles à votre projet de bibliothèque .NET MAUI en utilisant le gestionnaire de package NuGet dans Visual Studio.

Si vous ne trouvez pas de version compatible .NET 8 d’un package NuGet, vous devez :

• Recompiler le package avec des TFM .NET, si vous possédez le code.
• Rechercher une préversion d’une version .NET 8 du package.
• Remplacer la dépendance par une alternative compatible .NET 8.

Compiler et résoudre les problèmes

Une fois vos dépendances résolues, vous devez générer votre projet. Toutes les erreurs vous guideront vers les étapes suivantes.

Conseil

• Supprimez tous les dossiers bin et obj de tous les projets avant d’ouvrir et de générer des projets dans Visual Studio, en particulier lorsque vous changez de version de .NET.
• Supprimez le fichier généré Resource.designer.cs du projet Android.

Le tableau suivant fournit une aide pour surmonter les problèmes courants liés à la génération ou au runtime :

Problème	Conseil
L’espace de noms Xamarin.* n’existe pas.	Mettez à jour l’espace de noms vers son équivalent .NET MAUI. Pour plus d’informations, consultez Modifications des espace de noms.
L’API n’existe pas.	Mettez à jour l’utilisation de l’API vers son équivalent .NET MAUI. Pour plus d’informations, consultez Modifications des API.
L’application ne se déploie pas.	Vérifiez que le projet de plateforme requis est configuré pour le déploiement dans le Configuration Manager de Visual Studio.
L’application ne démarre pas.	Mettez à jour la classe de point d’entrée de chaque projet de plateforme et le point d’entrée de l’application. Pour plus d’informations, consultez Démarrer votre application migrée.
CollectionView ne défile pas.	Vérifiez la disposition du conteneur et la taille mesurée de CollectionView. Par défaut, le contrôle prend autant d’espace que le conteneur l’autorise. Un Grid limite les éléments enfant à sa propre taille. Toutefois, un StackLayout permet à un élément enfant de prendre de l’espace au-delà de ses limites.
La fenêtre contextuelle s’affiche sous la page sur iOS.	Dans Xamarin.Forms, toutes les fenêtres contextuelles sur iOS sont des instances UIWindow, mais dans les fenêtres contextuelles .NET MAUI sont affichées en localisant la présentation ViewController actuelle et en affichant la fenêtre contextuelle avec PresentViewControllerAsync. Dans les plug-ins tels que Mobups, pour vous assurer que vos fenêtres contextuelles sont correctement affichées, vous devez appeler DisplayAlert, DisplayActionSheet ou DisplayPromptAsync depuis la ContentPage utilisée dans la fenêtre contextuelle Mopup.
BoxView n’apparaît pas.	La taille par défaut d’une BoxView dans Xamarin.Forms est de 40 x 40. La taille par défaut d’une BoxView dans .NET MAUI est 0 x 0. Définissez WidthRequest et HeightRequest sur 40.
La disposition manque de remplissage, de marge ou d’espacement.	Ajoutez les valeurs par défaut à votre projet en fonction de la ressource de style .NET MAUI. Pour plus d’informations, consultez Modifications de la valeur par défaut de Xamarin.Forms.
La disposition personnalisée ne fonctionne pas.	Le code de disposition personnalisée doit être mis à jour pour fonctionner dans .NET MAUI. Pour plus d’informations, consultez Modifications de disposition personnalisée.
Le renderer personnalisé ne fonctionne pas.	Le code du renderer doit être mis à jour pour fonctionner dans .NET MAUI. Pour plus d’informations, consultez Utiliser des renderers personnalisés dans .NET MAUI.
L’effet ne fonctionne pas.	Le code d’effet doit être mis à jour pour fonctionner dans .NET MAUI. Pour plus d’informations, consultez Utiliser des effets dans .NET MAUI.
Le code SkiaSharp ne fonctionne pas.	Le code SkiaSharp a besoin de mises à jour mineures pour fonctionner dans .NET MAUI. Pour plus d’informations, consultez Réutiliser du code SkiaSharp dans .NET MAUI.
Impossible d’accéder aux données des propriétés d’application créées précédemment.	Migrez les données des propriétés de l’application vers les préférences .NET MAUI. Pour plus d’informations, consultez Migrer des données du dictionnaire des propriétés d’application Xamarin.Forms vers les préférences .NET MAUI.
Impossible d’accéder aux données de stockage sécurisé créées précédemment.	Migrez les données de stockage sécurisé vers .NET MAUI. Pour plus d’informations, consultez Migrer un stockage sécurisé Xamarin.Essentials vers le stockage sécurisé .NET MAUI.
Impossible d’accéder aux données de suivi des versions créées précédemment.	Migrez les données de suivi de version vers .NET MAUI. Pour plus d’informations, consultez Migrer les données de suivi des versions d’une application Xamarin.Forms vers une application .NET MAUI.

Voir aussi

• Portage de .NET Framework vers .NET
• Assistant de mise à niveau de .NET