Comparteix a través de

Actualización manual de una aplicación Xamarin.Forms a una aplicación .NET MAUI de proyecto único

  • Article

Para migrar una aplicación Xamarin.Forms a una aplicación de .NET Multi-platform App UI (.NET MAUI) de proyecto único, debes hacer lo siguiente:

  • Actualiza la aplicación Xamarin.Forms para usar Xamarin.Forms 5.
  • Actualiza todas las dependencias de la aplicación a las versiones más recientes.
  • Asegúrate de que la aplicación sigue funcionando.
  • Cree una aplicación .NET MAUI.
  • Copia el código y la configuración de la aplicación Xamarin.Forms en la aplicación .NET MAUI.
  • Copia los recursos de la aplicación Xamarin.Forms en la aplicación .NET MAUI.
  • Actualiza los espacios de nombres
  • Soluciona los cambios de API.
  • Actualiza o reemplaza las dependencias incompatibles con versiones de .NET 8.
  • Compila y prueba la aplicación.

Para simplificar el proceso de actualización, debes crear una nueva aplicación .NET MAUI con el mismo nombre que la aplicación Xamarin.Forms y, después, copiar en el código, la configuración y los recursos. Este es el método que se describe a continuación.

Actualiza tu aplicación Xamarin.Forms

Antes de actualizar la aplicación Xamarin.Forms a .NET MAUI, primero debes actualizar la aplicación Xamarin.Forms para usar Xamarin.Forms 5 y asegurarte de que todavía se ejecuta correctamente. Además, debes actualizar las dependencias que usa la 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 usando versiones compatibles con .NET de las dependencias si existen.

Crear una aplicación .NET MAUI

En Visual Studio, crea una aplicación .NET MAUI con el mismo nombre que la aplicación Xamarin.Forms:

Captura de pantalla de la creación de una aplicación MAUI de .NET en Visual Studio.

Al abrir el archivo del proyecto, se confirmará que tienes un proyecto de estilo SDK de .NET.

Copia del código en la aplicación de .NET MAUI

Todo el código multiplataforma del proyecto de biblioteca Xamarin.Forms debe copiarse en el proyecto de aplicación de .NET MAUI en carpetas y archivos con nombre idéntico.

Los representadores personalizados se pueden reutilizar en una aplicación de .NET MAUI o migrar a un controlador de .NET MAUI. Para obtener más información, consulta Reutilización de representadores personalizados en .NET MAUI y Migración de un representador personalizado Xamarin.Forms a un controlador de .NET MAUI.

Los efectos se pueden reutilizar en una aplicación de .NET MAUI. Para obtener más información, consulta Reutilización de efectos.

Nota:

Puede actualizar rápidamente losXamarin.Forms espacios de nombres aMicrosoft.Maui mediante acciones rápidas en Visual Studio, siempre que haya instalado Asistente de actualización.

Código específico de la plataforma

Un proyecto de aplicación .NET MAUI contiene una carpeta Plataforms en la que cada carpeta secundaria representa una plataforma que .NET MAUI puede tener como destino.

Captura de pantalla de carpetas de plataforma.

Las carpetas de cada plataforma contienen recursos específicos de la plataforma y el código que inicia la aplicación en cada plataforma:

Captura de pantalla de código específica de la plataforma.

El código, y las carpetas que lo contienen, de tus proyectos principales Xamarin.Forms deben copiarse en estas carpetas:

  • El código de tu proyecto principal de Android Xamarin.Forms debe copiarse en la carpeta Platform\Android de tu proyecto de aplicación de .NET MAUI. Además, copia cualquier código personalizado de tus clases Xamarin.FormsMainActivity y MainApplication en las mismas clases de tu proyecto de aplicación de .NET MAUI.

  • El código de tu proyecto principal de Xamarin.Forms iOS debe copiarse en la carpeta Platforms\iOS de tu proyecto de aplicación de .NET MAUI. Además, copia cualquier código personalizado de tu clase Xamarin.FormsAppDelegate en la misma clase de tu proyecto de aplicación de .NET MAUI.

    Nota:

    Para obtener una lista de los cambios importantes en .NET para iOS, consulte Cambios importantes en .NET para iOS.

  • El código de tu proyecto principal de UWP Xamarin.Forms debe copiarse en la carpeta Plataforms\Windows de tu proyecto de aplicación de .NET MAUI. Además, copia cualquier código personalizado de tu clase Xamarin.FormsApp en la misma clase de tu proyecto de aplicación de .NET MAUI.

En tiempo de compilación, el sistema de compilación solo incluye el código de cada carpeta al compilar para esa plataforma específica. Por ejemplo, al compilar para Android, los archivos de la carpeta Plataformas\Android se integrarán en el paquete de la aplicación, pero no los archivos de las demás carpetas Plataformas. Este enfoque usa una característica denominada múltiples versiones que pretende tener como destino varias plataformas desde un único proyecto. Las aplicaciones de .NET MAUI también pueden tener varios destinos en función de sus propios criterios de nombre de archivo y carpeta. Esto te permite estructurar el proyecto de aplicación de .NET MAUI para que no tengas que colocar tu código de la plataforma en carpetas secundarias de la carpeta Plataforms. Para obtener más información, consulta Configuración de varios destinos.

Copia de la configuración en la aplicación de .NET MAUI

Cada plataforma usa su propio archivo de manifiesto de aplicación nativa para especificar información como el título de la aplicación, el identificador, la versión, etc. El proyecto único de .NET MAUI permite especificar estos datos comunes de la aplicación en una sola ubicación en el archivo del proyecto.

Para especificar los datos del manifiesto de la aplicación compartida para un proyecto, en el Explorador de soluciones, abre el menú contextual del proyecto y, luego, elige Propiedades. El título, el identificador y la versión de la aplicación se pueden especificar en MAUI Shared > General:

Captura de pantalla del manifiesto de la aplicación MAUI de .NET.

En tiempo de compilación, los datos del manifiesto de la aplicación compartida se combinan con datos específicos de la plataforma en el archivo de manifiesto de aplicación nativa, para generar el archivo de manifiesto para el paquete de la aplicación. Para obtener más información, consulta Configuración de proyectos en .NET MAUI: MAUI compartido.

Los datos restantes de los manifiestos de la aplicación Xamarin.Forms deben copiarse en el manifiesto de la aplicación de .NET MAUI:

  • En Android, copia los datos adicionales del archivo AndroidManifest.xml en el proyecto principal de Android Xamarin.Forms, en el archivo Platforms\Android\AndroidManifest.xml del proyecto de aplicación de .NET MAUI
  • En iOS, copia los datos adicionales del archivo Info.plist en el proyecto principal de iOS Xamarin.Forms, en el archivo Platforms\iOS\Info.plist del proyecto de aplicación de .NET MAUI. Además, copia el archivo Entitlements.plist en el proyecto principal de iOS Xamarin.Forms en la carpeta Platforms\iOS del proyecto de aplicación de .NET MAUI.
  • En Windows, copia datos adicionales del archivo Package.appxmanifest en el proyecto principal de UWP Xamarin.Forms, en el archivo Platforms\Windows\Package.appxmanifest en el proyecto de aplicación de .NET MAUI.

Copia los recursos a la aplicación de .NET MAUI

El proyecto único .NET MAUI permite almacenar archivos de recursos en una sola ubicación mientras se consumen en cada plataforma. Esto incluye fuentes, imágenes, el icono de la aplicación, la pantalla de presentación, los recursos sin procesar y los archivos CSS para aplicar estilos a aplicaciones .NET MAUI.

Normalmente, los archivos de recursos deben colocarse en la carpeta Resources del proyecto de aplicación de .NET MAUI o en las carpetas secundarias de la carpeta Resources y deben tener la acción de compilación establecida correctamente. En la tabla siguiente se muestran las acciones de compilación para cada tipo de archivo de recurso:

Resource Acción de compilación
Icono de aplicación MauiIcon
Fuentes MauiFont
Imágenes MauiImage
Pantalla de presentación MauiSplashScreen
Recursos sin procesar MauiAsset
CSS archivos MauiCss

Nota:

Los archivos XAML también se almacenan en el proyecto de aplicación de .NET MAUI y se les asigna automáticamente la acción de compilación MauiXaml. Sin embargo, solo los diccionarios de recursos XAML se colocarán, por lo general, en la carpeta Resources del proyecto de la aplicación.

En la captura de pantalla siguiente se muestra una carpeta Resources típica que contiene carpetas secundarias para cada tipo de recurso:

Captura de pantalla de recursos de imagen y fuente.

La acción de compilación de un archivo de recursos se establecerá correctamente si el recurso se ha agregado a la carpeta secundaria Resources correcta.

Importante

Los recursos específicos de la plataforma reemplazarán a sus recursos compartidos homólogos. Por ejemplo, si tiene una imagen específica de Android ubicada en Platforms\Android\Resources\drawable-xhdpi\logo.png, y también proporciona una imagen compartida Resources\Images\logo.svg, el archivo de Gráficos vectoriales escalables (SVG) se usará para generar las imágenes de Android necesarias, excepto para la imagen XHDPI que ya existe como una imagen específica de la plataforma.

Iconos de aplicación

Tu icono de aplicación Xamarin.Forms debe agregarse al proyecto de aplicación de .NET MAUI arrastrando la imagen a la carpeta Resources\AppIcon del proyecto, donde su acción de compilación se establecerá automáticamente en MauiIcon. Durante la compilación, el icono de la aplicación se cambia de tamaño a los tamaños correctos de la plataforma y el dispositivo de destino. Los iconos de la aplicación se cambian de tamaño a varias resoluciones porque tienen varios usos, incluidos los que se usan para representar la aplicación en el dispositivo y en la tienda de aplicaciones.

Para obtener más información, consulta Agregar un icono de aplicación aun proyecto de aplicación de .NET MAUI.

Pantalla de presentación

Si tu aplicación Xamarin.Forms tiene una pantalla de presentación, debes agregarla a tu proyecto de aplicación de .NET MAUI arrastrando la imagen a la carpeta Resources\Splash del proyecto, donde su acción de compilación se establecerá automáticamente en MauiSplashScreen. Durante la compilación, la imagen de la pantalla de presentación cambia de tamaño al tamaño correcto para la plataforma y el dispositivo de destino.

Para obtener más información, consulta Agregar una pantalla de presentación a un proyecto de aplicación de .NET MAUI.

Imágenes

Los dispositivos tienen una gama de tamaños y densidades de pantalla y cada plataforma móvil tiene funcionalidad para mostrar imágenes dependientes de la densidad. En Xamarin.Forms, las imágenes que dependen de la densidad suelen colocarse en proyectos principales y adoptan una convención de nomenclatura específica de la plataforma. Hay dos enfoques que se pueden adoptar para migrar estas imágenes a .NET MAUI.

El enfoque recomendado es copiar la versión de resolución más alta de cada imagen de tu solución Xamarin.Forms al proyecto de la aplicación .NET MAUI arrastrándolo hasta la carpeta Resources\Images del proyecto, donde su acción de compilación se establecerá automáticamente en MauiImage. También será necesario establecer el atributo BaseSize de cada imagen de mapa de bits para asegurar que se produce el cambio de tamaño. Esto elimina la necesidad de tener varias versiones de cada imagen en cada plataforma. En tiempo de compilación, las imágenes se cambiarán a varias imágenes dependientes de la densidad que cumplan los requisitos de la plataforma. Para obtener más información, consulta Adición de imágenes a un proyecto de aplicación .NET MAUI.

Como alternativa, puedes copiar imágenes dependientes de la densidad de la solución Xamarin.Forms en carpetas con nombre idéntico en la carpeta Platforms\{Platform} del proyecto de aplicación de .NET MAUI y establecer sus acciones de compilación en las acciones de compilación que se usan en la solución Xamarin.Forms. En la tabla siguiente se enumeran las ubicaciones de imágenes de ejemplo de una solución Xamarin.Forms y su ubicación equivalente en un proyecto de aplicación de .NET MAUI:

Ubicación de las imágenes en Xamarin.Forms Ubicación de las imágenes en .NET MAUI Acción de compilación de imágenes de la plataforma .NET MAUI
{MyApp.Android}\Resources\drawable-xhdpi\image.png Platforms\Android\Resources\drawable-xhdpi\image.png AndroidResource
{MyApp.iOS}\image.jpg *Platforms\iOS\Resources\image.jpg BundleResource
{MyApp.UWP}\Assets\Images\image.gif *Platforms\Windows\Assets\Images\image.gif Contenido

Siempre que hayas adoptado la misma convención de nomenclatura de imágenes que usaste en la solución Xamarin.Forms, se elegirá la imagen adecuada en tiempo de ejecución según las funcionalidades del dispositivo. La desventaja de este enfoque es que sigues teniendo varias versiones de cada imagen en cada plataforma.

Fuentes

Las fuentes de la solución Xamarin.Forms se pueden agregar a la solución de .NET MAUI arrastrándolas a la carpeta Resources\Fonts del proyecto de aplicación de .NET MAUI, donde su acción de compilación se establecerá automáticamente en MauiFont.

Para obtener más información, consulta Fuentes.

CSS archivos

Los archivos CSS de la solución Xamarin.Forms se pueden agregar a la solución de .NET MAUI arrastrándolos a una carpeta con nombre idéntico y estableciendo su acción de compilación en MauiCss en la ventana Propiedades.

Para obtener más información sobre cómo usar los archivos CSS en una aplicación .NET MAUI, consulta Aplicar estilo a las aplicaciones mediante hojas de estilos en cascada.

Recursos sin procesar

Los archivos de recursos sin procesar, como HTML, JSON y vídeo, deben copiarse de la solución Xamarin.Forms en el proyecto de aplicación .NET MAUI arrastrándolos a la carpeta Resources\Raw del proyecto, donde su acción de compilación se establecerá automáticamente en MauiAsset.

Recursos localizados

En una aplicación .NET MAUI, las cadenas se localizan con el mismo enfoque que en una aplicación Xamarin.Forms. Por lo tanto, los archivos de recursos de .NET (.resx) deben copiarse de la solución Xamarin.Forms en una carpeta con nombre idéntico en la solución de .NET MAUI. Luego se debe especificar el idioma neutro de la aplicación .NET MAUI. Para obtener más información, consulta Especificar el idioma neutro de la aplicación.

Nota:

Los archivos de recursos de .NET no tienen que colocarse en la carpeta Resources del proyecto de aplicación de .NET MAUI.

En una aplicación .NET MAUI, las imágenes se localizan con el mismo enfoque que en una aplicación Xamarin.Forms. Por lo tanto, las imágenes localizadas y las carpetas en las que residen deben copiarse de la solución Xamarin.Forms en el proyecto de aplicación .NET MAUI:

  • En Android, la carpeta raíz del proyecto de aplicación .NET MAUI para las imágenes localizadas es Platforms\Android\Resources.
  • En iOS, la carpeta raíz del proyecto de aplicación .NET MAUI para las imágenes localizadas es Platforms\iOS\Resources.
  • En Windows, la carpeta raíz del proyecto de aplicación .NET MAUI para las imágenes localizadas es Platforms\Windows\Assets\Images.

Las imágenes localizadas deben tener sus acciones de compilación establecidas en las acciones de compilación que se usan en la solución Xamarin.Forms. Para obtener más información, consulta Localización de imágenes.

En una aplicación .NET MAUI, los nombres de aplicación se localizan con el mismo enfoque que en una aplicación Xamarin.Forms:

  • En Android, el nombre de la aplicación localizada se puede almacenar mediante una convención de nomenclatura basada en carpetas en la carpeta Platforms\Android\Resources. Las carpetas y los archivos de localización de nombres de aplicación deben copiarse en esta carpeta de la solución Xamarin.Forms.
  • En iOS, el nombre de la aplicación localizada se almacena mediante una convención de nomenclatura basada en carpetas en la carpeta Platforms\iOS\Resources. Las carpetas y los archivos de localización de nombres de aplicación deben copiarse en esta carpeta de la solución Xamarin.Forms.
  • En Windows, el nombre de la aplicación localizada se almacena en el manifiesto del paquete de la aplicación.

Para obtener más información, consulta Localizar el nombre de la aplicación. Para obtener más información sobre la localización de la aplicación .NET MAUI, consulta Localización.

Cambios en el espacio de nombres

Los espacios de nombres han cambiado al pasar de Xamarin.Forms a .NET MAUI y Xamarin.Essentials las características ahora forman parte de .NET MAUI. Para realizar actualizaciones de espacios de nombres, realiza una búsqueda y una sustitución para los siguientes espacios de nombres:

Espacio de nombres Xamarin.Forms Espacios de nombres de .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 usan directivas global using implícitas. Esta característica permite quitar directivas using para el espacio de nombres Xamarin.Essentials, sin tener que reemplazarlas por los espacios de nombres de .NET MAUI equivalentes.

Además, el espacio de nombres de 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, debes reemplazar todas las apariciones de xmlns="http://xamarin.com/schemas/2014/forms" por xmlns="http://schemas.microsoft.com/dotnet/2021/maui".

Nota:

Puede actualizar rápidamente losXamarin.Forms espacios de nombres aMicrosoft.Maui mediante acciones rápidas en Visual Studio, siempre que haya instalado Asistente de actualización.

Cambios de API

Algunas API han cambiado al pasar de Xamarin.Forms a .NET MAUI. Esta se debe a varias razones, incluida la eliminación de la funcionalidad duplicada causada al convertirse Xamarin.Essentials en parte de .NET MAUI y al asegurarse de que las API siguen las directrices de nomenclatura de .NET. En las secciones siguientes se describen estos cambios.

Cambios de color

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

La clase Microsoft.Maui.Graphics.Color, en el espacio de nombres Microsoft.Maui.Graphics, permite construir objetos Color mediante 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 medida los mismos colores con nombre. Por ejemplo, use Colors.AliceBlue para especificar el color AliceBlue.

En la tabla siguiente se muestran los cambios de API entre la estructura Xamarin.Forms.Color y la clase Microsoft.Maui.Graphics.Color:

API Xamarin.Forms API .NET MAUI 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 Propiedad Xamarin.Forms reemplazada por un método en .NET MAUI.
Xamarin.Forms.Color.Saturation Microsoft.Maui.Graphics.Color.GetSaturation Propiedad Xamarin.Forms reemplazada por un método en .NET MAUI.
Xamarin.Forms.Color.Luminosity Microsoft.Maui.Graphics.Color.GetLuminosity Propiedad Xamarin.Forms reemplazada por un método en .NET MAUI.
Xamarin.Forms.Color.Default No hay equivalente de .NET MAUI. En su lugar, el valor predeterminado para objetos Microsoft.Maui.Graphics.Color es 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 es obsoleto y se eliminará en una próxima versión.

Además, todos los valores numéricos de 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

En la tabla siguiente se enumeran las API de diseño que se han quitado en el traslado de Xamarin.Forms a .NET MAUI:

API Xamarin.Forms API .NET MAUI Comentarios
Xamarin.Forms.AbsoluteLayout.IAbsoluteList<T>.Add La sobrecarga de Add que acepta 3 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 control de compatibilidad para los usuarios que migran desde Xamarin.Forms. Usa Grid en su lugar o agrega xmlns al espacio de nombres de compatibilidad.

Además, agregar elementos secundarios a un diseño en el código en Xamarin.Forms se logra agregando 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 para uso interno de .NET MAUI y no debe manipularse directamente. Por lo tanto, en el código, los elementos secundarios se deben agregar directamente al diseño:

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

Importante

Los métodos de extensión de diseño Add, como GridExtensions.Add, se invocan en el diseño en lugar de en la colección Children de diseños.

Es posible que al ejecutar la aplicación .NET MAUI actualizada notes que el comportamiento del diseño es diferente. Para ver más información, consulta Cambios de comportamiento de diseño desde Xamarin.Forms.

Cambios de diseño personalizados

El proceso para crear un diseño personalizado en Xamarin.Forms supone la creación de una clase que deriva de Layout<View> y la invalidación de los métodos VisualElement.OnMeasure y Layout.LayoutChildren. Para ver más información, consulta Creación de 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 en una clase de administrador de diseño. Cada clase del administrador de diseño implementa la interfaz ILayoutManager, que especifica que se deben proporcionar las implementaciones Measure y ArrangeChildren:

  • La implementación de Measure llama a IView.Measure en cada vista del diseño y devuelve el tamaño total de este según las restricciones.
  • La implementación de ArrangeChildren determina dónde se debe colocar cada vista dentro de los límites del diseño y llama a Arrange en cada vista con sus límites adecuados. El valor devuelto es el tamaño real del diseño.

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

Cambios de dispositivo

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

En la tabla siguiente se muestran las sustituciones de .NET MAUI para la funcionalidad en la clase Xamarin.Forms.Device:

API Xamarin.Forms API .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, use 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 de 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 espacios de nombres Microsoft.Maui.Controls.Maps y Microsoft.Maui.Maps. Se ha cambiado el nombre de algunas propiedades y algunos tipos se han reemplazado por tipos equivalentes de Xamarin.Essentials.

En la tabla siguiente se muestran las sustituciones de .NET MAUI para la funcionalidad en el espacio de nombres Xamarin.Forms.Maps:

API Xamarin.Forms API .NET MAUI 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 cambiaron al tipo Microsoft.Maui.Devices.Sensors.Location.
Xamarin.Forms.Maps.Geocoder Microsoft.Maui.Devices.Sensors.Geocoding Los miembros del tipo Xamarin.Forms.Maps.Geocoder cambiaron al tipo Microsoft.Maui.Devices.Sensors.Geocoding.

.NET MAUI tiene dos tipos de Map: Microsoft.Maui.Controls.Maps.Map y Microsoft.Maui.ApplicationModel.Map. Dado que el espacio de nombres Microsoft.Maui.ApplicationModel es una de las directivas global using de .NET MAUI, al usar el control Microsoft.Maui.Controls.Maps.Map del código tendrás que calificar completamente el uso de Map o usar un alias using.

En XAML, se debe agregar una definición de espacio de nombres xmlns para el 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 ver más información, consulta Visualización de un mapa.

Otros cambios

Se ha consolidado un pequeño número de otras API en el traslado de Xamarin.Forms a .NET MAUI. En la tabla siguiente se muestran estos cambios.

API Xamarin.Forms API .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 método ApplyQueryAttributes acepta un argumento IDictionary<string, object>.
Xamarin.Forms.MenuItem.Icon Microsoft.Maui.Controls.MenuItem.IconImageSource Xamarin.Forms.MenuItem.Icon es la clase base para Xamarin.Forms.ToolbarItem y, por tanto, ToolbarItem.Icon se convierte en ToolbarItem.IconImageSource.
Xamarin.Forms.OrientationStateTrigger.Orientation Microsoft.Maui.Controls.OrientationStateTrigger.Orientation En Xamarin.Forms, la propiedad OrientationStateTrigger.Orientation 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.ToolbarItem y, por tanto, ToolbarItem.Name se convierte en ToolbarItem.Text.

Además, en Xamarin.Forms, se llama a la invalidación Page.OnAppearing en Android cuando se encuentra en segundo plano una aplicación y, a continuación, se lleva al primer plano. Sin embargo, no se llama a esta invalidación en iOS y Windows en el mismo escenario. En .NET MAUI, no se llama a la invalidación de OnAppearing() en ninguna plataforma cuando una aplicación está en segundo plano y a continuación, se lleva al primer plano. En su lugar, debe escuchar los eventos de ciclo de vida en Window para recibir una notificación cuando una aplicación vuelve al primer plano. Para obtener más información, consulte .NET MAUI Windows.

Cambios en los formularios nativos

Los formularios nativos en Xamarin.Forms se han convertido en incrustaciones nativas en .NET MAUI y usan un enfoque de inicialización y métodos de extensión diferentes para convertir controles multiplataforma a sus tipos nativos. Para obtener más información, consulta Inserción nativa.

Cambios de AssemblyInfo

Las propiedades que normalmente se establecen en un archivo AssemblyInfo.cs ahora están disponibles en el proyecto de estilo SDK. Se recomienda migrarlos de AssemblyInfo.cs al archivo de proyecto de cada proyecto y quitar el archivo AssemblyInfo.cs .

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

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

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

Actualización de las dependencias de la aplicación

Por lo general, los paquetes NuGet Xamarin.Forms no son compatibles con .NET 8 a menos que se hayan vuelto a compilar mediante monikers de la plataforma de destino (TFM) de .NET. Sin embargo, las aplicaciones Android pueden usar paquetes NuGet destinados a los marcos monoandroid y monoandroidXX.X.

Para confirmar que un paquete es compatible con .NET 8, examina la pestaña Marcos de NuGet para el paquete que usa y comprueba que enumera uno de los marcos compatibles que se muestran en la tabla siguiente:

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 en los marcos incompatibles enumerados anteriormente siguen siendo compatibles con .NET 8.

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

Si no encuentras una versión compatible con .NET 8 de un paquete NuGet, debes:

  • Vuelve a compilar el paquete con TFM de .NET, si posees el código.
  • Busca una versión preliminar de una versión de una versión de .NET 8 del paquete.
  • Reemplaza la dependencia por una alternativa compatible con .NET 8.

Compilación y solución de problemas

Una vez resueltas las dependencias, debes compilar el proyecto. Los errores te guiarán hacia los pasos siguientes.

Sugerencia

  • Elimina 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.

En la tabla siguiente se proporcionan instrucciones para superar problemas comunes de compilación o del tiempo de ejecución:

Problema Sugerencia
El espacio de nombres Xamarin.* no existe. Actualiza el espacio de nombres a su equivalente en .NET MAUI. Para obtener más información, consulta Cambios en el espacio de nombres.
La API no existe. Actualiza el uso de la API a su equivalente en .NET MAUI. Para obtener más información, consulta Cambios en la API.
La aplicación no se implementará. Asegúrate de que el proyecto de plataforma necesario esté establecido para implementarse en el Administrador de configuración 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 obtener más información, consulta Arranque de la aplicación migrada.
CollectionView no se desplaza. Comprueba el diseño del contenedor y el tamaño medido de CollectionView. De forma predeterminada, el control ocupará tanto espacio como permita el contenedor. Grid restringe los elementos secundarios a su propio tamaño. Sin embargo, StackLayout permite que los elementos secundarios ocupen espacio más allá de sus límites.
El elemento emergente se muestra bajo la página de iOS. En Xamarin.Forms, todos los elementos emergentes de iOS son instancias de UIWindow, pero en los elementos emergentes de .NET MAUI se muestran localizando la presentación ViewController actual y mostrando el elemento emergente con PresentViewControllerAsync. En complementos como Mopups, para asegurarte de que los elementos emergentes se muestran correctamente, debes llamar a DisplayAlert, DisplayActionSheet o DisplayPromptAsync desde el elemento ContentPage que se usa dentro del elemento emergente Mopup.
BoxView no aparece. El tamaño predeterminado de BoxView en Xamarin.Forms es 40 x 40. El tamaño predeterminado de BoxView .NET MAUI es 0 x 0. Establece WidthRequest y HeightRequest en 40.
En el diseño, falta relleno, margen o espaciado. Agrega valores predeterminados al proyecto en función del recurso de estilo MAUI de .NET. Para obtener más información, consulta Cambios del valor predeterminado de Xamarin.Forms.
El diseño personalizado no funciona. El código de diseño personalizado necesita actualizar para que funcione en .NET MAUI. Para obtener más información, consulta Cambios en el diseño personalizado.
El representador personalizado no funciona. El código del representador necesita actualizarse para que funcione en .NET MAUI. Para obtener más información, consulta Uso de representadores personalizados en .NET MAUI.
El efecto no funciona. El código de efecto necesita actualizarse para que funcione en .NET MAUI. Para obtener más información, consulta Uso de efectos en .NET MAUI.
El código SkiaSharp no funciona. SkiaSharp código necesita actualizaciones menores para funcionar en .NET MAUI. Para obtener más información, consulte Reutilización del código SkiaSharp en .NET MAUI.
No se puede acceder a los datos de propiedades de la aplicación creados anteriormente. Migra los datos de propiedades de la aplicación a las preferencias de .NET MAUI. Para obtener más información, consulta Migración de 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 seguros creados anteriormente. Migra los datos del almacenamiento seguro a .NET MAUI. Para obtener más información, consulta Migración del almacenamiento seguro de Xamarin.Essentials al 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 obtener más información, consulta Migración de datos de seguimiento de versiones de una aplicación Xamarin.Forms a una aplicación .NET MAUI.