通过

在 .NET for Android 和 .NET for iOS 应用中迁移 Xamarin.Essentials 代码

  • 项目

Xamarin.Essentials 是几乎每个 Xamarin 应用的基本库，其功能现在是 .NET Multi-platform App UI (.NET MAUI) 的一部分。

以下步骤概述了在 .NET for Android 或 .NET for iOS 应用中使用 .NET MAUI 的本机设备功能（以前称为 Xamarin.Essentials）的过程：

  1. 从 .NET for Android 或 .NET for iOS 应用中删除 Xamarin.Essentials NuGet 包。
  2. 在项目文件中将 $(UseMauiEssentials) 生成属性设置为 true。 有关详细信息，请参阅修改项目文件。
  3. 通过调用 Platform.Init 方法初始化“essentials”功能。 有关详细信息，请参阅初始化平台。
  4. 如有必要，请执行其他设置。 有关详细信息，请参阅执行其他设置。
  5. 为所需功能添加 using 指令。 有关详细信息，请参阅添加 using 指令。

重要

要在 .NET MAUI 应用中使用 Xamarin.Essentials，除了删除对 Xamarin.Essentials 命名空间的引用外，无需进行任何操作，因为 .NET MAUI 已包含 Xamarin.Essentials 中的功能。

修改项目文件

要在 .NET for Android 或 .NET for iOS 应用中使用 .NET MAUI 本机设备功能，请修改项目文件并将 $(UseMauiEssentials) 生成属性设置为 true。

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

初始化平台

在任何已启动的 Activity 中，必须从 OnCreate 方法调用位于 Microsoft.Maui.ApplicationModel 命名空间中的 Platform.Init 方法：

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);
        // ...
    }
}

Platform.Init 方法需要 Application 参数，或者 Activity 参数和 Bundle 参数。

执行其他设置

静态 Platform 类包含特定于平台的帮助程序。

成员 用途
ActivityStateChanged 当任何活动的状态发生更改时引发的事件。
AppContext Context 对象，表示获取属性值的方法。
CurrentActivity 获取表示当前活动的当前 Activity 对象的属性。
Intent 包含字符串的 ActionAppAction 静态类，它是应用操作使用的标识符 Intent 。
OnNewIntent Intent调用应用操作时，从活动的重写方法传递一个。
OnResume Activity在调用应用操作时Activity，从活动的重写方法传递一个。
OnRequestPermissionsResult 传递活动重写方法的权限请求结果，用于处理内部权限请求。
WaitForActivityAsync 等待 Activity 创建或激活。

要访问正在运行的应用的当前 Context 或 Activity，请执行以下操作：

var context = Platform.AppContext;

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

如果需要 Activity，但应用尚未完全启动，应使用 WaitForActivityAsync 方法。

var activity = await Platform.WaitForActivityAsync();

要处理运行时权限请求，请在每个 Activity 中替代 OnRequestPermissionsResult 方法，并从其调用 Platform.OnRequestPermissionsResult 方法：

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

除获取当前 Activity 之外，还可以注册生命周期事件：

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

活动状态为：

  • 已创建
  • Resumed
  • 已暂停
  • 已破坏
  • SaveInstanceState
  • 已开始
  • 已停止

添加 using 指令

.NET for iOS 和 .NET for Android 的隐式 global using 指令不包括 .NET MAUI 本机设备功能的命名空间。 因此，Xamarin.Essentials 命名空间的 using 指令应替换为包含所需功能的命名空间的 using 指令：

命名空间 用途
Microsoft.Maui.ApplicationModel 应用程序模型功能，包括应用操作、权限和版本跟踪。
Microsoft.Maui.ApplicationModel.Communication 通信功能，包括联系人、电子邮件和网络。
Microsoft.Maui.Devices 设备功能，包括电池、传感器、手电筒和触觉反馈。
Microsoft.Maui.Media 媒体功能，包括媒体选取和文本语音转换。
Microsoft.Maui.ApplicationModel.DataTransfer 共享功能，包括剪贴板和文件共享。
Microsoft.Maui.Storage 存储功能，包括文件选取和安全存储。

有关每个命名空间中的功能的详细信息，请参阅平台集成。