Migración de código Xamarin.Essentials en .NET para Android y .NET para aplicaciones iOS

Xamarin.Essentials es una biblioteca fundamental para casi todas las aplicaciones de Xamarin y su funcionalidad forma parte ahora de .NET Multi-platform App UI (.NET MAUI).

En los pasos siguientes se describe el proceso para usar la funcionalidad de dispositivo nativo de .NET MAUI, anteriormente conocida como Xamarin.Essentials, en una aplicación .NET para Android o .NET para iOS:

1. Quite el paquete NuGet Xamarin.Essentials de la aplicación .NET para Android o .NET para iOS.
2. Establece la propiedad de compilación $(UseMauiEssentials) en true en el archivo del proyecto. Para obtener más información, consulta Modificación del archivo de proyecto.
3. Inicializa la funcionalidad "essentials" llamando al método Platform.Init. Para obtener más información, consulta Inicialización de la plataforma.
4. Realiza una configuración adicional, si es necesario. Para obtener más información, consulta Configuración adicional.
5. Agrega directivas using para la funcionalidad necesaria. Para obtener más información, consulta Agregar directivas using.

Importante

No es necesario realizar ninguna acción para usar Xamarin.Essentials en una aplicación de .NET MAUI, aparte de quitar referencias al espacio de nombres Xamarin.Essentials, ya que .NET MAUI ya incluye la funcionalidad de Xamarin.Essentials.

Modificación del archivo de proyecto

Para usar .NET MAUIfuncionalidad de dispositivo nativo en una aplicación .NET para Android o .NET para iOS, modifique el archivo de proyecto y establezca la propiedad de compilación $(UseMauiEssentials) en true.

Android

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-android</TargetFramework>
    ...
    <UseMauiEssentials>true</UseMauiEssentials>
  </PropertyGroup>
</Project>

iOS

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-ios</TargetFramework>
    ...
    <UseMauiEssentials>true</UseMauiEssentials>
  </PropertyGroup>
</Project>

Inicialización de la plataforma

Android

En cualquier Activity que se inicie, debes llamar al método Platform.Init, que se encuentra en el espacio de nombres Microsoft.Maui.ApplicationModel, desde el método OnCreate:

using Android.Content.PM;
using Android.Runtime;
using Microsoft.Maui.ApplicationModel;

namespace MyAndroidApp;

[Activity(Label = "@string/app_name", MainLauncher = true)]
public class MainActivity : Activity
{
    protected override async void OnCreate(Bundle? savedInstanceState)
    {
        base.OnCreate(savedInstanceState);
        Platform.Init(this, savedInstanceState);
        // ...
    }
}

El método Platform.Init requiere un argumento Application o un argumento Activity y un argumento Bundle.

iOS

En la clase AppDelegate, debes llamar al método Platform.Init, que se encuentra en el espacio de nombres Microsoft.Maui.ApplicationModel, desde el método FinishedLaunching:

using Microsoft.Maui.ApplicationModel;

namespace MyiOSApp;

[Register("AppDelegate")]
public class AppDelegate : UIApplicationDelegate
{
    public override UIWindow? Window
    {
        get;
        set;
    }

    public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
    {
        // create a new window instance based on the screen size
        Window = new UIWindow(UIScreen.MainScreen.Bounds);

        // create a UIViewController with a single UILabel
        var vc = new UIViewController();
        // ...
        Window.RootViewController = vc;

        Platform.Init(() => vc);

        // make the window visible
        Window.MakeKeyAndVisible();

        return true;
    }
}

El método Platform.Init requiere un argumento Func<UIKit.UIViewController.

Nota:

Si es necesario, puedes recuperar el objeto UIViewController actual llamando al método Platform.GetCurrentUIViewController.

Configuración adicional

La clase Platform estática contiene asistentes específicos de la plataforma.

Android

Member	Fin
ActivityStateChanged	Evento que se genera cuando cambia el estado de cualquier actividad.
AppContext	Propiedad que obtiene el objeto Context que representa el contexto de la aplicación actual.
CurrentActivity	Propiedad que obtiene el objeto Activity actual que representa la actividad actual.
Intent	Una clase estática que contiene la cadena ActionAppAction, que es el identificador del Intent utilizado por las acciones de la aplicación.
OnNewIntent	Pasa un objeto Intent desde el método invalidado de una actividad al invocar una acción de aplicación.
OnResume	Pasa un objeto Activity desde el método invalidado de una actividad, cuando Activity se reanuda como parte de invocar una acción de aplicación.
OnRequestPermissionsResult	Pasa los resultados de la solicitud de permiso del método invalidado de una actividad para controlar las solicitudes de permisos internos.
WaitForActivityAsync	Espera a que se cree o se active una Activity.

Para acceder a Context o Activity actual para la aplicación en ejecución:

var context = Platform.AppContext;

// Current Activity or null if not initialized or not started.
var activity = Platform.CurrentActivity;

Si hay una situación en la que se necesita Activity, pero la aplicación no se inició totalmente, debes llamar al método WaitForActivityAsync:

var activity = await Platform.WaitForActivityAsync();

Para controlar las solicitudes de permisos en tiempo de ejecución, invalida el método OnRequestPermissionsResult en cada Activity y llama al método Platform.OnRequestPermissionsResult desde él:

public override void OnRequestPermissionsResult(int requestCode, string[] permissions, Permission[] grantResults)
{
    Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults);
    base.OnRequestPermissionsResult(requestCode, permissions, grantResults);
}

Además de obtener la Activity actual, también puedes registrarte en los eventos de ciclo de vida.

protected override void OnCreate(Bundle bundle)
{
    base.OnCreate(bundle);
    Platform.Init(this, bundle);
    Platform.ActivityStateChanged += Platform_ActivityStateChanged;
}

protected override void OnDestroy()
{
    base.OnDestroy();
    Platform.ActivityStateChanged -= Platform_ActivityStateChanged;
}

void Platform_ActivityStateChanged(object sender, ActivityStateChangedEventArgs e) =>
    Toast.MakeText(this, e.State.ToString(), ToastLength.Short).Show();

Los estados de actividad son:

• Creado
• Reanudado
• En pausa
• Destruido
• SaveInstanceState
• Comenzado
• Detenido

iOS

Método	Fin
ContinueUserActivity	Informa a la aplicación de que hay datos asociados con la continuación de una tarea especificada como un objeto NSUserActivity, y luego devuelve si la aplicación continuó la actividad.
GetCurrentUIViewController	Obtiene el controlador de vista actual. Este método devolverá null si no puede detectar UIViewController.
OpenUrl	Abre el URI especificado para iniciar un flujo de autenticación.
PerformActionForShortcutItem	Invoca la acción que corresponde al AppAction elegido por el usuario.

Por ejemplo, para controlar las acciones de la aplicación, invalida el método PerformActionForShortcutItem de la clase AppDelegate y llama al método Platform.PerformActionForShortcutItem método desde allí:

public override void PerformActionForShortcutItem(UIApplication application, UIApplicationShortcutItem shortcutItem, UIOperationHandler completionHandler)
{
    Platform.PerformActionForShortcutItem(application, shortcutItem, completionHandler);
}

Adición de directivas using

Las directivas implícitas de global using para .NET para iOS y .NET para Android no incluyen los espacios de nombres para la funcionalidad de dispositivo nativo .NET MAUI. Por lo tanto, las directivas using del espacio de nombres Xamarin.Essentials deben reemplazarse por directivas using para el espacio de nombres que contiene las funciones necesarias:

Espacio de nombres	Fin
Microsoft.Maui.ApplicationModel	Funciones del modelo de aplicación, como las acciones de la aplicación, los permisos y el seguimiento de versiones.
Microsoft.Maui.ApplicationModel.Communication	Funciones de comunicación, como los contactos, el correo electrónico y las redes.
Microsoft.Maui.Devices	Funciones del dispositivo, como la batería, los sensores, la linterna y los comentarios hápticos.
Microsoft.Maui.Media	Funciones multimedia, como la selección de medios y texto a voz.
Microsoft.Maui.ApplicationModel.DataTransfer	Funciones de uso compartido, como el portapapeles y el uso compartido de archivos.
Microsoft.Maui.Storage	Funciones de almacenamiento, como la selección de archivos y el almacenamiento seguro.

Para obtener más información sobre la funcionalidad de cada espacio de nombres, consulta Integración de plataformas.