Partager via

Mettre à niveau manuellement une application Xamarin.Forms vers une application .NET MAUI sous forme de projet unique

Pour migrer une application Xamarin.Forms vers un projet unique .NET Multi-platform App UI (.NET MAUI), vous devez :

  • Mettez à jour votre application Xamarin.Forms pour utiliser Xamarin.Forms 5.
  • Mettez à jour les dépendances de l'application aux dernières versions.
  • Assurez-vous que l'application fonctionne toujours.
  • Créer une application .NET MAUI.
  • Copiez le code et la configuration de l’application Xamarin.Forms vers l’application .NET MAUI.
  • Copiez les ressources de votre Xamarin.Forms application vers l’application .NET MAUI.
  • Mettre à jour les namespaces.
  • Traitez toutes les modifications de l'API.
  • Mettez à niveau ou remplacez les dépendances incompatibles par les versions .NET 8.
  • Compilez et testez votre application.

Pour simplifier le processus de mise à niveau, vous devez créer une application .NET MAUI du même nom que votre application, puis copier dans votre Xamarin.Forms code, configuration et ressources. Voici l'approche décrite ci-dessous.

Mettez à 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 utiliser Xamarin.Forms 5 et vous assurer qu'elle fonctionne toujours correctement. De plus, vous devriez mettre à jour les dépendances que votre application utilise vers les dernières versions.

Cela aidera à simplifier le reste du processus de migration, car cela minimisera les différences API entre Xamarin.Forms et .NET MAUI, et garantira que vous utilisez des versions compatibles avec .NET de vos dépendances si elles existent.

Créer une application .NET MAUI

Dans Visual Studio, créez une application .NET MAUI avec le même nom que votre Xamarin.Forms application :

Capture d’écran de la création d’une application .NET MAUI dans Visual Studio.

L’ouverture du fichier projet vérifie que vous disposez d’un projet de style sdk .NET.

Copier du code dans l’application .NET MAUI

Tout le code multiplateforme de votre Xamarin.Forms projet de bibliothèque doit être copié dans votre projet d’application .NET MAUI dans des dossiers et fichiers nommés identiquement.

Les renderers personnalisés peuvent soit être réutilisés dans une application .NET MAUI, soit migrés vers un gestionnaire .NET MAUI. Pour plus d'informations, consultez Réutilisez des renderers personnalisés dans .NET MAUI et Xamarin.Forms.

Les effets peuvent être réutilisés dans une application .NET MAUI. Pour plus d'informations, voir Effets de réutilisation.

Remarque

Vous pouvez rapidement mettre à jour vos Xamarin.Forms espaces de noms vers Microsoft.Maui en utilisant les Actions rapides dans Visual Studio, à condition que vous ayez installé Upgrade Assistant.

Code spécifique à la plateforme

Un projet d’application .NET MAUI contient un dossier Plateformes , avec chaque dossier enfant représentant une plateforme que .NET MAUI peut cibler :

Capture d’écran des dossiers de plateforme.

Les dossiers de chaque plateforme contiennent des ressources spécifiques à la plateforme et du code qui démarre l’application sur chaque plateforme :

Capture d’écran du code spécifique à la plateforme.

Le code, ainsi que les dossiers qui les contiennent, de vos Xamarin.Forms projets de tête, doivent être copiés dans ces dossiers :

  • Le code de votre Xamarin.Forms projet principal Android doit être copié dans le dossier Platform\Android de votre projet d’application .NET MAUI. En outre, copiez tout code personnalisé de vos classes Xamarin.Forms, MainActivity et MainApplication vers les mêmes classes dans votre projet d’application .NET MAUI.

  • Le code de votre Xamarin.Forms projet principal iOS doit être copié dans le dossier Platforms\iOS de votre projet d’application .NET MAUI. En outre, copiez tout code personnalisé de votre Xamarin.FormsAppDelegate classe vers la même classe dans votre projet d’application .NET MAUI.

    Remarque

    Pour obtenir la liste des modifications importantes dans .NET pour iOS, consultez Modifications importantes dans .NET pour iOS.

  • Le code de votre Xamarin.Forms projet principal UWP doit être copié dans le dossier Platforms\Windows de votre projet d’application .NET MAUI. En outre, copiez tout code personnalisé de votre Xamarin.FormsApp classe vers la même classe dans votre projet d’application .NET MAUI.

Au moment de la compilation, le système de build inclut uniquement le code de chaque dossier lors de la construction pour cette plateforme spécifique. Par exemple, lorsque vous générez pour Android, les fichiers du dossier Platforms\Android sont intégrés au package d’application, mais les fichiers des autres dossiers plateformes ne seront pas. Cette approche utilise le ciblage multiple pour cibler plusieurs plateformes à partir d’un seul projet. Les applications .NET MAUI peuvent également être ciblées sur la base de vos propres critères de nom de fichier et de dossier. Cela vous permet de structurer votre projet d’application .NET MAUI afin que vous n’ayez pas à placer votre code de plateforme dans des dossiers enfants du dossier Plateformes . Pour plus d’informations, consultez Configurer le multi-ciblage.

Copier la configuration vers l’application .NET MAUI

Chaque plateforme utilise son propre fichier manifeste d’application natif pour spécifier des informations telles que le titre de l’application, l’ID, la version, etc. Le projet .NET MAUI vous permet de spécifier ces données d’application courantes dans un emplacement unique dans le fichier projet.

Pour spécifier les données de manifeste d’application partagée pour un projet, ouvrez le menu contextuel du projet dans l’Explorateur de solutions, puis choisissez Propriétés. Le titre, l’ID et la version de l’application peuvent ensuite être spécifiés dans MAUI Shared > General :

Capture d’écran du manifeste de l’application .NET MAUI.

Au moment de la génération, les données du manifeste d’application partagée sont fusionnées avec des données spécifiques à la plateforme dans le fichier manifeste d’application natif, afin de produire le fichier manifeste du package d’application. Pour plus d’informations, consultez La configuration du projet dans .NET MAUI - MAUI Shared.

Les données restantes de vos Xamarin.Forms manifestes d’application doivent être copiées dans votre manifeste d’application .NET MAUI :

  • Sur Android, copiez toutes les données supplémentaires du fichier AndroidManifest.xml dans votre Xamarin.Forms projet principal Android, dans le fichier Plateformes\Android\AndroidManifest.xml dans votre projet d’application .NET MAUI.
  • Sur iOS, copiez toutes les données supplémentaires du fichier Info.plist dans votre Xamarin.Forms projet principal iOS vers le fichier Platforms\iOS\Info.plist dans votre projet d’application .NET MAUI. En outre, copiez le fichier Entitlements.plist dans votre Xamarin.Forms projet principal iOS dans le dossier Platforms\iOS de votre projet d’application .NET MAUI.
  • Sur Windows, copiez des données supplémentaires à partir du fichier Package.appxmanifest dans votre Xamarin.Forms projet principal UWP vers le fichier Platforms\Windows\Package.appxmanifest dans votre projet d’application .NET MAUI.

Copier des ressources dans l’application .NET MAUI

Le projet unique .NET MAUI permet aux fichiers de ressources d’être stockés dans un emplacement unique tout en étant consommés sur chaque plateforme. Cela inclut les polices, les images, l’icône de l’application, l’écran de démarrage, les ressources brutes et les fichiers CSS pour le style des applications .NET MAUI.

Les fichiers de ressources doivent généralement être placés dans le dossier Ressources de votre projet d’application .NET MAUI, ou les dossiers enfants du dossier Ressources , et doivent avoir correctement défini leur action de génération. Le tableau suivant présente les actions de génération pour chaque type de fichier de ressources :

Ressource Action de construction
Icône de l’application MauiIcon
Polices MauiFont
Images MauiImage
Écran de démarrage MauiSplashScreen
Ressources brutes MauiAsset
fichiers CSS MauiCss

Remarque

Les fichiers XAML sont également stockés dans votre projet d’application .NET MAUI et sont automatiquement affectés à l’action de génération MauiXaml . Toutefois, seuls les dictionnaires de ressources XAML sont généralement placés dans le dossier Ressources du projet d’application.

La capture d’écran suivante montre un dossier Ressources classique contenant des dossiers enfants pour chaque type de ressource :

Capture d’écran des ressources d’image et de police.

L’action de génération d’un fichier de ressources est correctement définie si la ressource a été ajoutée au dossier Enfant Ressources approprié.

Important

Les ressources spécifiques à la plateforme remplacent leurs équivalents de ressources partagées. Par exemple, si vous disposez d’une image spécifique à Android située sur les plateformes\Android\Resources\drawable-xhdpi\logo.png, et que vous fournissez également une image partagée Resources\Images\logo.svg , le fichier SVG (Scalable Vector Graphics) sera utilisé pour générer les images Android requises, à l’exception de l’image XHDPI qui existe déjà en tant qu’image spécifique à la plateforme.

Icônes d’application

L’icône Xamarin.Forms de votre application doit être ajoutée à votre projet d’application .NET MAUI en faisant glisser l’image dans le dossier Resources\AppIcon du projet, où son action de génération sera automatiquement définie sur MauiIcon. Au moment de la génération, l’icône d’application est redimensionnée aux tailles appropriées pour la plateforme cible et l’appareil. Les icônes d’application sont redimensionnées en plusieurs résolutions, car elles ont plusieurs utilisations, notamment pour représenter l’application sur l’appareil et dans le magasin d’applications.

Pour plus d’informations, consultez Ajouter une icône d’application à un projet d’application .NET MAUI.

Écran de démarrage

Si votre Xamarin.Forms application a un écran de démarrage, elle doit être ajoutée à votre projet d’application .NET MAUI en faisant glisser l’image dans le dossier Resources\Splash du projet, où son action de génération est automatiquement définie sur MauiSplashScreen. Au moment de la génération, l’image de l’écran de démarrage est redimensionnée à la taille correcte pour la plateforme cible et l’appareil.

Pour plus d’informations, consultez Ajouter un écran de démarrage à un projet d’application .NET MAUI.

Images

Les appareils ont une plage de tailles d’écran et de densités, et chaque plateforme dispose de fonctionnalités permettant d’afficher des images dépendantes de la densité. Dans Xamarin.Forms, les images dépendantes de la densité sont généralement placées dans des projets principaux et adoptent une convention d’affectation de noms spécifique à la plateforme. Il existe deux approches qui peuvent être prises pour migrer ces images vers .NET MAUI.

L’approche recommandée consiste à copier la version de résolution la plus élevée de chaque image de votre Xamarin.Forms solution vers votre projet d’application .NET MAUI en le faisant glisser dans le dossier Resources\Images du projet, où son action de génération est automatiquement définie sur MauiImage. Il sera également nécessaire de définir l’attribut BaseSize de chaque image bitmap pour vous assurer que le redimensionnement se produit. Cela élimine la nécessité d’avoir plusieurs versions de chaque image, sur chaque plateforme. Au moment de la génération, toutes les images seront ensuite redimensionnées en plusieurs images dépendantes de la densité qui répondent aux exigences de la plateforme. Pour plus d’informations, consultez Ajouter des images à un projet d’application .NET MAUI.

Vous pouvez également copier des images dépendantes de la densité de votre Xamarin.Forms solution vers des dossiers nommés identiquement dans le dossier Plateformes\{Platform} de votre projet d’application .NET MAUI et définir leurs actions de génération sur les actions de génération utilisées dans votre Xamarin.Forms solution. Le tableau suivant répertorie les exemples d’emplacements d’image d’une Xamarin.Forms solution et leur emplacement équivalent dans un projet d’application .NET MAUI :

Xamarin.Forms emplacement de l’image Emplacement de l’image .NET MAUI Action de construction de l'image de la plateforme .NET MAUI
{MyApp.Android}\Resources\drawable-xhdpi\image.png Plateformes\Android\Resources\drawable-xhdpi\image.png AndroidResource
{MyApp.iOS}\image.jpg *Plateformes\iOS\Resources\image.jpg BundleResource
{MyApp.UWP}\Assets\Images\image.gif *Plateformes\Windows\Assets\Images\image.gif Contenu

À condition que vous ayez adopté la même convention d’affectation de noms d’image que celle utilisée dans votre Xamarin.Forms solution, l’image appropriée sera choisie au moment de l’exécution en fonction des fonctionnalités de l’appareil. L’inconvénient de cette approche est que vous disposez toujours de plusieurs versions de chaque image sur chaque plateforme.

Polices

Toutes les polices de votre Xamarin.Forms solution peuvent être ajoutées à votre solution MAUI .NET en les faisant glisser dans le dossier Resources\Fonts de votre projet d’application .NET MAUI, où leur action de génération sera automatiquement définie sur MauiFont.

Pour plus d’informations, consultez Polices.

fichiers CSS

Tous les fichiers CSS de votre Xamarin.Forms solution peuvent être ajoutés à votre solution MAUI .NET en les faisant glisser dans un dossier nommé identiquement et en définissant leur action de génération sur MauiCss dans la fenêtre Propriétés .

Pour plus d’informations sur l’utilisation de fichiers CSS dans une application .NET MAUI, consultez Les applications style à l’aide de feuilles de style en cascade.

Ressources brutes

Tous les fichiers multimédias bruts, tels que HTML, JSON et vidéo, doivent être copiés à partir de votre Xamarin.Forms solution vers votre projet d’application MAUI .NET en les faisant glisser dans le dossier Resources\Raw de votre projet, où leur action de génération sera automatiquement définie sur MauiAsset.

Ressources localisées

Dans une application .NET MAUI, les chaînes sont localisées à l’aide de la même approche que dans une Xamarin.Forms application. Par conséquent, vos fichiers de ressources .NET (.resx) doivent être copiés de votre Xamarin.Forms solution vers un dossier nommé identiquement dans votre solution MAUI .NET. Ensuite, le langage neutre de votre application .NET MAUI doit être spécifié. Pour plus d’informations, consultez Spécifier la langue neutre de l’application.

Remarque

Les fichiers de ressources .NET ne doivent pas être placés dans le dossier Ressources de votre projet d’application .NET MAUI.

Dans une application MAUI .NET, les images sont localisées à l’aide de la même approche que dans une Xamarin.Forms application. Par conséquent, vos images localisées et les dossiers dans lesquels elles résident doivent être copiées de votre Xamarin.Forms solution vers votre projet d’application .NET MAUI :

  • Sur Android, le dossier racine de votre projet d’application .NET MAUI pour les images localisées est Platforms\Android\Resources.
  • Sur iOS, le dossier racine de votre projet d’application .NET MAUI pour les images localisées est Platforms\iOS\Resources.
  • Sur Windows, le dossier racine de votre projet d’application .NET MAUI pour les images localisées est Platforms\Windows\Assets\Images.

Les images localisées doivent avoir leurs actions de génération configurées selon celles de votre solution Xamarin.Forms. Pour plus d’informations, consultez Localiser les images.

Dans une application .NET MAUI, les noms d’application sont localisés à l’aide de la même approche que dans une Xamarin.Forms application :

  • Sur Android, le nom de l’application localisée peut être stocké à l’aide d’une convention d’affectation de noms basée sur des dossiers dans le dossier Platforms\Android\Resources . Les dossiers et fichiers de localisation des noms d’application doivent être copiés dans ce dossier à partir de votre Xamarin.Forms solution.
  • Sur iOS, le nom de l’application localisée est stocké à l’aide d’une convention d’affectation de noms basée sur un dossier dans le dossier Platforms\iOS\Resources . Les dossiers et fichiers de localisation des noms d’application doivent être copiés dans ce dossier à partir de votre Xamarin.Forms solution.
  • Sur Windows, le nom de l’application localisée est stocké dans le manifeste du package d’application.

Pour plus d’informations, consultez Localiser le nom de l’application. Pour plus d’informations sur la localisation de l’application .NET MAUI, consultez Localisation.

Modifications de l'espace de noms

Les espaces de noms ont changé lors du passage de Xamarin.Forms à .NET MAUI, et les fonctionnalités de Xamarin.Essentials font désormais partie de .NET MAUI. Pour effectuer des mises à jour de l'espace de noms, réalisez une recherche et un remplacement pour les espaces de noms suivants :

Xamarin.Forms Namespace Espaces 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 implicites global using. 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 équivalents de .NET MAUI.

De plus, l'espace de noms XAML par défaut a changé 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 Xamarin.Forms espaces de noms vers Microsoft.Maui en utilisant les Actions rapides dans Visual Studio, à condition que vous ayez installé Upgrade Assistant.

Modifications de l’API

Certaines API ont changé lors du passage de Xamarin.Forms à .NET MAUI. Il y a plusieurs raisons, y compris la suppression des fonctionnalités en double causée par Xamarin.Essentials devenant partie de .NET MAUI, et garantir que les API suivent les directives de nommage .NET. Les sections suivantes discutent de ces changements.

Changements de couleur

Dans Xamarin.Forms, la structure Xamarin.Forms.Color vous permet de construire des objets Color en utilisant des valeurs double, et fournit des couleurs nommées, telles que Xamarin.Forms.Color.AliceBlue. Dans .NET MAUI, cette fonctionnalité a été séparée en 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, des valeurs byte, et des valeurs int. La classe Microsoft.Maui.Graphics.Colors, qui se trouve également dans l'espace de noms Microsoft.Maui.Graphics, fournit principalement les mêmes couleurs nommées. Par exemple, utilisez Colors.AliceBlue pour spécifier la AliceBlue couleur.

Le tableau suivant montre les modifications de l'API entre la structure Xamarin.Forms.Color et la classe Microsoft.Maui.Graphics.Color.

Xamarin.Forms Interface de Programmation d'Applications (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 Xamarin.Forms propriété remplacée par une méthode dans .NET MAUI.
Xamarin.Forms.Color.Saturation Microsoft.Maui.Graphics.Color.GetSaturation Xamarin.Forms propriété remplacée par une méthode dans .NET MAUI.
Xamarin.Forms.Color.Luminosity Microsoft.Maui.Graphics.Color.GetLuminosity Xamarin.Forms propriété remplacée par une méthode dans .NET MAUI.
Xamarin.Forms.Color.Default Pas d'équivalent .NET MAUI. Au lieu de cela, les objets reviennent par défaut à null.
Xamarin.Forms.Color.Accent Pas d'é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 future version.

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

Remarque

Contrairement à Xamarin.Forms, un Microsoft.Maui.Graphics.Color n’a pas de conversion implicite en System.Drawing.Color.

Modifications de la mise en page

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

Xamarin.Forms Interface de Programmation d'Applications (API) API .NET MAUI Commentaires
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add La Add surcharge qui accepte trois arguments n’est pas présente dans .NET MAUI.
Xamarin.Forms.Grid.IGridList<T>.AddHorizontal Pas d'équivalent .NET MAUI.
Xamarin.Forms.Grid.IGridList<T>.AddVertical Pas d'équivalent .NET MAUI.
Xamarin.Forms.RelativeLayout Microsoft.Maui.Controls.Compatibility.RelativeLayout Dans .NET MAUI, RelativeLayout n'existe que comme un contrôle de compatibilité pour les utilisateurs migrer de Xamarin.Forms. Utilisez Grid à la place, ou ajoutez le xmlns pour l'espace de noms de compatibilité.

En outre, l'ajout d'enfants à une mise en page dans le code dans Xamarin.Forms s'effectue en ajoutant les enfants à la collection de Children de la mise en page :

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

Dans .NET MAUI, la collection Children est destinée à un usage interne par .NET MAUI et ne doit pas être manipulée directement. Par conséquent, dans le code, les enfants doivent être ajoutés directement à la mise en page.

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

Important

Toute méthode d'extension de Add mise en page, telle que GridExtensions.Add, est invoquée sur la mise en page plutôt que sur la collection de Children mises en page.

Vous pourriez remarquer 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, voir Modifications du comportement de mise en page à partir de Xamarin.Forms.

Modifications de mise en page 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 redéfinition des méthodes VisualElement.OnMeasure et Layout.LayoutChildren. Pour plus d'informations, consultez Créer une mise en page personnalisée dans Xamarin.Forms.

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

  • L'implémentation Measure appelle IView.Measure sur chaque vue de la disposition, et renvoie 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 mise en page, et appelle Arrange sur chaque vue avec ses limites appropriées. La valeur de retour est la taille réelle de la mise en page.

Pour plus d'informations, consultez Agencements personnalisés.

Changements d'appareil

Xamarin.Forms contient une Xamarin.Forms.Device classe qui vous aide à interagir avec l'appareil et la plateforme sur laquelle l'application s'exécute. La classe équivalente dans .NET MAUI, Microsoft.Maui.Controls.Device, est obsolète et sa fonctionnalité est désormais remplacée par plusieurs types.

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

Xamarin.Forms Interface de Programmation d'Applications (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 Pas d'équivalent .NET MAUI.
Xamarin.Forms.Device.macOS Pas d'équivalent .NET MAUI. Au lieu de cela, utilisez 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 Pas d'équivalent .NET MAUI.
Xamarin.Forms.Device.Flags Pas d'é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 Pas d'équivalent .NET MAUI.
Xamarin.Forms.Device.GetNamedSize Pas d'é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 Pas d'é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 la 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 montre les remplacements .NET MAUI pour la fonctionnalité dans l'espace de nom Xamarin.Forms.Maps :

Xamarin.Forms Interface de Programmation d'Applications (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 Pas d'é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 du type Xamarin.Forms.Maps.Position ont changé pour le type Microsoft.Maui.Devices.Sensors.Location.
Xamarin.Forms.Maps.Geocoder Microsoft.Maui.Devices.Sensors.Geocoding Les membres du type Xamarin.Forms.Maps.Geocoder ont changé pour le type Microsoft.Maui.Devices.Sensors.Geocoding.

.NET MAUI dispose de deux types Map - Microsoft.Maui.Controls.Maps.Map et Microsoft.Maui.ApplicationModel.Map. Étant donné que l'espace de noms Microsoft.Maui.ApplicationModel est l'une des directives de .NET MAUI global using, lorsque vous utilisez le contrôle Microsoft.Maui.Controls.Maps.Map depuis le code, vous devrez qualifier entièrement votre utilisation de Map ou utiliser un alias using.

Dans XAML, une définition d'espace de noms xmlns doit être ajoutée pour le contrôle Map. Bien que cela ne soit pas nécessaire, cela empêche une collision entre les types Polygon et Polyline, qui existent dans les espaces de noms Microsoft.Maui.Controls.Maps et Microsoft.Maui.Controls.Shapes. Pour plus d'informations, voir Afficher une carte.

Autres modifications

Un petit nombre d'autres API ont été consolidées lors du passage de Xamarin.Forms à .NET MAUI. Le tableau suivant montre ces changements :

Xamarin.Forms Interface de Programmation d'Applications (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 donc 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 donc ToolbarItem.Name devient ToolbarItem.Text.

De plus, dans Xamarin.Forms, la substitution Page.OnAppearing est appelée sur Android lorsqu'une application est envoyée en arrière-plan puis ramenée au premier plan. Cependant, cette surcharge n'est pas appelée sur iOS et Windows dans le même scénario. Dans .NET MAUI, la surcharge OnAppearing() n'est appelée sur aucune plateforme lorsqu'une application est mise en arrière-plan puis ramenée au premier plan. Au lieu de cela, vous devriez écouter les événements du cycle de vie sur Window pour être informé lorsque l'application revient au premier plan. Pour plus d'informations, consultez .NET MAUI.

Modifications des formulaires natifs

Formulaires natifs dans Xamarin.Forms est devenu une intégration native dans .NET MAUI, et utilise une approche d'initialisation différente et des méthodes d'extension différentes pour convertir les contrôles multiplateformes en leurs types natifs. Pour plus d'informations, voir Native embedding.

Modifications d'AssemblyInfo

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

Optionnellement, vous pouvez conserver le fichier AssemblyInfo.cs et définir la propriété GenerateAssemblyInfo dans votre fichier de projet à false :

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

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

Mettre à jour les dépendances de l'application

En général, les packages NuGet ne sont pas compatibles avec .NET 8, sauf s'ils ont été recompilés en utilisant des monikers de framework cible pour .NET. Toutefois, les applications Android peuvent utiliser des packages NuGet ciblant les frameworks monoandroid et monoandroidXX.X.

Vous pouvez confirmer qu'un package est compatible avec .NET 8 en consultant l'onglet Frameworks sur NuGet pour le package que vous utilisez, et en vérifiant qu'il répertorie l'un des frameworks compatibles indiqués dans le tableau suivant :

Cadres compatibles Cadres 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 pas de dépendances sur les frameworks incompatibles listés ci-dessus restent compatibles avec .NET 8.

Si un package sur NuGet indique une compatibilité avec l'un des cadres compatibles ci-dessus, même s'il inclut également des cadres incompatibles, alors le package est compatible. Des packages NuGet compatibles peuvent être ajoutés à votre projet de bibliothèque .NET MAUI en utilisant le gestionnaire de packages NuGet dans Visual Studio.

Si vous ne pouvez pas trouver une version compatible avec .NET 8 d'un package NuGet, vous devriez :

  • Recompiler le package avec les TFMs .NET, si vous possédez le code.
  • Recherchez une version préliminaire d'une version .NET 8 du package.
  • Remplacez la dépendance par une alternative compatible avec .NET 8.

Compiler et résoudre les problèmes

Une fois vos dépendances résolues, vous devez construire votre projet. Toute erreur vous guidera vers les étapes suivantes.

Conseil / Astuce

  • Supprimez tous les dossiers bin et obj de tous les projets avant d'ouvrir et de construire des projets dans Visual Studio, en particulier lors du changement de versions de .NET.
  • Supprimez le fichier généré Resource.designer.cs du projet Android.

Le tableau suivant fournit des conseils pour surmonter les problèmes courants de compilation ou d'exécution.

Problème Conseil / Astuce
Xamarin.* espace de noms n'existe pas. Mettez à jour l'espace de noms pour son équivalent .NET MAUI. Pour plus d'informations, voir Changements de nom d'espace.
L'API n'existe pas. Mettez à jour l'utilisation de l'API pour son équivalent .NET MAUI. Pour plus d'informations, consultez API changes.
L'application ne se déploie pas. Assurez-vous que le projet de plateforme requis est configuré pour être déployé dans le gestionnaire de configuration de Visual Studio.
L'application ne se lance pas. Mettre à jour la classe du point d'entrée de chaque projet de plateforme, ainsi que 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 du CollectionView. Par défaut, le contrôle occupera autant d'espace que le permet le conteneur. Un Grid contraint les enfants à sa propre taille. Cependant, un StackLayout permet aux enfants d'occuper un espace au-delà de ses limites.
La fenêtre contextuelle s'affiche sous la page sur iOS. Dans Xamarin.Forms, tous les pop-ups sur iOS sont des instances de UIWindow, mais dans .NET MAUI, les pop-ups sont affichés en localisant l'élément de présentation actuel ViewController et en affichant le pop-up avec PresentViewControllerAsync. Dans des modules tels que Mopups, pour vous assurer que vos fenêtres contextuelles s'affichent correctement, vous devez appeler DisplayAlert (ou DisplayAlertAsync dans .NET 10+), DisplayActionSheet (ou DisplayActionSheetAsync dans .NET 10+), ou DisplayPromptAsync à partir du ContentPage utilisé à l'intérieur de la fenêtre contextuelle Mopup.
BoxView n'apparaît pas. La taille par défaut d'un BoxView dans Xamarin.Forms est de 40x40. La taille par défaut d'un BoxView dans .NET MAUI est 0x0. Réglez WidthRequest et HeightRequest sur 40.
La mise en page manque d'espacement interne, de marge ou d'espacement. Ajoutez des valeurs par défaut à votre projet basées sur la ressource de style de .NET MAUI. Pour plus d'informations, voir Les modifications de la valeur par défaut à partir de Xamarin.Forms.
La mise en page personnalisée ne fonctionne pas. Le code de mise en page personnalisée doit être mis à jour pour fonctionner avec .NET MAUI. Pour plus d'informations, consultez Modifications de la disposition personnalisée.
Le moteur de rendu personnalisé ne fonctionne pas. Le code du renderer doit être mis à jour pour fonctionner dans .NET MAUI. Pour plus d'informations, voir Utiliser des renderers personnalisés dans .NET MAUI.
L'effet ne fonctionne pas. Le code de l'effet doit être mis à jour pour fonctionner dans .NET MAUI. Pour plus d'informations, consultez Use effects in .NET MAUI.
SkiaSharp code ne fonctionne pas. SkiaSharp le code nécessite des mises à jour mineures pour fonctionner avec .NET MAUI. Pour plus d'informations, voir SkiaSharp.
Impossible d'accéder aux données des propriétés de l'application précédemment créées. Migrez les données des propriétés de l'application vers les préférences de .NET MAUI. Pour plus d'informations, consultez Xamarin.Forms.
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, voir Migrer de Xamarin.Essentials secure storage vers .NET MAUI secure storage.
Impossible d'accéder aux données de suivi de version 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 de version d'une application Xamarin.Forms vers une application .NET MAUI.