Compartir a través de

Actualización manual de una Xamarin.Forms aplicación a una aplicación de .NET MAUI de varios proyectos

La actualización de una aplicación de varios proyectos Xamarin.Forms a una aplicación de aplicaciones multiplataforma de .NET multiproyecto (.NET MAUI) sigue los mismos pasos que un proyecto de Xamarin.Android y Xamarin.iOS, con pasos adicionales para aprovechar los cambios en .NET MAUI.

En este artículo se describe cómo migrar manualmente un Xamarin.Forms proyecto de biblioteca a un proyecto de biblioteca MAUI de .NET. Antes de hacerlo, debe actualizar los Xamarin.Forms proyectos de plataforma para que sean proyectos de estilo SDK. Los proyectos de estilo SDK utilizan el mismo formato de proyecto que todas las cargas de trabajo de .NET y, en comparación con muchos proyectos de Xamarin, son mucho menos verbosos. Para obtener información sobre cómo actualizar los proyectos de la aplicación, consulte Actualización de proyectos de Xamarin.Android, Xamarin.iOS y Xamarin.Mac a .NET, Xamarin.Android, Migración de proyectos de Xamarin Apple y Xamarin.Forms Migración de proyectos de UWP.

Para migrar un Xamarin.Forms proyecto de biblioteca a un proyecto de biblioteca MAUI de .NET, debe:

  • Actualiza tu aplicación Xamarin.Forms para usar Xamarin.Forms 5.
  • Actualiza las dependencias de la aplicación a las versiones más recientes.
  • Asegúrese de que la aplicación siga funcionando.
  • Actualice el archivo del proyecto para que sea de estilo SDK.
  • Actualizar espacios de nombres.
  • Aborda cualquier cambio en la API.
  • Configurar .NET MAUI.
  • Actualiza o reemplaza las dependencias incompatibles con las versiones de .NET 8.
  • Compila y prueba tu aplicación.

Para simplificar el proceso de actualización, debe crear un nuevo proyecto de biblioteca .NET MAUI con el mismo nombre que el proyecto de biblioteca Xamarin.Forms, y luego copiar el código, la configuración y los recursos. Esta es la estrategia delineada a continuación.

Actualiza tu Xamarin.Forms aplicación

Antes de actualizar tu aplicación Xamarin.Forms a .NET MAUI, primero deberías actualizar tu aplicación Xamarin.Forms para usar Xamarin.Forms 5 y asegurarte de que siga funcionando correctamente. Además, debes actualizar las dependencias que utiliza tu aplicación a las versiones más recientes.

Esto ayudará a simplificar el resto del proceso de migración, ya que minimizará las diferencias de API entre Xamarin.Forms y .NET MAUI, y garantizará que estés utilizando versiones compatibles con .NET de tus dependencias, si existen.

Creación de un nuevo proyecto

En Visual Studio, cree un nuevo proyecto de biblioteca de clases MAUI de .NET con el mismo nombre que el Xamarin.Forms proyecto de biblioteca. Este proyecto hospedará el código del proyecto de biblioteca Xamarin.Forms. Al abrir el archivo del proyecto, se confirmará que tiene un proyecto de estilo SDK de .NET:

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFrameworks>net8.0;net8.0-android;net8.0-ios;net8.0-maccatalyst</TargetFrameworks>
        <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net8.0-windows10.0.19041.0</TargetFrameworks>
        <!-- Uncomment to also build the tizen app. You will need to install tizen by following this: https://github.com/Samsung/Tizen.NET -->
        <!-- <TargetFrameworks>$(TargetFrameworks);net8.0-tizen</TargetFrameworks> -->
        <UseMaui>true</UseMaui>
        <SingleProject>true</SingleProject>
        <ImplicitUsings>enable</ImplicitUsings>

        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">11.0</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">13.1</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">21.0</SupportedOSPlatformVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.17763.0</SupportedOSPlatformVersion>
        <TargetPlatformMinVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.17763.0</TargetPlatformMinVersion>
        <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'tizen'">6.5</SupportedOSPlatformVersion>
    </PropertyGroup>

</Project>

En los proyectos de la plataforma, agregue una referencia a este nuevo proyecto de biblioteca. A continuación, copie los Xamarin.Forms archivos de librería en el proyecto de librería MAUI de .NET.

Cambios de espacio de nombres

Los espacios de nombres han cambiado en la transición de Xamarin.Forms a .NET MAUI, y las características de Xamarin.Essentials ahora forman parte de .NET MAUI. Para realizar actualizaciones de espacios de nombres, lleva a cabo una búsqueda y reemplazo para los siguientes espacios de nombres:

Xamarin.Forms Namespace Espacios de nombres .NET MAUI
Xamarin.Forms Microsoft.Maui y Microsoft.Maui.Controls
Xamarin.Forms.DualScreen Microsoft.Maui.Controls.Foldable
Xamarin.Forms.Maps Microsoft.Maui.Controls.Maps y 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

Los proyectos de .NET MAUI hacen uso de directivas implícitas. Esta función te permite eliminar las using directivas para el espacio de nombres Xamarin.Essentials, sin tener que reemplazarlas por los espacios de nombres equivalentes de .NET MAUI.

Además, el espacio de nombres XAML predeterminado ha cambiado de http://xamarin.com/schemas/2014/forms en Xamarin.Forms a http://schemas.microsoft.com/dotnet/2021/maui en .NET MAUI. Por lo tanto, debe reemplazar todas las apariciones de xmlns="http://xamarin.com/schemas/2014/forms" por xmlns="http://schemas.microsoft.com/dotnet/2021/maui".

Nota:

Puedes actualizar rápidamente tus Xamarin.Forms espacios de nombres a Microsoft.Maui utilizando Acciones rápidas en Visual Studio, siempre que tengas instalado Upgrade Assistant.

Cambios de API

Algunas API han cambiado en la transición de Xamarin.Forms a .NET MAUI. Esta es una serie de razones, incluyendo la eliminación de funcionalidades duplicadas causadas por el hecho de que Xamarin.Essentials se convierte en parte de .NET MAUI, y asegurar que las API sigan las directrices de nombres de .NET. Las siguientes secciones analizan estos cambios.

Cambios de color

En Xamarin.Forms, la estructura Xamarin.Forms.Color te permite construir objetos Color utilizando valores double, y proporciona colores nombrados, como Xamarin.Forms.Color.AliceBlue. En .NET MAUI, esta funcionalidad se ha separado en la clase Microsoft.Maui.Graphics.Color y la clase Microsoft.Maui.Graphics.Colors.

La clase Microsoft.Maui.Graphics.Color, en el espacio de nombres Microsoft.Maui.Graphics, te permite construir objetos Color usando valores float, valores byte y valores int. La clase Microsoft.Maui.Graphics.Colors, que también se encuentra en el espacio de nombres Microsoft.Maui.Graphics, proporciona en gran parte los mismos colores nombrados. Por ejemplo, use Colors.AliceBlue para especificar el color AliceBlue.

La siguiente tabla muestra los cambios de la API entre la estructura Xamarin.Forms.Color y la clase Microsoft.Maui.Graphics.Color.

Xamarin.Forms Interfaz de Programación de Aplicaciones (API) API de MAUI de .NET Comentario
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 propiedad reemplazada por un método en .NET MAUI.
Xamarin.Forms.Color.Saturation Microsoft.Maui.Graphics.Color.GetSaturation Xamarin.Forms propiedad reemplazada por un método en .NET MAUI.
Xamarin.Forms.Color.Luminosity Microsoft.Maui.Graphics.Color.GetLuminosity Xamarin.Forms propiedad reemplazada por un método en .NET MAUI.
Xamarin.Forms.Color.Default "No hay equivalente de .NET MAUI." En su lugar, los objetos Microsoft.Maui.Graphics.Color se establecen por defecto en null.
Xamarin.Forms.Color.Accent "No hay equivalente de .NET MAUI."
Xamarin.Forms.Color.FromHex Microsoft.Maui.Graphics.Color.FromArgb Microsoft.Maui.Graphics.Color.FromHex está obsoleto y se eliminará en una futura versión.

Además, todos los valores numéricos en un Microsoft.Maui.Graphics.Color son float, en lugar de double como se usa en Xamarin.Forms.Color.

Nota:

A diferencia de Xamarin.Forms, un Microsoft.Maui.Graphics.Color no tiene una conversión implícita a System.Drawing.Color.

Cambios de diseño

La siguiente tabla enumera las API de diseño que se han eliminado en la transición de Xamarin.Forms a .NET MAUI.

Xamarin.Forms Interfaz de Programación de Aplicaciones (API) API de MAUI de .NET Comentarios
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add La Add sobrecarga que acepta tres argumentos no está presente en .NET MAUI.
Xamarin.Forms.Grid.IGridList<T>.AddHorizontal "No hay equivalente de .NET MAUI."
Xamarin.Forms.Grid.IGridList<T>.AddVertical "No hay equivalente de .NET MAUI."
Xamarin.Forms.RelativeLayout Microsoft.Maui.Controls.Compatibility.RelativeLayout En .NET MAUI, RelativeLayout solo existe como un control de compatibilidad para los usuarios que migran desde Xamarin.Forms. Utiliza Grid en su lugar, o añade el xmlns para el espacio de nombres de compatibilidad.

Además, agregar elementos secundarios a un diseño en el código en Xamarin.Forms se realiza añadiendo los elementos secundarios a la colección Children del diseño.

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

En .NET MAUI, la colección Children es de uso interno de .NET MAUI y no debe ser manipulada directamente. Por lo tanto, en el código, los hijos deben añadirse directamente al diseño.

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

Importante

Cualquier método de extensión de Add layout, como GridExtensions.Add, se invoca en el layout en lugar de en la colección de Children layouts.

Puede notar que al ejecutar su aplicación .NET MAUI actualizada, el comportamiento del diseño es diferente. Para más información, consulte Cambios en el comportamiento del diseño desde Xamarin.Forms.

Cambios en el diseño personalizado

El proceso para crear un diseño personalizado en Xamarin.Forms implica crear una clase que derive de Layout<View> y sobrescribir los métodos VisualElement.OnMeasure y Layout.LayoutChildren. Para más información, consulta Crea un diseño personalizado en Xamarin.Forms.

En .NET MAUI, las clases de diseño derivan de la clase abstracta Layout. Esta clase delega el diseño y la medición multiplataforma a una clase gestora de diseño. Cada clase de gestor de diseño implementa la interfaz ILayoutManager, que especifica que deben proporcionarse las implementaciones de Measure y ArrangeChildren.

  • La implementación Measure llama a IView.Measure en cada vista del diseño y devuelve el tamaño total del diseño dadas las restricciones.
  • La implementación de ArrangeChildren determina dónde debe colocarse cada vista dentro de los límites del diseño y llama a Arrange en cada vista con sus límites apropiados. El valor de retorno es el tamaño real del diseño.

Para obtener más información, consulte Diseños personalizados.

Cambios de dispositivo

Xamarin.Forms tiene una Xamarin.Forms.Device clase que le ayuda a interactuar con el dispositivo y la plataforma en la que se ejecuta la aplicación. La clase equivalente en .NET MAUI, Microsoft.Maui.Controls.Device, está obsoleta y su funcionalidad se ha sustituido por varios tipos.

La siguiente tabla muestra los reemplazos de .NET MAUI para la funcionalidad en la clase Xamarin.Forms.Device.

Xamarin.Forms Interfaz de Programación de Aplicaciones (API) API de .NET MAUI Comentarios
Xamarin.Forms.Device.Android Microsoft.Maui.Devices.DevicePlatform.Android
Xamarin.Forms.Device.iOS Microsoft.Maui.Devices.DevicePlatform.iOS
Xamarin.Forms.Device.GTK "No hay equivalente de .NET MAUI."
Xamarin.Forms.Device.macOS "No hay equivalente de .NET MAUI." En su lugar, utilice 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 "No hay equivalente de .NET MAUI."
Xamarin.Forms.Device.Flags "No hay equivalente de .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 "No hay equivalente de .NET MAUI."
Xamarin.Forms.Device.GetNamedSize "No hay equivalente de .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 "No hay equivalente de .NET MAUI."
Xamarin.Forms.Device.SetFlowDirection Microsoft.Maui.Controls.Window.FlowDirection
Xamarin.Forms.Device.StartTimer Microsoft.Maui.Dispatching.DispatcherExtensions.StartTimer o Microsoft.Maui.Dispatching.Dispatcher.DispatchDelayed

Cambios en el mapa

En Xamarin.Forms, el control Map y los tipos asociados están en el espacio de nombres Xamarin.Forms.Maps. En .NET MAUI, esta funcionalidad se ha movido a los Microsoft.Maui.Controls.Maps y Microsoft.Maui.Maps namespaces. Algunas propiedades han sido renombradas y algunos tipos han sido reemplazados por tipos equivalentes de Xamarin.Essentials.

La siguiente tabla muestra los reemplazos de .NET MAUI para la funcionalidad en el espacio de nombres Xamarin.Forms.Maps.

Xamarin.Forms Interfaz de Programación de Aplicaciones (API) .NET MAUI API Comentario
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 "No hay equivalente de .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 Los miembros del tipo Xamarin.Forms.Maps.Position se han cambiado al tipo Microsoft.Maui.Devices.Sensors.Location.
Xamarin.Forms.Maps.Geocoder Microsoft.Maui.Devices.Sensors.Geocoding Los miembros del tipo Xamarin.Forms.Maps.Geocoder se han cambiado al tipo Microsoft.Maui.Devices.Sensors.Geocoding.

.NET MAUI tiene dos tipos de Map - Microsoft.Maui.Controls.Maps.Map y Microsoft.Maui.ApplicationModel.Map. Debido a que el espacio de nombres Microsoft.Maui.ApplicationModel es una de las directivas de .NET MAUI, al usar el control global using desde el código, deberá calificar completamente su uso Microsoft.Maui.Controls.Maps.Map o usar un Map.

En XAML, se debe agregar un espacio de nombres xmlns para la definición de control Map. Aunque esto no es necesario, evita una colisión entre los tipos Polygon y Polyline, que existen en los espacios de nombres Microsoft.Maui.Controls.Maps y Microsoft.Maui.Controls.Shapes. Para más información, consulte Mostrar un mapa.

Otros cambios

Se ha consolidado un pequeño número de otras API durante el traslado de Xamarin.Forms a .NET MAUI. La siguiente tabla muestra estos cambios.

Xamarin.Forms Interfaz de Programación de Aplicaciones (API) API de .NET MAUI Comentarios
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 En Xamarin.Forms, el método ApplyQueryAttributes acepta un argumento IDictionary<string, string>. En .NET MAUI, el ApplyQueryAttributes método acepta un IDictionary<string, object> argumento.
Xamarin.Forms.MenuItem.Icon Microsoft.Maui.Controls.MenuItem.IconImageSource Xamarin.Forms.MenuItem.Icon es la clase base para Xamarin.Forms.ToolbarItemy, por tanto ToolbarItem.Icon , se convierte en ToolbarItem.IconImageSource.
Xamarin.Forms.OrientationStateTrigger.Orientation Microsoft.Maui.Controls.OrientationStateTrigger.Orientation En Xamarin.Forms, la OrientationStateTrigger.Orientation propiedad es de tipo Xamarin.Forms.Internals.DeviceOrientation. En .NET MAUI, la propiedad OrientationStateTrigger.Orientation es de tipo 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 es la clase base para Microsoft.Maui.Controls.ToolbarItemy, por tanto ToolbarItem.Name , se convierte en ToolbarItem.Text.

Además, en Xamarin.Forms, la Page.OnAppearing sobrecarga se llama en Android cuando una aplicación se pone en segundo plano y luego se devuelve al primer plano. Sin embargo, esta sobrescritura no se llama en iOS y Windows en el mismo escenario. En .NET MAUI, el reemplazo OnAppearing() no se llama en ninguna plataforma cuando una aplicación está en segundo plano y luego se lleva al primer plano. En su lugar, debería escuchar los eventos del ciclo de vida en Window para ser notificado cuando una aplicación vuelva al primer plano. Para obtener más información, vea .NET MAUI windows.

Cambios en los formularios nativos

Native forms en Xamarin.Forms se ha convertido en incrustación nativa en .NET MAUI, y usa un enfoque de inicialización diferente y diferentes métodos de extensión para convertir los controles multiplataforma a sus tipos nativos. Para más información, consulte Native embedding.

Pon en marcha tu aplicación migrada

Al actualizar manualmente una Xamarin.Forms aplicación a .NET MAUI, deberá habilitar la compatibilidad con .NET MAUI en cada proyecto de plataforma, actualizar la clase de punto de entrada de cada proyecto de plataforma y, a continuación, configurar el arranque de la aplicación .NET MAUI.

Habilitación de .NET MAUI en proyectos de plataforma

Antes de actualizar la clase de punto de entrada de cada proyecto de plataforma, primero debe habilitar la compatibilidad con .NET MAUI. Esto se puede lograr estableciendo la propiedad $(UseMaui)true de compilación en cada proyecto de plataforma.

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

Importante

Debe agregar <UseMaui>true</UseMaui> al archivo de proyecto para habilitar la compatibilidad con .NET MAUI. Además, asegúrese de que ha agregado <EnableDefaultMauiItems>false</EnableDefaultMauiItems> al archivo de proyecto de WinUI. Esto evitará que recibas errores de compilación sobre el método InitializeComponent ya está definido.

Agregar referencias de paquete

En .NET 8, .NET MAUI se distribuye como un elemento de trabajo (workload) de .NET, así como varios paquetes NuGet. La ventaja de este enfoque es que permite anclar fácilmente los proyectos a versiones específicas, a la vez que le permite obtener una vista previa sencilla de compilaciones no publicadas o experimentales.

Debe agregar las siguientes referencias de paquete explícitas en el <ItemGroup> de cada archivo de proyecto.

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

La variable $(MauiVersion) se refiere a la versión de .NET MAUI que ha instalado. Para invalidar esto, agregue la $(MauiVersion) propiedad build a cada archivo de proyecto:

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

Configuración del proyecto de Android

En el proyecto de .NET MAUI Android, actualice la MainApplication clase para que coincida con el código siguiente:

using System;
using Android.App;
using Android.Runtime;
using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.Droid
{
    [Application]
    public class MainApplication : MauiApplication
    {
        public MainApplication(IntPtr handle, JniHandleOwnership ownership) : base(handle, ownership)
        {
        }

        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
    }
}

Actualice también la MainActivity clase para heredar de MauiAppCompatActivity:

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

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

A continuación, actualice el archivo de manifiesto para especificar que es minSdKVersion 21, que es la versión mínima de Android SDK requerida por .NET MAUI. Esto se puede lograr modificando el <uses-sdk /> nodo, que es un elemento secundario del <manifest> nodo:

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

Configuración del proyecto de iOS

En el proyecto de .NET MAUI iOS, actualice la AppDelegate clase para heredar de MauiUIApplicationDelegate:

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

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

A continuación, actualice Info.plist para que MinimumOSVersion sea 11.0, que es la versión mínima de iOS requerida por .NET MAUI.

Configuración del proyecto para UWP

En el proyecto .NET MAUI WinUI 3, actualice App.xaml para que coincida con el código siguiente:

<?xml version="1.0" encoding="utf-8"?>
<maui:MauiWinUIApplication
    x:Class="YOUR_NAMESPACE_HERE.WinUI.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:maui="using:Microsoft.Maui"
    xmlns:local="using:YOUR_NAMESPACE_HERE.WinUI">
    <maui:MauiWinUIApplication.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
                <!-- Other merged dictionaries here -->
            </ResourceDictionary.MergedDictionaries>
            <!-- Other app resources here -->
        </ResourceDictionary>
    </maui:MauiWinUIApplication.Resources>
</maui:MauiWinUIApplication>

Nota:

Si el proyecto incluía recursos en app.xaml existente, debe migrarlos a la nueva versión del archivo.

Además, actualice App.xaml.cs para que coincida con el código siguiente:

using Microsoft.Maui;
using Microsoft.Maui.Hosting;
using YOUR_MAUI_CLASS_LIB_HERE;

namespace YOUR_NAMESPACE_HERE.WinUI;

public partial class App : MauiWinUIApplication
{
    public App()
    {
        InitializeComponent();
    }

    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}

Nota:

Si el proyecto incluía lógica de negocios en App.xaml.cs debe migrar esa lógica a la nueva versión del archivo.

A continuación, agregue un archivo launchSettings.json a la carpeta Properties del proyecto y agregue el siguiente JSON al archivo:

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

Punto de entrada de la aplicación

Las aplicaciones MAUI de .NET tienen un único punto de entrada de aplicación multiplataforma. Cada punto de entrada de plataforma llama a un CreateMauiApp método en la clase estática MauiProgram y devuelve un MauiApp.

Por lo tanto, agregue una nueva clase denominada MauiProgram que contenga el código siguiente:

namespace YOUR_NAMESPACE_HERE;

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

        return builder.Build();
    }
}

Nota:

Para los proyectos de Xamarin.Forms UWP, la referencia App en builder.UseMauiApp<App>() se encuentra en el archivo MainPage.xaml.cs.

Si hay servicios específicos de la plataforma que deben migrarse a .NET MAUI, use el AddTransient(IServiceCollection, Type) método para agregar un servicio transitorio del tipo especificado al especificado IServiceCollection.

Nota:

Puedes actualizar rápidamente tus Xamarin.Forms espacios de nombres a Microsoft.Maui utilizando Acciones rápidas en Visual Studio, siempre que tengas instalado Upgrade Assistant.

Cambios de AssemblyInfo

Las propiedades que generalmente se establecen en un archivo AssemblyInfo.cs ahora están disponibles en su proyecto de estilo SDK. Recomendamos migrarlos de AssemblyInfo.cs al archivo de proyecto en cada proyecto y eliminar el archivo AssemblyInfo.cs.

Opcionalmente, puedes mantener el archivo AssemblyInfo.cs y establecer la propiedad GenerateAssemblyInfo en tu archivo de proyecto a false.

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

Para obtener más información sobre la propiedad GenerateAssemblyInfo, consulte GenerateAssemblyInfo.

Actualizar las dependencias de la aplicación

Generalmente, Xamarin.Forms los paquetes NuGet no son compatibles con .NET 8 a menos que hayan sido recompilados utilizando los monikers del marco de trabajo objetivo de .NET (TFMs). Sin embargo, las aplicaciones de Android pueden usar paquetes NuGet dirigidos a los marcos monoandroid y monoandroidXX.X.

Puede confirmar que un paquete es compatible con .NET 8 mirando la pestaña de Frameworks en NuGet para el paquete que está utilizando, y comprobando que enumera uno de los frameworks compatibles que se muestran en la tabla a continuación:

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

Nota:

Las bibliotecas de .NET Standard que no tienen dependencias de los marcos incompatibles listados anteriormente siguen siendo compatibles con .NET 8.

Si un paquete en NuGet indica compatibilidad con cualquiera de los marcos compatibles mencionados anteriormente, independientemente de incluir también marcos incompatibles, entonces el paquete es compatible. Los paquetes NuGet compatibles se pueden agregar a su proyecto de biblioteca .NET MAUI utilizando el administrador de paquetes NuGet en Visual Studio.

Si no puedes encontrar una versión compatible con .NET 8 de un paquete de NuGet, deberías:

  • Vuelva a compilar el paquete con los TFMs de .NET, si posee el código.
  • Busca una versión preliminar del paquete de .NET 8.
  • Reemplaza la dependencia con una alternativa compatible con .NET 8.

Compilar y solucionar problemas

Una vez resueltas las dependencias, debe compilar su proyecto. Los errores le guiarán hacia los pasos siguientes.

Sugerencia

  • Elimine todas las carpetas bin y obj de todos los proyectos antes de abrir y compilar proyectos en Visual Studio, especialmente al cambiar las versiones de .NET.
  • Elimina el archivo generado Resource.designer.cs del proyecto de Android.

La siguiente tabla proporciona orientación para superar problemas comunes de compilación o de tiempo de ejecución.

Cuestión Sugerencia
Xamarin.* espacio de nombres no existe. Actualiza el espacio de nombres a su equivalente en .NET MAUI. Para más información, consulte Cambios en el espacio de nombres.
La API no existe. Actualiza el uso de la API a su equivalente en .NET MAUI. Para más información, consulte Cambios de API.
La aplicación no se desplegará. Asegúrese de que el proyecto de plataforma necesario esté establecido para implementarlo en Configuration Manager de Visual Studio.
La aplicación no se iniciará. Actualiza la clase de punto de entrada de cada proyecto de plataforma y el punto de entrada de la aplicación. Para más información, consulte Arranque su aplicación migrada.
CollectionView no se desplaza. Comprueba el diseño del contenedor y el tamaño medido del CollectionView. De forma predeterminada, el control ocupará tanto espacio como permita el contenedor. Restringe a Grid los elementos secundarios a su tamaño propio. Sin embargo, un StackLayout permite que los niños ocupen espacio más allá de sus límites.
El elemento emergente se muestra debajo de la página en iOS. En Xamarin.Forms, todas las ventanas emergentes en iOS son instancias de UIWindow, pero en .NET MAUI las ventanas emergentes se muestran ubicando el ViewController actual que presenta y mostrando la ventana emergente con PresentViewControllerAsync. En plugins como Mopups, para asegurarte de que tus ventanas emergentes se muestren correctamente, debes llamar a DisplayAlert (o DisplayAlertAsync en .NET 10+), DisplayActionSheet (o DisplayActionSheetAsync en .NET 10+), o DisplayPromptAsync desde el ContentPage que se usa dentro del Mopup de la ventana emergente.
BoxView no aparece. El tamaño predeterminado de un BoxView en Xamarin.Forms es 40x40. El tamaño predeterminado de un BoxView en .NET MAUI es 0x0. Establezca WidthRequest y HeightRequest en 40.
Faltan relleno, margen o espacio en el diseño. Agrega valores predeterminados a tu proyecto según el recurso de estilo .NET MAUI. Para obtener más información, consulte cambios del valor predeterminado desde Xamarin.Forms.
La disposición personalizada no funciona. El código de diseño personalizado necesita actualizarse para funcionar en .NET MAUI. Para más información, consulte Custom layout changes.
El procesador personalizado no funciona. El código del renderizador necesita actualizarse para funcionar en .NET MAUI. Para más información, consulte Use custom renderers in .NET MAUI.
El efecto no funciona. El código de efecto necesita actualizar para que funcione en .NET MAUI. Para más información, consulte Use effects in .NET MAUI.
SkiaSharp el código no funciona. SkiaSharp el código necesita actualizaciones secundarias para que funcionen en .NET MAUI. Para más información, consulte Reuse SkiaSharp code in .NET MAUI.
No se puede acceder a los datos de las propiedades de la aplicación creadas anteriormente. Migra los datos de propiedades de la aplicación a las preferencias de .NET MAUI. Para obtener más información, consulte Migrar datos del diccionario de propiedades de la aplicación Xamarin.Forms a las preferencias de .NET MAUI.
No se puede acceder a los datos de almacenamiento seguro creados anteriormente. Migre los datos de almacenamiento seguro a .NET MAUI. Para más información, consulte Migración del Xamarin.Essentials almacenamiento seguro a almacenamiento seguro de .NET MAUI.
No se puede acceder a los datos de seguimiento de versiones creados anteriormente. Migra los datos de seguimiento de versiones a .NET MAUI. Para más información, consulte Migrar datos de seguimiento de versiones de una Xamarin.Forms aplicación a una aplicación .NET MAUI.

Consulte también