Delen via

Een Xamarin.Forms-app handmatig upgraden naar een enkel project .NET MAUI-app

Als u een Xamarin.Forms app wilt migreren naar een enkel project .NET Multi-platform App UI-app (.NET MAUI), moet u het volgende doen:

  • Werk je Xamarin.Forms app bij om Xamarin.Forms 5 te gebruiken.
  • Werk de afhankelijkheden van de app bij naar de nieuwste versies.
  • Zorg ervoor dat de app nog steeds werkt.
  • Maak een .NET MAUI-app.
  • Kopieer code en configuratie van de Xamarin.Forms app naar de .NET MAUI-app.
  • Kopieer resources van uw Xamarin.Forms app naar de .NET MAUI-app.
  • Werk namespaces bij.
  • Behandel eventuele API-wijzigingen.
  • Upgrade of vervang incompatibele afhankelijkheden door .NET 8-versies.
  • Compileer en test je app.

Om het upgradeproces te vereenvoudigen, moet u een nieuwe .NET MAUI-app met dezelfde naam maken als uw Xamarin.Forms app en vervolgens kopiëren in uw code, configuratie en resources. Dit is de aanpak die hieronder wordt uiteengezet.

Werk je Xamarin.Forms app bij

Voordat u uw Xamarin.Forms-app upgrade naar .NET MAUI, moet u eerst uw Xamarin.Forms-app updaten zodat deze Xamarin.Forms 5 gebruikt en ervoor zorgen dat deze nog steeds correct werkt. Daarnaast moet u de afhankelijkheden die uw app gebruikt bijwerken naar de nieuwste versies.

Dit zal helpen om de rest van het migratieproces te vereenvoudigen, omdat het de API-verschillen tussen Xamarin.Forms en .NET MAUI zal minimaliseren en ervoor zal zorgen dat je de .NET-compatibele versies van je afhankelijkheden gebruikt, indien deze bestaan.

Een .NET MAUI-app maken

Maak in Visual Studio een nieuwe .NET MAUI-app met dezelfde naam als uw Xamarin.Forms app:

Schermopname van het maken van een .NET MAUI-app in Visual Studio.

Als u het projectbestand opent, wordt bevestigd dat u een .NET SDK-project hebt.

Code kopiëren naar de .NET MAUI-app

Alle platformoverschrijdende code van uw Xamarin.Forms bibliotheekproject moet worden gekopieerd naar uw .NET MAUI-app-project in identieke benoemde mappen en bestanden.

Aangepaste renderers kunnen opnieuw worden gebruikt in een .NET MAUI-app of worden gemigreerd naar een .NET MAUI-handler. Zie Aangepaste renderers hergebruiken in .NET MAUI en Een aangepaste renderer migreren Xamarin.Forms naar een .NET MAUI-handler voor meer informatie.

Effecten kunnen opnieuw worden gebruikt in een .NET MAUI-app. Zie Hergebruikeffecten voor meer informatie.

Opmerking

U kunt uw Xamarin.Forms naamruimten snel bijwerken naar Microsoft.Maui door Snelle acties in Visual Studio te gebruiken, op voorwaarde dat u Upgrade Assistant heeft geïnstalleerd.

Platformspecifieke code

Een .NET MAUI-app-project bevat een map Platforms , waarbij elke onderliggende map een platform vertegenwoordigt waarop .NET MAUI zich kan richten:

Schermopname van platformmappen.

De mappen voor elk platform bevatten platformspecifieke resources en code waarmee de app op elk platform wordt gestart:

Schermopname van platformspecifieke code.

Code en de bijbehorende mappen uit uw Xamarin.Forms hoofdprojecten moeten worden gekopieerd naar deze mappen:

  • Code van uw Xamarin.Forms Android-hoofdproject moet worden gekopieerd naar de map Platform\Android van uw .NET MAUI-app-project. Kopieer bovendien alle aangepaste code van uw Xamarin.FormsMainActivity en MainApplication klassen naar dezelfde klassen in uw .NET MAUI-app-project.

  • Code van uw Xamarin.Forms iOS-hoofdproject moet worden gekopieerd naar de map Platforms\iOS van uw .NET MAUI-app-project. Kopieer bovendien alle aangepaste code van uw Xamarin.FormsAppDelegate klas naar dezelfde klasse in uw .NET MAUI-app-project.

    Opmerking

    Zie Belangrijke wijzigingen in .NET voor iOS voor een lijst met belangrijke wijzigingen in .NET voor iOS.

  • Code van uw Xamarin.Forms UWP-hoofdproject moet worden gekopieerd naar de map Platforms\Windows van uw .NET MAUI-app-project. Kopieer bovendien alle aangepaste code van uw Xamarin.FormsApp klas naar dezelfde klasse in uw .NET MAUI-app-project.

Tijdens de build bevat het buildsysteem alleen de code uit elke map bij het bouwen voor dat specifieke platform. Wanneer u bijvoorbeeld bouwt voor Android, worden de bestanden in de map Platforms\Android ingebouwd in het app-pakket, maar de bestanden in de andere platformsmappen zijn niet. Deze benadering maakt gebruik van multi-targeting om meerdere platforms vanuit één project te ondersteunen. .NET MAUI-apps kunnen ook meerdere doelgroepen hebben op basis van uw eigen bestandsnaam- en mapcriteria. Hiermee kunt u uw .NET MAUI-app-project structureren, zodat u uw platformcode niet hoeft te plaatsen in onderliggende mappen van de map Platforms . Zie Multi-targeting configurerenvoor meer informatie.

Configuratie kopiëren naar de .NET MAUI-app

Elk platform gebruikt een eigen manifestbestand voor apps om informatie op te geven, zoals de app-titel, id, versie en meer. Met één .NET MAUI-project kunt u deze algemene app-gegevens opgeven op één locatie in het projectbestand.

Als u de manifestgegevens van de gedeelde app voor een project wilt opgeven, opent u het snelmenu voor het project in Solution Explorer en kiest u Vervolgens Eigenschappen. De app-titel, -id en -versie kunnen vervolgens worden opgegeven in MAUI Shared > General:

Schermopname van het manifest van de .NET MAUI-app.

Tijdens het bouwen worden de manifestgegevens van de gedeelde app samengevoegd met platformspecifieke gegevens in het systeemeigen app-manifestbestand om het manifestbestand voor het app-pakket te produceren. Zie Projectconfiguratie in .NET MAUI - SHARED voor meer informatie.

De resterende gegevens uit uw Xamarin.Forms app-manifesten moeten worden gekopieerd naar uw .NET MAUI-app-manifest:

  • Kopieer op Android eventuele extra gegevens uit het AndroidManifest.xml-bestand in uw Xamarin.Forms Android-hoofdproject naar het platformbestand\Android\AndroidManifest.xml in uw .NET MAUI-app-project.
  • In iOS kopieert u eventuele extra gegevens uit het bestand Info.plist in uw Xamarin.Forms iOS-hoofdproject naar het bestand Platforms\iOS\Info.plist in uw .NET MAUI-app-project. Kopieer bovendien het bestand Entitlements.plist in uw Xamarin.Forms iOS-hoofdproject naar de map Platforms\iOS in uw .NET MAUI-app-project.
  • Kopieer in Windows aanvullende gegevens uit het bestand Package.appxmanifest in uw Xamarin.Forms UWP-hoofdproject naar het bestand Platforms\Windows\Package.appxmanifest in uw .NET MAUI-app-project.

Resources kopiëren naar de .NET MAUI-app

Met één .NET MAUI-project kunnen resourcebestanden op één locatie worden opgeslagen terwijl ze op elk platform worden gebruikt. Dit omvat lettertypen, afbeeldingen, het app-pictogram, het welkomstscherm, onbewerkte assets en CSS-bestanden voor het stylen van .NET MAUI-apps.

Resourcebestanden moeten doorgaans worden geplaatst in de map Resources van uw .NET MAUI-app-project of onderliggende mappen van de map Resources en moeten hun buildactie juist hebben ingesteld. In de volgende tabel ziet u de buildacties voor elk resourcebestandstype:

Hulpbron Bouwactie
App-pictogram MauiIcon
Lettertypen MauiFont
Afbeeldingen MauiImage
Plonsscherm MauiSplashScreen
Onbewerkte middelen MauiAsset
CSS-bestanden MauiCss

Opmerking

XAML-bestanden worden ook opgeslagen in uw .NET MAUI-app-project en krijgen automatisch de MauiXaml build-actie toegewezen. Alleen XAML-resourcewoordenlijsten worden doorgaans echter in de map Resources van het app-project geplaatst.

In de volgende schermafbeelding ziet u een typische map Resources met onderliggende mappen voor elk resourcetype:

Schermopname van afbeeldings- en lettertypebronnen.

De buildactie voor een resourcebestand wordt correct ingesteld als de resource is toegevoegd aan de juiste onderliggende map Resources .

Belangrijk

Platformspecifieke resources overschrijven hun gedeelde resource-tegenhangers. Als u bijvoorbeeld een Android-specifieke afbeelding hebt op Platforms\Android\Resources\drawable-xhdpi\logo.png en u ook een gedeelde resources\Afbeeldingen\logo.svg afbeelding opgeeft, wordt het SVG-bestand (Scalable Vector Graphics) gebruikt om de verplichte Android-afbeeldingen te genereren, behalve de XHDPI-afbeelding die al bestaat als platformspecifieke afbeelding.

App-pictogrammen

Uw Xamarin.Forms-app-pictogram moet worden toegevoegd aan uw .NET MAUI-app-project door de afbeelding naar de map Resources\AppIcon van het project te slepen, waar de build-actie automatisch wordt ingesteld op MauiIcon. Tijdens de build wordt het app-pictogram aangepast aan de juiste grootten voor het doelplatform en het doelapparaat. App-pictogrammen worden aangepast aan meerdere resoluties, omdat ze meerdere toepassingen hebben, zoals worden gebruikt om de app op het apparaat en in de App Store weer te geven.

Zie Een app-pictogram toevoegen aan een .NET MAUI-app-project voor meer informatie.

Plonsscherm

Als uw Xamarin.Forms app een opstartscherm heeft, moet deze worden toegevoegd aan uw .NET MAUI-app-project door de afbeelding naar de map Resources\Splash van het project te slepen, waarbij de build-actie automatisch wordt ingesteld op MauiSplashScreen. Tijdens de build wordt de grootte van de afbeelding van het welkomstscherm aangepast aan de juiste grootte voor het doelplatform en apparaat.

Zie Een welkomstscherm toevoegen aan een .NET MAUI-app-project voor meer informatie.

Afbeeldingen

Apparaten hebben een scala aan schermgrootten en -densiteiten en elk platform heeft functionaliteit voor het weergeven van dichtheidsafhankelijke afbeeldingen. In Xamarin.Forms worden dichtheidsafhankelijke afbeeldingen meestal in hoofdprojecten geplaatst en nemen ze een platformspecifieke naamconventie aan. Er zijn twee benaderingen die kunnen worden genomen om deze afbeeldingen te migreren naar .NET MAUI.

De aanbevolen methode is om de hoogste resolutieversie van elke installatiekopie van uw Xamarin.Forms oplossing naar uw .NET MAUI-app-project te kopiëren door deze naar de map Resources\Images van het project te slepen, waarbij de build-actie automatisch wordt ingesteld op MauiImage. Het is ook nodig om het BaseSize kenmerk van elke bitmapafbeelding in te stellen om ervoor te zorgen dat het formaat wordt gewijzigd. Dit elimineert de noodzaak om meerdere versies van elke afbeelding op elk platform te hebben. Tijdens de bouwtijd worden alle afbeeldingen vervolgens aangepast en in meerdere dichtheid-afhankelijke formaten omgezet die aan de platformvereisten voldoen. Zie Afbeeldingen toevoegen aan een .NET MAUI-app-project voor meer informatie.

U kunt ook dichtheidsafhankelijke afbeeldingen van uw Xamarin.Forms oplossing kopiëren naar identieke benoemde mappen in de map Platforms\{Platform} van uw .NET MAUI-app-project en hun buildacties instellen op de buildacties die in uw Xamarin.Forms oplossing worden gebruikt. De volgende tabel bevat voorbeeldafbeeldingslocaties voor een Xamarin.Forms oplossing en hun equivalente locatie in een .NET MAUI-app-project:

Xamarin.Forms afbeeldingslocatie Locatie van .NET MAUI-afbeeldingen Buildactie voor .NET MAUI-platforminstallatiekopieën
{MyApp.Android}\Resources\drawable-xhdpi\image.png Platformen\Android\Resources\drawable-xhdpi\image.png AndroidResource
{MyApp.iOS}\image.jpg *Platforms\iOS\Resources\image.jpg BundleResource
{MyApp.UWP}\Assets\Images\image.gif *Platformen\Windows\Assets\Images\image.gif Inhoud

Op voorwaarde dat u dezelfde naamconventie voor afbeeldingen hebt gebruikt als in uw Xamarin.Forms oplossing, wordt de juiste afbeelding tijdens het uitvoeren gekozen op basis van de mogelijkheden van het apparaat. Het nadeel van deze benadering is dat u nog steeds meerdere versies van elke afbeelding op elk platform hebt.

Lettertypen

Alle lettertypen uit uw Xamarin.Forms oplossing kunnen worden toegevoegd aan uw .NET MAUI-oplossing door ze naar de map Resources\Fonts van uw .NET MAUI-app-project te slepen, waarbij hun buildactie automatisch wordt ingesteld op MauiFont.

Zie Lettertypen voor meer informatie.

CSS-bestanden

Vanuit uw Xamarin.Forms-oplossing kunnen CSS-bestanden worden toegevoegd aan uw .NET MAUI-oplossing door ze in een map met dezelfde naam te slepen en de buildactie in te stellen op MauiCss in het venster Eigenschappen.

Zie Apps stylen met Cascading Style Sheets voor meer informatie over het gebruik van CSS-bestanden in een .NET MAUI-app.

Onbewerkte activa

Alle onbewerkte assetbestanden, zoals HTML, JSON en video, moeten worden gekopieerd van uw Xamarin.Forms oplossing naar uw .NET MAUI-app-project door ze naar de map Resources\Raw van uw project te slepen, waarbij hun buildactie automatisch wordt ingesteld op MauiAsset.

Gelokaliseerde bronnen

In een .NET MAUI-app worden tekenreeksen gelokaliseerd met dezelfde methode als in een Xamarin.Forms app. Daarom moeten uw .NET-resourcebestanden (.resx) worden gekopieerd van uw Xamarin.Forms oplossing naar een identiek benoemde map in uw .NET MAUI-oplossing. Vervolgens moet de neutrale taal van uw .NET MAUI-app worden opgegeven. Zie De neutrale taal van de app opgeven voor meer informatie.

Opmerking

.NET-resourcebestanden hoeven niet te worden geplaatst in de map Resources van uw .NET MAUI-app-project.

In een .NET MAUI-app worden afbeeldingen gelokaliseerd met behulp van dezelfde methode als in een Xamarin.Forms app. Daarom moeten uw gelokaliseerde afbeeldingen en de mappen waarin ze zich bevinden, worden gekopieerd van uw Xamarin.Forms oplossing naar uw .NET MAUI-app-project:

  • Op Android is de hoofdmap in uw .NET MAUI-app-project voor gelokaliseerde afbeeldingen Platforms\Android\Resources.
  • In iOS is de hoofdmap in uw .NET MAUI-app-project voor gelokaliseerde afbeeldingen Platforms\iOS\Resources.
  • Op Windows is de hoofdmap in uw .NET MAUI-app-project voor gelokaliseerde afbeeldingen Platforms\Windows\Assets\Images.

Gelokaliseerde afbeeldingen moeten hun buildacties instellen op de buildacties die in uw Xamarin.Forms oplossing worden gebruikt. Zie Afbeeldingen lokaliseren voor meer informatie.

In een .NET MAUI-app worden app-namen gelokaliseerd met dezelfde benadering als in een Xamarin.Forms app:

  • Op Android kan de gelokaliseerde app-naam worden opgeslagen met behulp van een naamconventie op basis van mappen in de map Platforms\Android\Resources . Mappen en bestanden voor app-naamlokalisatie moeten vanuit uw Xamarin.Forms oplossing naar deze map worden gekopieerd.
  • In iOS wordt de gelokaliseerde app-naam opgeslagen met behulp van een naamconventie op basis van mappen in de map Platforms\iOS\Resources . Mappen en bestanden voor app-naamlokalisatie moeten vanuit uw Xamarin.Forms oplossing naar deze map worden gekopieerd.
  • In Windows wordt de gelokaliseerde app-naam opgeslagen in het app-pakketmanifest.

Zie De naam van de app lokaliseren voor meer informatie. Zie Lokalisatie voor meer informatie over lokalisatie van .NET MAUI-apps.

Wijzigingen in naamruimten

De namespaces zijn gewijzigd bij de overgang van Xamarin.Forms naar .NET MAUI, en Xamarin.Essentials-functies maken nu deel uit van .NET MAUI. Voor het bijwerken van namespaces dient u een zoek-en-vervang uit te voeren voor de volgende namespaces:

Xamarin.Forms naamruimte .NET MAUI-naamruimten
Xamarin.Forms Microsoft.Maui en Microsoft.Maui.Controls
Xamarin.Forms.DualScreen Microsoft.Maui.Controls.Foldable
Xamarin.Forms.Maps Microsoft.Maui.Controls.Maps en 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

.NET MAUI-projecten maken gebruik van impliciete global using directieven. Deze functie stelt je in staat om using richtlijnen voor de Xamarin.Essentials naamruimte te verwijderen, zonder dat je ze hoeft te vervangen door de equivalente .NET MAUI naamruimtes.

Bovendien is de standaard XAML-naamruimte in .NET MAUI veranderd van http://xamarin.com/schemas/2014/forms in Xamarin.Forms naar http://schemas.microsoft.com/dotnet/2021/maui. Vervang daarom alle gevallen van xmlns="http://xamarin.com/schemas/2014/forms" door xmlns="http://schemas.microsoft.com/dotnet/2021/maui".

Opmerking

U kunt uw Xamarin.Forms naamruimten snel bijwerken naar Microsoft.Maui door Snelle acties in Visual Studio te gebruiken, op voorwaarde dat u Upgrade Assistant heeft geïnstalleerd.

API-wijzigingen

Sommige API's zijn gewijzigd in de overstap van Xamarin.Forms, naar .NET MAUI. Dit zijn meerdere redenen, waaronder het verwijderen van dubbele functionaliteit veroorzaakt doordat Xamarin.Essentials onderdeel werd van .NET MAUI, en ervoor zorgen dat de API's de .NET naamgevingsrichtlijnen volgen. De volgende secties bespreken deze veranderingen.

Kleurwijzigingen

In Xamarin.Forms, de Xamarin.Forms.Color struct kunt u Color objecten creëren met behulp van double waarden en biedt benoemde kleuren, zoals Xamarin.Forms.Color.AliceBlue. In .NET MAUI is deze functionaliteit opgesplitst in de Microsoft.Maui.Graphics.Color-klasse en de Microsoft.Maui.Graphics.Colors-klasse.

De Microsoft.Maui.Graphics.Color klasse, in de Microsoft.Maui.Graphics namespace, stelt je in staat Color objecten te construeren met behulp van float waarden, byte waarden, en int waarden. De Microsoft.Maui.Graphics.Colors klasse, die zich ook in de Microsoft.Maui.Graphics namespace bevindt, biedt grotendeels dezelfde benoemde kleuren. Bijvoorbeeld, gebruik Colors.AliceBlue om de AliceBlue kleur te specificeren.

De volgende tabel toont de API-wijzigingen tussen de Xamarin.Forms.Color struct en de Microsoft.Maui.Graphics.Color class.

Xamarin.Forms API .NET MAUI API Opmerking
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 eigenschap vervangen door een methode in .NET MAUI.
Xamarin.Forms.Color.Saturation Microsoft.Maui.Graphics.Color.GetSaturation Xamarin.Forms eigenschap vervangen door een methode in .NET MAUI.
Xamarin.Forms.Color.Luminosity Microsoft.Maui.Graphics.Color.GetLuminosity Xamarin.Forms eigenschap vervangen door een methode in .NET MAUI.
Xamarin.Forms.Color.Default Geen equivalent voor .NET MAUI. In plaats daarvan, vallen Microsoft.Maui.Graphics.Color-objecten standaard terug op null.
Xamarin.Forms.Color.Accent Geen equivalent voor .NET MAUI.
Xamarin.Forms.Color.FromHex Microsoft.Maui.Graphics.Color.FromArgb Microsoft.Maui.Graphics.Color.FromHex is verouderd en zal in een toekomstige versie worden verwijderd.

Bovendien zijn alle numerieke waarden in een Microsoft.Maui.Graphics.Colorfloat, in plaats van double zoals gebruikt in Xamarin.Forms.Color.

Opmerking

In tegenstelling tot Xamarin.Forms heeft een Microsoft.Maui.Graphics.Color geen impliciete conversie naar System.Drawing.Color.

Layoutwijzigingen

De volgende tabel bevat een overzicht van de layout-API's die zijn verwijderd bij de overgang van Xamarin.Forms naar .NET MAUI.

Xamarin.Forms API .NET MAUI API Opmerkingen
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add De Add overload die drie argumenten accepteert, is niet aanwezig in .NET MAUI.
Xamarin.Forms.Grid.IGridList<T>.AddHorizontal Geen equivalent voor .NET MAUI.
Xamarin.Forms.Grid.IGridList<T>.AddVertical Geen equivalent voor .NET MAUI.
Xamarin.Forms.RelativeLayout Microsoft.Maui.Controls.Compatibility.RelativeLayout Binnen .NET MAUI bestaat RelativeLayout alleen als een compatibiliteitscontrole voor gebruikers die migreren vanaf Xamarin.Forms. Gebruik in plaats daarvan Grid, of voeg xmlns toe voor de compatibiliteitsnamespace.

Bovendien wordt het toevoegen van kinderen aan een lay-out in code in Xamarin.Forms gerealiseerd door het toevoegen van de kinderen aan de Children verzameling van de lay-out.

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

In .NET INTERNAL is de Children verzameling bedoeld voor intern gebruik door .NET INTERNAL en mag deze niet rechtstreeks worden gemanipuleerd. Daarom moeten kinderen in de code direct aan de lay-out worden toegevoegd.

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

Belangrijk

Alle Add lay-outuitbreidingsmethoden, zoals GridExtensions.Add, worden op de lay-out aangeroepen in plaats van op de Children-verzameling van lay-outs.

U ziet mogelijk dat bij het uitvoeren van uw bijgewerkte .NET MAUI-app het lay-outgedrag anders is. Voor meer informatie, zie Layoutgedragswijzigingen van Xamarin.Forms.

Aangepaste lay-outwijzigingen

Het proces voor het maken van een aangepaste lay-out in Xamarin.Forms houdt in dat er een klasse wordt aangemaakt die afstamt van Layout<View>, en het overschrijven van de VisualElement.OnMeasure en Layout.LayoutChildren methoden. Voor meer informatie, zie Een aangepaste indeling maken in Xamarin.Forms.

In .NET MAUI zijn de opmaakklassen afgeleid van de abstracte Layout klasse. Deze klasse delegeert het platformonafhankelijke ontwerp en de meting aan een lay-out manager klasse. Elke layout manager klasse implementeert de ILayoutManager interface, die specificeert dat Measure en ArrangeChildren implementaties moeten worden geleverd.

  • De Measure-implementatie roept IView.Measure aan op elke weergave in de lay-out en retourneert de totale grootte van de lay-out gezien de beperkingen.
  • De ArrangeChildren implementatie bepaalt waar elke weergave binnen de grenzen van de lay-out moet worden geplaatst en roept Arrange aan voor elke weergave met de juiste grenzen. De retourwaarde is de werkelijke grootte van de lay-out.

Voor meer informatie, zie Aangepaste ontwerpen.

Apparaatwijzigingen

Xamarin.Forms heeft een Xamarin.Forms.Device klasse die je helpt om te communiceren met het apparaat en het platform waarop de app draait. De equivalente klasse in .NET MAUI, Microsoft.Maui.Controls.Device, is verouderd en de functionaliteit ervan is vervangen door meerdere typen.

De volgende tabel toont de .NET MAUI-vervangingen voor de functionaliteit in de Xamarin.Forms.Device-klasse:

Xamarin.Forms API .NET MAUI API Opmerkingen
Xamarin.Forms.Device.Android Microsoft.Maui.Devices.DevicePlatform.Android
Xamarin.Forms.Device.iOS Microsoft.Maui.Devices.DevicePlatform.iOS
Xamarin.Forms.Device.GTK Geen equivalent voor .NET MAUI.
Xamarin.Forms.Device.macOS Geen equivalent voor .NET MAUI. Gebruik in plaats daarvan 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 Geen equivalent voor .NET MAUI.
Xamarin.Forms.Device.Flags Geen equivalent voor .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 Geen equivalent voor .NET MAUI.
Xamarin.Forms.Device.GetNamedSize Geen equivalent voor .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 Geen equivalent voor .NET MAUI.
Xamarin.Forms.Device.SetFlowDirection Microsoft.Maui.Controls.Window.FlowDirection
Xamarin.Forms.Device.StartTimer Microsoft.Maui.Dispatching.DispatcherExtensions.StartTimer of Microsoft.Maui.Dispatching.Dispatcher.DispatchDelayed

Kaartwijzigingen

In Xamarin.Forms bevinden de Map-besturing en bijbehorende typen zich in de Xamarin.Forms.Maps-naamruimte. In .NET MAUI is deze functionaliteit verplaatst naar de Microsoft.Maui.Controls.Maps en Microsoft.Maui.Maps naamruimten. Sommige eigenschappen zijn hernoemd en sommige typen zijn vervangen door equivalente typen van Xamarin.Essentials.

De volgende tabel toont de .NET MAUI-vervangingen voor de functionaliteit in de Xamarin.Forms.Maps namespace:

Xamarin.Forms API .NET MAUI API Opmerking
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 Geen equivalent voor .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 Leden van type Xamarin.Forms.Maps.Position zijn gewijzigd naar het type Microsoft.Maui.Devices.Sensors.Location.
Xamarin.Forms.Maps.Geocoder Microsoft.Maui.Devices.Sensors.Geocoding Leden van type Xamarin.Forms.Maps.Geocoder zijn gewijzigd naar het type Microsoft.Maui.Devices.Sensors.Geocoding.

.NET MAUI heeft twee Map typen - Microsoft.Maui.Controls.Maps.Map en Microsoft.Maui.ApplicationModel.Map. Omdat de Microsoft.Maui.ApplicationModel namespace een van de global using richtlijnen van .NET MAUI is, moet je bij het gebruik van de Microsoft.Maui.Controls.Maps.Map besturingselement vanuit code je Map gebruik volledig kwalificeren of een using alias gebruiken.

In XAML moet een xmlns namespace-definitie worden toegevoegd voor de Map controle. Hoewel dit niet vereist is, voorkomt het een botsing tussen de Polygon en Polyline types, die in zowel de Microsoft.Maui.Controls.Maps als Microsoft.Maui.Controls.Shapes naamruimten bestaan. Voor meer informatie, zie Een kaart weergeven.

Andere wijzigingen

Een klein aantal andere API's is samengevoegd bij de overgang van Xamarin.Forms naar .NET MAUI. De volgende tabel toont deze wijzigingen.

Xamarin.Forms API .NET MAUI API Opmerkingen
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 In Xamarin.Forms accepteert de ApplyQueryAttributes-methode een IDictionary<string, string>-argument. In .NET MAUI accepteert de ApplyQueryAttributes methode een IDictionary<string, object> argument.
Xamarin.Forms.MenuItem.Icon Microsoft.Maui.Controls.MenuItem.IconImageSource Xamarin.Forms.MenuItem.Icon is de basisklasse van Xamarin.Forms.ToolbarItem, en daarom wordt ToolbarItem.IconToolbarItem.IconImageSource.
Xamarin.Forms.OrientationStateTrigger.Orientation Microsoft.Maui.Controls.OrientationStateTrigger.Orientation In Xamarin.Forms, de OrientationStateTrigger.Orientation eigenschap is van het type Xamarin.Forms.Internals.DeviceOrientation. In .NET MAUI, de OrientationStateTrigger.Orientation-eigenschap is van het 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 is de basisklasse van Microsoft.Maui.Controls.ToolbarItem, en daarom wordt ToolbarItem.NameToolbarItem.Text.

Bovendien wordt in Xamarin.Forms de Page.OnAppearing override aangeroepen op Android wanneer een app op de achtergrond wordt geplaatst en daarna weer op de voorgrond wordt gehaald. Deze override wordt echter in hetzelfde scenario niet aangeroepen op iOS en Windows. In .NET MAUI wordt de OnAppearing() override niet aangeroepen op platforms wanneer een app op de achtergrond is en vervolgens naar de voorgrond wordt gehaald. In plaats daarvan moet je luisteren naar lifecycle events op Window om op de hoogte te worden gebracht wanneer een app naar de voorgrond terugkeert. Voor meer informatie, zie .NET MAUI windows.

Wijzigingen in inheemse vormen

Native forms in Xamarin.Forms zijn native embedding geworden in .NET MAUI en gebruiken een andere initiëringsmethode en andere uitbreidingsmethoden om platformonafhankelijke controles om te zetten naar hun native typen. Zie Systeemeigen insluitenvoor meer informatie.

Wijzigingen in AssemblyInfo

Eigenschappen die doorgaans worden ingesteld in een AssemblyInfo.cs-bestand zijn nu beschikbaar in je SDK-stijl project. We raden aan om ze in elk project van AssemblyInfo.cs naar uw projectbestand te migreren, en het bestand AssemblyInfo.cs te verwijderen.

Optioneel kunt u het AssemblyInfo.cs-bestand behouden en de GenerateAssemblyInfo-eigenschap in uw projectbestand instellen op false:

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

Voor meer informatie over de GenerateAssemblyInfo-eigenschap, zie GenerateAssemblyInfo.

Werk app-afhankelijkheden bij

Over het algemeen zijn Xamarin.Forms NuGet-pakketten niet compatibel met .NET 8, tenzij ze opnieuw gecompileerd zijn met behulp van .NET target framework monikers (TFM's). Echter, Android-apps kunnen NuGet-pakketten gebruiken die gericht zijn op de monoandroid en monoandroidXX.X frameworks.

U kunt bevestigen dat een pakket compatibel is met .NET 8 door op het tabblad Frameworks op NuGet te kijken voor het pakket dat u gebruikt en te controleren of het een van de compatibele frameworks vermeldt die in de volgende tabel worden weergegeven:

Compatibele frameworks Onverenigbare kaders
net8.0-android, monoandroid, monoandroidXX.X
net8.0-ios monotouch, xamarinios, xamarinios10
net8.0-macos monomac, xamarinmac, xamarinmac20
net8.0-tvos xamarintvos
xamarinwatchos

Opmerking

.NET Standard-bibliotheken die geen afhankelijkheden hebben van de hierboven genoemde incompatibele frameworks zijn nog steeds compatibel met .NET 8.

Als een pakket op NuGet aangeeft compatibel te zijn met een van de hierboven genoemde compatibele frameworks, ongeacht of er ook niet-compatibele frameworks zijn opgenomen, dan is het pakket compatibel. Compatibele NuGet-pakketten kunnen aan je .NET MAUI-bibliotheekproject worden toegevoegd via de NuGet-pakketbeheerder in Visual Studio.

Als je geen .NET 8-compatibele versie van een NuGet-pakket kunt vinden, moet je:

  • Compileer het pakket opnieuw met .NET TFM's als u de eigenaar bent van de code.
  • Zoek naar een preview-versie van een .NET 8-versie van het pakket.
  • Vervang de afhankelijkheid door een .NET 8-compatibel alternatief.

Compileer en zoek problemen op

Zodra uw afhankelijkheden zijn opgelost, moet u uw project bouwen. Eventuele fouten helpen u bij de volgende stappen.

Hint

  • Verwijder alle bin - en obj-mappen uit alle projecten voordat u projecten opent en bouwt in Visual Studio, met name wanneer u .NET-versies wijzigt.
  • Verwijder het gegenereerde bestand Resource.designer.cs uit het Android-project.

De volgende tabel biedt richtlijnen voor het oplossen van veelvoorkomende build- of runtimeproblemen.

Probleem Hint
Xamarin.* naamruimte bestaat niet. Werk de namespace bij naar het .NET MAUI-equivalent. Voor meer informatie, zie Namespace-wijzigingen.
API bestaat niet. Werk de API-gebruik bij naar het .NET MAUI-equivalent. Voor meer informatie, zie API changes.
De app wil niet worden ingezet. Zorg ervoor dat het vereiste platformproject is ingesteld om te implementeren in Visual Studio's Configuration Manager.
App start niet op. Update elke platformproject-entrypuntklasse en het app-entrypunt. Voor meer informatie, zie Bootstrap je gemigreerde app.
CollectionView scrollt niet. Controleer de containerindeling en de gemeten grootte van het CollectionView. Standaard neemt de controle zoveel ruimte in als de container toestaat. Een Grid beperkt kinderen tot zijn eigen grootte. Een StackLayout stelt kinderen echter in staat om ruimte in te nemen buiten zijn grenzen.
De pop-up wordt onderaan de pagina weergegeven op iOS. In Xamarin.Forms zijn alle pop-ups op iOS UIWindow-instanties, maar in .NET MAUI worden pop-ups weergegeven door de huidige presenterende ViewController te lokaliseren en de pop-up weer te geven met PresentViewControllerAsync. In invoegtoepassingen zoals Mopups, om ervoor te zorgen dat uw pop-ups correct worden weergegeven, moet u DisplayAlert aanroepen (of DisplayAlertAsync in .NET 10+), DisplayActionSheet (of DisplayActionSheetAsync in .NET 10+), of DisplayPromptAsync vanuit de ContentPage die wordt gebruikt binnen de Mopup pop-up.
BoxView wordt niet weergegeven. De standaardgrootte van een BoxView in Xamarin.Forms is 40x40. De standaardgrootte van een BoxView in .NET MAUI is 0x0. Stel WidthRequest en HeightRequest in op 40.
De opmaak mist opvulling, marge of ruimte. Voeg standaardwaarden toe aan uw project op basis van de .NET MAUI stijlhulpbron. Voor meer informatie, zie Standaardwaarde veranderingen van Xamarin.Forms.
Aangepaste layout werkt niet. Aangepaste lay-outcode moet worden bijgewerkt om te werken in .NET MAUI. Voor meer informatie, zie Aangepaste lay-outwijzigingen.
Aangepaste renderer werkt niet. Renderer-code moet bijgewerkt worden om te werken in .NET MAUI. Voor meer informatie, zie Use custom renderers in .NET MAUI.
Effect werkt niet. De effectcode moet worden bijgewerkt om te werken in .NET MAUI. Zie Use effects in .NET MAUI voor meer informatie.
SkiaSharp code werkt niet. SkiaSharp code heeft kleine updates nodig om te kunnen werken in .NET MAUI. Voor meer informatie, zie Code opnieuw SkiaSharp gebruiken in .NET MAUI.
Kan geen toegang krijgen tot eerder gemaakte app-eigenschapgegevens. Migreer de gegevens van de app-eigenschappen naar .NET MAUI-voorkeuren. Zie voor meer informatie Gegevens uit de eigenschappenwoordenlijst van de Xamarin.Forms app migreren naar .NET MAUI-voorkeuren.
Kan geen toegang krijgen tot eerder gemaakte beveiligde opslaggegevens. Migreer de gegevens van beveiligde opslag naar .NET MAUI. Zie Migreren van Xamarin.Essentials beveiligde opslag naar .NET MAUI beveiligde opslag voor meer informatie.
Kan geen toegang krijgen tot eerder gemaakte versievolggegevens. Migreer de versietraceringsgegevens naar .NET MAUI. Voor meer informatie, zie Versietraceringsgegevens migreren van een Xamarin.Forms app naar een .NET MAUI-app.