Migrer du code Xamarin.Essentials dans les applications .NET pour iOS et .NET pour Android

Xamarin.Essentials est une bibliothèque fondamentale pour presque toutes les applications Xamarin, et ses fonctionnalités font désormais partie de .NET Multi-platform App UI (.NET MAUI).

Les étapes suivantes décrivent le processus d’utilisation de la fonctionnalité d’appareil native de .NET MAUI, anciennement appelée Xamarin.Essentials, dans une application .NET pour Android ou .NET pour iOS :

1. Supprimez le package NuGet Xamarin.Essentials de votre application .NET pour Android ou .NET pour iOS.
2. Définissez la propriété de build $(UseMauiEssentials) sur true dans votre fichier projet. Pour plus d’informations, consultez Modifier votre fichier projet.
3. Initialisez la fonctionnalité « essentials » en appelant la méthode Platform.Init. Pour plus d’informations, consultez Initialiser la plateforme.
4. Effectuez une configuration supplémentaire, si nécessaire. Pour plus d’informations, consultez Effectuer une configuration supplémentaire.
5. Ajoutez des directives Using pour les fonctionnalités requises. Pour plus d’informations, consultez Ajouter des directives Using.

Important

Aucune action n’est requise pour utiliser Xamarin.Essentials dans une application .NET MAUI, en dehors de la suppression de références à l’espace de noms Xamarin.Essentials, car .NET MAUI inclut déjà les fonctionnalités de Xamarin.Essentials.

Modifier votre fichier projet

Pour utiliser la fonctionnalité d’appareil native de .NET MAUI dans un application .NET pour Android ou .NET pour iOS, modifiez votre fichier projet et définissez la propriété de build $(UseMauiEssentials) sur 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>

Initialiser la plateforme

Android

Dans tout les Activity lancés, vous devez appeler la méthode Platform.Init, qui se trouve dans l’espace de noms Microsoft.Maui.ApplicationModel, à partir de la méthode 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);
        // ...
    }
}

La méthode Platform.Init nécessite un argument Application ou un argument Activity et un argument Bundle.

iOS

Dans votre classe AppDelegate, vous devez appeler la méthode Platform.Init, qui se trouve dans l’espace de noms Microsoft.Maui.ApplicationModel, à partir de la méthode 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;
    }
}

La méthode Platform.Init nécessite un argument Func<UIKit.UIViewController.

Remarque

Si nécessaire, vous pouvez récupérer l’objet UIViewController actuel en appelant la méthode Platform.GetCurrentUIViewController.

Effectuer une configuration supplémentaire

La classe statique Platform contient des programmes d’assistance spécifiques à la plateforme.

Android

Membre	Objectif
ActivityStateChanged	Un événement déclenché lorsque l’état d’une activité change.
AppContext	Une propriété qui obtient l’objet Context qui représente le contexte d’application actuel.
CurrentActivity	Une propriété qui obtient l’objet Activity actuel qui représente l’activité actuelle.
Intent	Une classe statique qui contient la chaîne ActionAppAction, qui est l’identificateur pour le Intent utilisé par les actions d’application.
OnNewIntent	Transmettez un Intent à partir de la méthode substituée d’une activité lors de l’appel d’une action d’application.
OnResume	Transmettez un Activity à partir de la méthode substituée d’une activité lorsqu’un Activity est repris dans le cadre de l’appel d’une action d’application.
OnRequestPermissionsResult	Transmettez les résultats de la demande d’autorisation à partir de la méthode substituée d’une activité pour gérer les demandes d’autorisation internes.
WaitForActivityAsync	Attendez qu’un Activity soit créé ou devienne actif.

Pour accéder au Context ou au Activity actuel pour l’application en cours d’exécution :

var context = Platform.AppContext;

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

Dans le cas où Activity est nécessaire, mais que l’application n’a pas entièrement démarré, appelez la méthode WaitForActivityAsync :

var activity = await Platform.WaitForActivityAsync();

Pour gérer les demandes d’autorisation d’exécution, remplacez la méthode OnRequestPermissionsResult dans chaque Activity et appelez la méthode Platform.OnRequestPermissionsResult à partir de celle-ci :

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

En plus d’obtenir le Activity actuel, vous pouvez également vous inscrire aux événements de cycle de vie :

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();

Les états d’activité sont les suivants :

• Créé
• Repris
• Suspendu
• Détruit
• SaveInstanceState
• Démarré
• Arrêté

iOS

Méthode	Objectif
ContinueUserActivity	Informe l’application qu’il existe des données associées à la poursuite d’une tâche spécifiée en tant qu’objet NSUserActivity, puis retourne si l’application a continué l’activité.
GetCurrentUIViewController	Obtient le contrôleur d’affichage actuel. Cette méthode retourne null si elle ne parvient pas à détecter un UIViewController.
OpenUrl	Ouvre l’URI spécifié pour démarrer un flux d’authentification.
PerformActionForShortcutItem	Appelle l’action qui correspond au AppAction choisi par l’utilisateur.

Par exemple, pour gérer les actions d’application, remplacez la méthode PerformActionForShortcutItem dans votre classe AppDelegate et appelez la méthode Platform.PerformActionForShortcutItem à partir de celle-ci :

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

Ajouter des directives d’utilisation

Les directives global using implicites pour .NET pour iOS et .NET pour Android n’incluent pas les espaces de noms pour les fonctionnalités d’appareils natives de .NET MAUI. Par conséquent, les directives using pour l’espace de noms Xamarin.Essentials doivent être remplacées par des directives using pour l’espace de noms qui contient la fonctionnalité requise :

Espace de noms	Objectif
Microsoft.Maui.ApplicationModel	Fonctionnalités du modèle d’application, notamment les actions d’application, les autorisations et le suivi des versions.
Microsoft.Maui.ApplicationModel.Communication	Fonctionnalité de communication, notamment les contacts, la messagerie et la mise en réseau.
Microsoft.Maui.Devices	Fonctionnalité de l’appareil, notamment la batterie, les capteurs, la lampe de poche et les commentaires haptiques.
Microsoft.Maui.Media	Fonctionnalité multimédia, notamment la sélection du média et la synthèse vocale.
Microsoft.Maui.ApplicationModel.DataTransfer	Fonctionnalité de partage, notamment le Presse-papiers et le partage de fichiers.
Microsoft.Maui.Storage	Fonctionnalité de stockage, y compris la sélection du fichier et le stockage sécurisé.

Pour plus d’informations sur la fonctionnalité de chaque espace de noms, consultez Intégration de la plateforme.