Compartir a través de

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

  • Artículo

La actualización de una aplicación Xamarin.Forms de varios proyectos a una aplicación de .NET Multi-platform App UI (.NET MAUI) de varios proyectos 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 proyecto de biblioteca Xamarin.Forms a un proyecto de biblioteca de .NET MAUI. Antes de hacerlo, debes actualizar tus proyectos de plataforma Xamarin.Forms para que sean proyectos de estilo SDK. Los proyectos de estilo SDK son del mismo formato de proyecto que usan todas las cargas de trabajo de .NET y, en comparación con muchos proyectos de Xamarin, son mucho menos detallados. Para obtener información sobre cómo actualizar los proyectos de la aplicación, vea Actualización de proyectos de Xamarin.Android, Xamarin.iOS y Xamarin.Mac a .NET, Migración de proyectos de Xamarin.Android, Migración de proyectos de Xamarin Appley Xamarin.Forms migración de proyectos de UWP.

Para migrar un proyecto de biblioteca Xamarin.Forms a un proyecto de biblioteca de .NET MAUI, 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.
  • Actualizar el archivo del proyecto para que sea un proyecto de tipo SDK.
  • Actualiza los espacios de nombres
  • Soluciona los cambios de API.
  • Configura .NET MAUI.
  • Actualiza o reemplaza las dependencias incompatibles con versiones de .NET 8.
  • Compila y prueba la 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, a continuación, 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.

Creación de un nuevo proyecto

En Visual Studio, crea un nuevo proyecto de biblioteca de clases de .NET MAUI con el mismo nombre que el proyecto de biblioteca Xamarin.Forms. Este proyecto hospedará el código de tu proyecto de biblioteca Xamarin.Forms. Al abrir el archivo del proyecto, se confirmará que tienes 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 tus proyectos de la plataforma, agrega una referencia a este nuevo proyecto de biblioteca. Después, copia los archivos de biblioteca Xamarin.Forms en el proyecto de biblioteca de .NET MAUI.

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, después, 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, después, 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, vea .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.

Arranque de la aplicación migrada

Al actualizar manualmente una aplicación Xamarin.Forms 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 $(UseMaui)propiedad de compilación a true 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 dejará de recibir errores de compilación sobre el método InitializeComponent que ya se está definiendo.

Incorporación de referencias de paquete

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

Debe agregar las siguientes referencias de paquete explícitas a un <ItemGroup> en cada archivo de proyecto:

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

Se hace referencia a la variable $(MauiVersion) desde la versión de .NET MAUI que has instalado. Para invalidar esto, agregue la propiedad de compilación $(MauiVersion) 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 de Android, actualiza la clase MainApplication 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();
    }
}

Actualiza también la clase MainActivity 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);
        }
    }
}

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

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

Configuración del proyecto de iOS

En el proyecto de .NET MAUI de iOS, actualiza la clase AppDelegate 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();
    }
}

Luego, actualiza 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 la 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 Propiedades 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 .NET MAUI tienen un único punto de entrada de aplicación multiplataforma. El punto de entrada de cada plataforma llama a un método CreateMauiApp en la clase estática MauiProgram y devuelve un MauiApp.

Por lo tanto, agrega 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 Xamarin.Forms proyectos de UWP, la referencia de App en builder.UseMauiApp<App>() se puede encontrar en el archivo MainPage.xaml.cs.

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

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

Consulta también