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 y copier votre code, votre configuration et vos ressources. 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 :
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. Par exemple, utilisez Colors.AliceBlue pour spécifier la couleur de AliceBlue.
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. |
De plus, dans Xamarin.Forms, le remplacement Page.OnAppearing est appelé sur Android lorsqu’une application est en arrière-plan, puis mise au premier plan. Toutefois, dans le même scénario, ce remplacement n’est pas appelé sur iOS et Windows. Dans .NET MAUI, le remplacement OnAppearing() n’est appelé sur aucune plateforme lorsqu’une application est mise en arrière-plan puis ramenée au premier plan. En revanche, il est préférable d’écouter les événements du cycle de vie sur Window pour être informé du retour d’une application au premier plan. Pour plus d’informations, consultez Fenêtres .NET MAUI.
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’une application 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 l’amorçage 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. |
