Migrar o código do Xamarin.Essentials em aplicativos .NET para Android e .NET para iOS

Xamarin.Essentials é uma biblioteca básica para quase todos os aplicativos Xamarin e a funcionalidade dela já faz parte do .NET MAUI (.NET Multi-Platform App UI).

As seguintes etapas descrevem o processo para usar a funcionalidade de dispositivo nativo do .NET MAUI, anteriormente conhecido como Xamarin.Essentials, em um aplicativo. NET para Android ou .NET para iOS:

1. Remova o pacote NuGet Xamarin.Essentials do aplicativo .NET para Android ou .NET para iOS.
2. Defina a propriedade de build $(UseMauiEssentials) como true no arquivo de projeto. Para obter mais informações, confira Modificar o arquivo de projeto.
3. Inicialize a funcionalidade do “Essentials” chamando o método Platform.Init. Para obter mais informações, confira Inicializar a plataforma.
4. Faça uma configuração adicional, se necessário. Para obter mais informações, confira Fazer uma configuração adicional.
5. Adicione diretivas using à funcionalidade necessária. Para obter mais informações, confira Adicionar diretivas using.

Importante

Nenhuma ação é necessária para usar o Xamarin.Essentials em um aplicativo .NET MAUI, além de remover as referências ao namespace Xamarin.Essentials, pois o .NET MAUI já inclui a funcionalidade do Xamarin.Essentials.

Modificar o arquivo de projeto

Para usar a funcionalidade de dispositivo nativo do .NET MAUI em um aplicativo .NET para Android ou .NET para iOS, modifique o arquivo de projeto e defina a propriedade de build $(UseMauiEssentials) como 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>

Inicializar a plataforma

Android

Em qualquer Activity que seja iniciada, você precisa chamar o método Platform.Init, que está no namespace Microsoft.Maui.ApplicationModel do 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);
        // ...
    }
}

O método Platform.Init exige um argumento Application ou um argumento Activity e um argumento Bundle.

iOS

Na classe AppDelegate, você precisa chamar o método Platform.Init, que está no namespace Microsoft.Maui.ApplicationModel do 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;
    }
}

O método Platform.Init exige um argumento Func<UIKit.UIViewController.

Observação

Se necessário, você pode recuperar o objeto UIViewController atual chamando o método Platform.GetCurrentUIViewController.

Fazer uma configuração adicional

A classe estática Platform contém auxiliares específicos da plataforma.

Android

Membro	Finalidade
ActivityStateChanged	Um evento gerado quando o estado de qualquer atividade é alterado.
AppContext	Uma propriedade que obtém o objeto Context que representa o contexto atual do aplicativo.
CurrentActivity	Uma propriedade que obtém o objeto Activity atual que representa a atividade atual.
Intent	Uma classe estática que contém a cadeia de caracteres ActionAppAction, que é o identificador para a Intent usada pelas ações do aplicativo.
OnNewIntent	Transmita um método Intent substituído de uma atividade ao invocar uma ação de aplicativo.
OnResume	Transmita um método Activity substituído de uma atividade quando uma Activity é retomada como parte da invocação de uma ação de aplicativo.
OnRequestPermissionsResult	Transmita os resultados da solicitação de permissão do método substituído de uma atividade para lidar com as solicitações de permissão internas.
WaitForActivityAsync	Aguarde até que uma Activity seja criada ou fique ativa.

Para acessar o Context ou a Activity atual do aplicativo em execução:

var context = Platform.AppContext;

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

Se houver uma situação em que o aplicativo Activity seja necessário, mas o aplicativo ainda não tenha sido totalmente iniciado, chame o método WaitForActivityAsync:

var activity = await Platform.WaitForActivityAsync();

Para lidar com solicitações de permissão de runtime, substitua o método OnRequestPermissionsResult em todas as Activity e chame o método Platform.OnRequestPermissionsResult nele:

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

Além de obter a Activity atual, você também pode se registrar para ver os 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();

Os estados de atividade são:

• Criado em
• Retomada
• Pausada
• Destruído
• SaveInstanceState
• Iniciado
• Interrompido

iOS

Método	Finalidade
ContinueUserActivity	Informa ao aplicativo que há dados associados à continuação de uma tarefa especificada como um objeto NSUserActivity e retorna se o aplicativo continuou a atividade.
GetCurrentUIViewController	Obtém o controlador de exibição atual. Esse método retornará null se não for possível detectar um UIViewController.
OpenUrl	Abre o URI especificado para iniciar um fluxo de autenticação.
PerformActionForShortcutItem	Invoca a ação que corresponde à AppAction escolhida pelo usuário.

Por exemplo, para lidar com ações de aplicativo, substitua o método PerformActionForShortcutItem na classe AppDelegate e chame o método Platform.PerformActionForShortcutItem nele:

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

Adicionar diretivas using

As diretivas global using implícitas para o .NET para iOS e o .NET para Android não incluem os namespaces para a funcionalidade de dispositivo nativo do .NET MAUI. Portanto, as diretivas using para o namespace Xamarin.Essentials devem ser substituídas por diretivas using para o namespace que contém a funcionalidade necessária:

Namespace	Finalidade
Microsoft.Maui.ApplicationModel	Funcionalidade do modelo de aplicativo, incluindo ações de aplicativo, permissões e acompanhamento de versão.
Microsoft.Maui.ApplicationModel.Communication	Funcionalidade de comunicação, incluindo contatos, email e rede.
Microsoft.Maui.Devices	Funcionalidade do dispositivo, incluindo bateria, sensores, lanterna e comentários hápticos.
Microsoft.Maui.Media	Funcionalidade de mídia, incluindo a seleção de mídia e a conversão de texto em fala.
Microsoft.Maui.ApplicationModel.DataTransfer	Funcionalidade de compartilhamento, incluindo a área de transferência e o compartilhamento de arquivos.
Microsoft.Maui.Storage	Funcionalidade de armazenamento, incluindo a seleção de arquivos e o armazenamento seguro.

Para obter mais informações sobre a funcionalidade de cada namespace, confira Integração de plataforma.