Aggiornare manualmente un'app Xamarin.Forms a un singolo progetto app MAUI .NET

Per eseguire la migrazione di un'app Xamarin.Forms a un'app .NET multipiattaforma (.NET MAUI) a un singolo progetto, è necessario:

Per semplificare il processo di aggiornamento, è necessario creare una nuova app MAUI .NET con lo stesso nome Xamarin.Forms dell'app e quindi copiare il codice, la configurazione e le risorse. Questo è l'approccio descritto di seguito.

Aggiornare l'app Xamarin.Forms

Prima di aggiornare l'app Xamarin.Forms a .NET MAUI, è necessario aggiornare Xamarin.Forms l'app per usare Xamarin.Forms 5 e assicurarsi che funzioni ancora correttamente. È anche necessario aggiornare le dipendenze usate dall'app alle versioni più recenti.

Ciò consentirà di semplificare il resto del processo di migrazione, in quanto ridurrà al minimo le differenze api tra Xamarin.Forms e .NET MAUI e garantirà l'uso di versioni compatibili con .NET delle dipendenze, se presenti.

Creare un'app .NET MAUI

In Visual Studio creare una nuova app MAUI .NET usando lo stesso nome dell'app Xamarin.Forms :

L'apertura del file di progetto consentirà di verificare di avere un progetto di tipo .NET SDK.

Copiare il codice nell'app MAUI .NET

Tutto il codice multipiattaforma del Xamarin.Forms progetto di libreria deve essere copiato nel progetto di app MAUI .NET in cartelle e file denominati in modo identico.

I renderer personalizzati possono essere riutilizzati in un'app MAUI .NET o migrati a un gestore MAUI .NET. Per altre informazioni, vedere Riutilizzare i renderer personalizzati in .NET MAUI ed eseguire la migrazione di un Xamarin.Forms renderer personalizzato a un gestore MAUI .NET.

Gli effetti possono essere riutilizzati in un'app MAUI .NET. Per altre informazioni, vedere Riutilizzare gli effetti.

Codice specifico della piattaforma

Un progetto di app .NET MAUI contiene una cartella Platforms , con ogni cartella figlio che rappresenta una piattaforma di destinazione di .NET MAUI:

Le cartelle per ogni piattaforma contengono risorse specifiche della piattaforma e codice che avvia l'app in ogni piattaforma:

Il codice e le relative cartelle contenenti, dai Xamarin.Forms progetti head devono essere copiati in queste cartelle:

• Il codice del Xamarin.Forms progetto head Android deve essere copiato nella cartella Platform\Android del progetto di app .NET MAUI. Inoltre, copiare qualsiasi codice personalizzato dalle Xamarin.FormsMainActivity classi e MainApplication nelle stesse classi nel progetto dell'app MAUI .NET.

• Il codice del Xamarin.Forms progetto head iOS deve essere copiato nella cartella Platforms\iOS del progetto di app MAUI .NET. Copiare anche qualsiasi codice personalizzato dalla Xamarin.FormsAppDelegate classe alla stessa classe nel progetto di app MAUI .NET.

  Nota

  Per un elenco delle modifiche di rilievo in .NET per iOS, vedere Modifiche di rilievo in .NET per iOS.

• Il codice del Xamarin.Forms progetto head UWP deve essere copiato nella cartella Platforms\Windows del progetto di app MAUI .NET. Copiare anche qualsiasi codice personalizzato dalla Xamarin.FormsApp classe alla stessa classe nel progetto di app MAUI .NET.

In fase di compilazione, il sistema di compilazione include solo il codice di ogni cartella necessario per la compilazione per la piattaforma specifica. Ad esempio, quando si compila per Android i file nella cartella Platforms\Android verranno incorporati nel pacchetto dell'app, ma i file nelle altre cartelle Piattaforme non saranno. Questo approccio usa multitargeting per definire come destinazione più piattaforme da un singolo progetto. Le app MAUI .NET possono anche essere multi-destinazione in base ai propri criteri di nome file e cartelle. In questo modo è possibile strutturare il progetto di app .NET MAUI in modo che non sia necessario inserire il codice della piattaforma in cartelle figlio della cartella Piattaforme . Per altre informazioni, vedere Configurare multitargeting.

Copiare la configurazione nell'app MAUI .NET

Ogni piattaforma usa il proprio file manifesto dell'app nativa per specificare informazioni quali il titolo dell'app, l'ID, la versione e altro ancora. Il progetto singolo .NET MAUI consente di specificare questi dati comuni dell'app in un'unica posizione nel file di progetto.

Per specificare i dati del manifesto dell'app condivisa per un progetto, aprire il menu di scelta rapida per il progetto in Esplora soluzioni e quindi scegliere Proprietà. Il titolo, l'ID e la versione dell'app possono quindi essere specificati in Generale condiviso > MAUI:

Al momento della compilazione, i dati del manifesto dell'app condivisa vengono uniti ai dati specifici della piattaforma nel file manifesto dell'app nativa per produrre il file manifesto per il pacchetto dell'app. Per altre informazioni, vedere Configurazione del progetto in .NET MAUI - MAUI Shared.

I dati rimanenti dai Xamarin.Forms manifesti dell'app devono essere copiati nel manifesto dell'app MAUI .NET:

• In Android copiare eventuali dati aggiuntivi dal file AndroidManifest.xml nel Xamarin.Forms progetto principale Android nel file Platforms\Android\AndroidManifest.xml nel progetto di app MAUI .NET.
• In iOS copiare eventuali dati aggiuntivi dal file Info.plist nel Xamarin.Forms progetto head iOS nel file Platforms\iOS\Info.plist nel progetto di app MAUI .NET. Copiare anche il file Entitlements.plist nel Xamarin.Forms progetto head iOS nella cartella Platforms\iOS nel progetto di app MAUI .NET.
• In Windows copiare dati aggiuntivi dal file Package.appxmanifest nel Xamarin.Forms progetto head UWP al file Platforms\Windows\Package.appxmanifest nel progetto di app MAUI .NET.

Copiare le risorse nell'app MAUI .NET

Il singolo progetto MAUI .NET consente di archiviare i file di risorse in un'unica posizione durante l'utilizzo in ogni piattaforma. Sono inclusi tipi di carattere, immagini, l'icona dell'app, la schermata iniziale, gli asset non elaborati e i file CSS per applicare stili alle app MAUI .NET.

I file di risorse devono in genere essere inseriti nella cartella Risorse del progetto dell'app MAUI .NET o nelle cartelle figlio della cartella Risorse e devono impostare correttamente l'azione di compilazione. La tabella seguente illustra le azioni di compilazione per ogni tipo di file di risorse:

Lo screenshot seguente mostra una tipica cartella Resources contenente cartelle figlio per ogni tipo di risorsa:

L'azione di compilazione per un file di risorse verrà impostata correttamente, se la risorsa è stata aggiunta alla cartella figlio Risorse corretta.

Icone dell'app

L'icona Xamarin.Forms dell'app deve essere aggiunta al progetto di app MAUI .NET trascinando l'immagine nella cartella Resources\AppIcon del progetto, in cui l'azione di compilazione verrà impostata automaticamente su MauiIcon. In fase di compilazione, l'icona dell'app viene ridimensionata in base alle dimensioni corrette per la piattaforma e il dispositivo di destinazione. Le icone dell'app vengono ridimensionate in più risoluzioni perché hanno più usi, tra cui l'uso per rappresentare l'app nel dispositivo e nell'App Store.

Per altre informazioni, vedere Aggiungere un'icona dell'app a un progetto di app MAUI .NET.

Schermata iniziale

Se l'app Xamarin.Forms ha una schermata iniziale, deve essere aggiunta al progetto di app MAUI .NET trascinando l'immagine nella cartella Resources\Splash del progetto, in cui l'azione di compilazione verrà impostata automaticamente su MauiSplashScreen. In fase di compilazione, l'immagine della schermata iniziale viene ridimensionata in base alle dimensioni corrette per la piattaforma e il dispositivo di destinazione.

Per altre informazioni, vedere Aggiungere una schermata iniziale a un progetto di app MAUI .NET.

Immagini

I dispositivi hanno una gamma di dimensioni e densità dello schermo e ogni piattaforma ha funzionalità per la visualizzazione di immagini dipendenti dalla densità. In Xamarin.Formsle immagini dipendenti dalla densità vengono in genere inserite nei progetti head e adottano una convenzione di denominazione specifica della piattaforma. Per eseguire la migrazione di queste immagini a .NET MAUI è possibile adottare due approcci.

L'approccio consigliato consiste nel copiare la versione con risoluzione più elevata di ogni immagine dalla Xamarin.Forms soluzione al progetto di app MAUI .NET trascinandolo nella cartella Resources\Images del progetto, in cui l'azione di compilazione verrà impostata automaticamente su MauiImage. Sarà anche necessario impostare l'attributo BaseSize di ogni immagine bitmap per assicurarsi che si verifichi il ridimensionamento. Ciò elimina la necessità di avere più versioni di ogni immagine, in ogni piattaforma. In fase di compilazione, tutte le immagini verranno quindi ridimensionate in più immagini dipendenti dalla densità che soddisfano i requisiti della piattaforma. Per altre informazioni, vedere Aggiungere immagini a un progetto di app MAUI .NET.

In alternativa, è possibile copiare immagini dipendenti dalla densità dalla Xamarin.Forms soluzione a cartelle denominate in modo identico nella cartella Platforms\{Platform} del progetto di app MAUI .NET e impostare le azioni di compilazione sulle azioni di compilazione usate nella Xamarin.Forms soluzione. La tabella seguente elenca i percorsi delle immagini di esempio per una Xamarin.Forms soluzione e la posizione equivalente in un progetto di app MAUI .NET:

Purché sia stata adottata la stessa convenzione di denominazione delle immagini usata nella Xamarin.Forms soluzione, l'immagine appropriata verrà scelta in fase di esecuzione in base alle funzionalità del dispositivo. Lo svantaggio di questo approccio è che sono ancora disponibili più versioni di ogni immagine in ogni piattaforma.

Tipi di carattere

I tipi di carattere della Xamarin.Forms soluzione possono essere aggiunti alla soluzione MAUI .NET trascinandoli nella cartella Resources\Fonts del progetto di app MAUI .NET, in cui l'azione di compilazione verrà impostata automaticamente su MauiFont.

Per altre informazioni, vedere Tipi di carattere.

File CSS

Tutti i file CSS della Xamarin.Forms soluzione possono essere aggiunti alla soluzione MAUI .NET trascinandoli in una cartella denominata in modo identico e impostando l'azione di compilazione su MauiCss nella finestra Proprietà .

Per altre informazioni sull'uso di file CSS in un'app MAUI .NET, vedere Style apps using Cascading Style Sheets (App di stile css in un'app MAUI .NET).

Asset non elaborati

Tutti i file di asset non elaborati, ad esempio HTML, JSON e video, devono essere copiati dalla Xamarin.Forms soluzione al progetto di app MAUI .NET trascinandoli nella cartella Resources\Raw del progetto, in cui l'azione di compilazione verrà impostata automaticamente su MauiAsset.

Risorse localizzate

In un'app MAUI .NET le stringhe vengono localizzate usando lo stesso approccio di un'app Xamarin.Forms . Di conseguenza, i file di risorse .NET (con estensione resx) devono essere copiati dalla Xamarin.Forms soluzione in una cartella denominata in modo identico nella soluzione MAUI .NET. È quindi necessario specificare il linguaggio neutro dell'app .NET MAUI. Per altre informazioni, vedere Specificare la lingua neutra dell'app.

In un'app MAUI .NET le immagini vengono localizzate usando lo stesso approccio di un'app Xamarin.Forms . Pertanto, le immagini localizzate e le cartelle in cui risiedono devono essere copiate dalla Xamarin.Forms soluzione al progetto di app MAUI .NET:

• In Android la cartella radice nel progetto di app MAUI .NET per le immagini localizzate è Platforms\Android\Resources.
• In iOS la cartella radice nel progetto di app MAUI .NET per le immagini localizzate è Platforms\iOS\Resources.
• In Windows la cartella radice nel progetto di app MAUI .NET per le immagini localizzate è Platforms\Windows\Assets\Images.

Le immagini localizzate devono avere le azioni di compilazione impostate sulle azioni di compilazione usate nella Xamarin.Forms soluzione. Per altre informazioni, vedere Localizzare le immagini.

In un'app .NET MAUI i nomi delle app vengono localizzati usando lo stesso approccio di un'app Xamarin.Forms :

• In Android il nome dell'app localizzata può essere archiviato usando una convenzione di denominazione basata su cartelle nella cartella Platforms\Android\Resources . Le cartelle e i file di localizzazione dei nomi dell'app devono essere copiati in questa cartella dalla Xamarin.Forms soluzione.
• In iOS il nome dell'app localizzata viene archiviato usando una convenzione di denominazione basata su cartelle nella cartella Platforms\iOS\Resources . Le cartelle e i file di localizzazione dei nomi dell'app devono essere copiati in questa cartella dalla Xamarin.Forms soluzione.
• In Windows il nome dell'app localizzata viene archiviato nel manifesto del pacchetto dell'app.

Per altre informazioni, vedere Localizzare il nome dell'app. Per altre informazioni sulla localizzazione di app MAUI .NET, vedere Localizzazione.

Modifiche dello spazio dei nomi

Gli spazi dei nomi sono stati modificati nel passaggio da Xamarin.Forms a MAUI .NET e Xamarin.Essentials le funzionalità fanno ora parte di .NET MAUI. Per eseguire gli aggiornamenti dello spazio dei nomi, eseguire una ricerca e sostituire per gli spazi dei nomi seguenti:

I progetti MAUI .NET usano direttive implicite global using . Questa funzionalità consente di rimuovere using le direttive per lo Xamarin.Essentials spazio dei nomi, senza doverle sostituire con gli spazi dei nomi MAUI .NET equivalenti.

Inoltre, lo spazio dei nomi XAML predefinito è passato da http://xamarin.com/schemas/2014/forms in Xamarin.Forms a http://schemas.microsoft.com/dotnet/2021/maui in .NET MAUI. Pertanto, è necessario sostituire tutte le occorrenze di xmlns="http://xamarin.com/schemas/2014/forms" con xmlns="http://schemas.microsoft.com/dotnet/2021/maui".

Modifiche API

Alcune API sono state modificate nel passaggio da Xamarin.Forms a MAUI .NET. Si tratta di diversi motivi, tra cui la rimozione di funzionalità duplicate causate dal Xamarin.Essentials fatto che fa parte di .NET MAUI e garantisce che le API seguano le linee guida per la denominazione .NET. Le sezioni seguenti illustrano queste modifiche.

Modifiche al colore

In Xamarin.Formslo Xamarin.Forms.Color struct consente di costruire Color oggetti usando double valori e di specificare colori denominati, ad esempio Xamarin.Forms.Color.AliceBlue. In .NET MAUI questa funzionalità è stata separata nella Microsoft.Maui.Graphics.Color classe e nella Microsoft.Maui.Graphics.Colors classe .

La Microsoft.Maui.Graphics.Color classe, nello spazio dei Microsoft.Maui.Graphics nomi , consente di costruire Color oggetti usando float valori, byte valori e int valori. La Microsoft.Maui.Graphics.Colors classe , che è anche nello spazio dei Microsoft.Maui.Graphics nomi , in gran parte fornisce gli stessi colori denominati. Ad esempio, usare Colors.AliceBlue per specificare il AliceBlue colore.

La tabella seguente illustra le modifiche dell'API tra lo Xamarin.Forms.Color struct e la Microsoft.Maui.Graphics.Color classe :

Inoltre, tutti i valori numerici in un Microsoft.Maui.Graphics.Color sono , anziché double come usato in Xamarin.Forms.Colorfloat.

Modifiche al layout

La tabella seguente elenca le API di layout che sono state rimosse nel passaggio da Xamarin.Forms a .NET MAUI:

Inoltre, l'aggiunta di elementi figlio a un layout nel codice in Xamarin.Forms viene eseguita aggiungendo gli elementi figlio alla raccolta del Children layout:

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

In .NET MAUI la Children raccolta è destinata all'uso interno di .NET MAUI e non deve essere modificata direttamente. Pertanto, negli elementi figlio di codice deve essere aggiunto direttamente al layout:

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

Quando si esegue l'app .NET MAUI aggiornata, è possibile notare che il comportamento del layout è diverso. Per altre informazioni, vedere Modifiche al comportamento del layout da Xamarin.Forms.

Modifiche di layout personalizzate

Il processo di creazione di un layout personalizzato in Xamarin.Forms comporta la creazione di una classe che deriva da Layout<View>e l'override dei VisualElement.OnMeasure metodi e Layout.LayoutChildren . Per altre informazioni, vedere Creare un layout personalizzato in Xamarin.Forms.

In .NET MAUI le classi di layout derivano dalla classe astratta Layout . Questa classe delega il layout e la misurazione multipiattaforma a una classe di gestione layout. Ogni classe di gestione layout implementa l'interfaccia ILayoutManager , che specifica che Measure e ArrangeChildren le implementazioni devono essere fornite:

• L'implementazione Measure chiama IView.Measure in ogni visualizzazione del layout e restituisce le dimensioni totali del layout in base ai vincoli.
• L'implementazione ArrangeChildren determina la posizione di ogni visualizzazione all'interno dei limiti del layout e le chiamate Arrange a ogni visualizzazione con i limiti appropriati. Il valore restituito è la dimensione effettiva del layout.

Per altre informazioni, vedere Layout personalizzati.

Modifiche del dispositivo

Xamarin.Forms ha una Xamarin.Forms.Device classe che consente di interagire con il dispositivo e la piattaforma in cui è in esecuzione l'app. La classe equivalente in .NET MAUI, Microsoft.Maui.Controls.Device, è deprecata e la relativa funzionalità viene sostituita da più tipi.

La tabella seguente illustra le sostituzioni MAUI di .NET per la funzionalità nella Xamarin.Forms.Device classe :

Modifiche mappa

In Xamarin.Formsil controllo e i Map tipi associati si trovano nello spazio dei Xamarin.Forms.Maps nomi . In .NET MAUI questa funzionalità è stata spostata negli Microsoft.Maui.Controls.Maps spazi dei nomi e Microsoft.Maui.Maps . Alcune proprietà sono state rinominate e alcuni tipi sono stati sostituiti con tipi equivalenti da Xamarin.Essentials.

La tabella seguente illustra le sostituzioni MAUI di .NET per la funzionalità nello spazio dei Xamarin.Forms.Maps nomi :

.NET MAUI ha due Map tipi: Microsoft.Maui.Controls.Maps.Map e Microsoft.Maui.ApplicationModel.Map. Poiché lo Microsoft.Maui.ApplicationModel spazio dei nomi è una delle direttive MAUI di global using .NET, quando si usa il Microsoft.Maui.Controls.Maps.Map controllo dal codice è necessario qualificare Map completamente l'utilizzo o usare un alias using.

In XAML è necessario aggiungere una xmlns definizione dello spazio dei nomi per il Map controllo . Anche se non è necessario, impedisce una collisione tra i Polygon tipi e Polyline , che esistono sia negli spazi dei Microsoft.Maui.Controls.Maps Microsoft.Maui.Controls.Shapes nomi che negli spazi dei nomi . Per altre informazioni, vedere Visualizzare una mappa.

Altre modifiche

Un numero ridotto di altre API è stato consolidato nel passaggio da Xamarin.Forms a .NET MAUI. La tabella seguente mostra queste modifiche:

Inoltre, in Xamarin.Forms, l'override Page.OnAppearing viene chiamato in Android quando un'app è in background e quindi viene portata in primo piano. Tuttavia, questa sostituzione non viene chiamata in iOS e Windows nello stesso scenario. In .NET MAUI l'override OnAppearing() non viene chiamato in alcuna piattaforma quando un'app è in background e quindi viene portata in primo piano. È invece necessario restare in ascolto degli eventi del ciclo di vita su cui Window ricevere una notifica quando un'app torna in primo piano. Per altre informazioni, vedere Finestre MAUI .NET.

Modifiche ai moduli nativi

I moduli nativi in Xamarin.Forms sono diventati l'incorporamento nativo in .NET MAUI e usano un approccio di inizializzazione e metodi di estensione diversi per convertire i controlli multipiattaforma nei tipi nativi. Per altre informazioni, vedere Incorporamento nativo.

Modifiche di AssemblyInfo

Le proprietà in genere impostate in un file AssemblyInfo.cs sono ora disponibili nel progetto in stile SDK. È consigliabile eseguirne la migrazione da AssemblyInfo.cs al file di progetto in ogni progetto e rimuovere il file AssemblyInfo.cs .

Facoltativamente, è possibile mantenere il file AssemblyInfo.cs e impostare la GenerateAssemblyInfo proprietà nel file di progetto su false:

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

Per altre informazioni sulla GenerateAssemblyInfo proprietà, vedere GenerateAssemblyInfo.

Aggiornare le dipendenze delle app

In genere, Xamarin.Forms i pacchetti NuGet non sono compatibili con .NET 8 a meno che non siano stati ricompilati usando moniker del framework di destinazione .NET (TFMS). Tuttavia, le app Android possono usare pacchetti NuGet destinati ai monoandroid framework e monoandroidXX.X .

È possibile verificare che un pacchetto sia compatibile con .NET 8 esaminando la scheda Framework in NuGet per il pacchetto in uso e verificando che elenca uno dei framework compatibili illustrati nella tabella seguente:

Se un pacchetto in NuGet indica la compatibilità con uno dei framework compatibili precedenti, indipendentemente dall'inclusione anche di framework incompatibili, il pacchetto è compatibile. I pacchetti NuGet compatibili possono essere aggiunti al progetto di libreria MAUI .NET usando gestione pacchetti NuGet in Visual Studio.

Se non è possibile trovare una versione compatibile con .NET 8 di un pacchetto NuGet, è necessario:

• Ricompilare il pacchetto con i TFM .NET, se si è proprietari del codice.
• Cercare una versione di anteprima di una versione .NET 8 del pacchetto.
• Sostituire la dipendenza con un'alternativa compatibile con .NET 8.

Compilare e risolvere i problemi

Dopo aver risolto le dipendenze, è necessario compilare il progetto. Eventuali errori ti guideranno verso i passaggi successivi.

La tabella seguente fornisce indicazioni per il superamento dei problemi comuni di compilazione o runtime: