技术速递｜使用 Native Library Interop 为 .NET MAUI 创建绑定

作者：Rachel Kang
排版：Alan Wang

在当今的应用开发领域，通过利用本机功能来扩展 .NET 应用程序的能力非常宝贵。.NET MAUI 处理程序架构使开发人员能够使用 .NET 代码直接操作本机控件，甚至允许无缝创建跨平台自定义控件。然而，其潜力不仅限于原生平台 API。如果您还能利用本机库 API，将会解锁更多可能性。

适用于 .NET MAUI 的 Native Library Interop（以前称为 Slim Binding 方法）是将本机库集成到 .NET MAUI 应用程序（包括 .NET for Android、.NET for iOS 和 .NET for Mac Catalyst）的替代方法。这种方法能够以既精简又易于维护的方式直接访问本机库 API，从而无需通过传统方法绑定整个库。

您可能会问自己，什么是绑定？当您想要使用不是用 C# 编写的第三方 iOS 或 Android 库时，您需要一种在 .NET MAUI 应用程序中使用它的方法。这就是绑定项目的作用所在，它使您能够创建 C# API 定义来描述本机 API 在 .NET 中的公开方式，以及它如何映射到底层库。建立此定义后，您可以对其进行编译以生成可在 .NET MAUI 应用程序中使用的“绑定”程序集。此过程反映了适用于 iOS 和 Android 的 .NET 的功能；当您在 C# 中使用本机 iOS 或 Android API 时，由于为核心 API 创建的绑定，它是可访问的。

Maui.NativeLibraryInterop 存储库是社区精选示例的宝贵资源，为 .NET 开发人员提供了一个深入研究和受益于共享知识以及贡献自己见解的机会。通过用于创建新绑定的现成模板，它为开发人员从概念到执行的旅程奠定了良好的基础。Native Library Interop 的优点在于它是一种更通用的绑定创建方式，不局限于绑定库，而且从技术上可用于更深入地挖掘原生平台 SDK。

在这篇文章中，我将分享我自己使用 .NET MAUI 的 Native Library Interop 的经验，并提供了一个实际示例来说明如何在 .NET MAUI 应用程序中使用这种创新的方法。请跟随我的步伐，使用模板并遵循入门文档的指导，来实现一个绑定。

开始使用 Native Library Interop 模板

首先，我克隆了 Maui.NativeLibraryInterop 存储库。如果想从现有的绑定示例（Facebook、Firebase、GoogleCast）开始构建，则应从相应文件夹中包含的示例开始。然而，由于我有兴趣从一个完全不同的库创建绑定，因此我将从模板开始！该模板包含使用 Native Library Interop 创建 Android 绑定、iOS 和 Mac Catalyst 绑定以及使用两者的 .NET MAUI 示例应用程序的基础。

获取先决条件
在继续操作之前，请确保您已安装所有先决条件。如果您是长期的 .NET MAUI 开发人员，那么您可能已经像我一样安装了大部分（如果不是全部）先决条件，但请务必检查先决条件的完整列表。

我将绑定什么？

那么我要绑定什么呢？好吧，我想在我的应用程序中包含一个漂亮的饼图！然而 .NET MAUI SDK 目前还没有内置的控件。

虽然我可以使用图表库创建的所有图表都非常漂亮，但我选择了 Native Library Interop 方法，因为我现在只需要在 .NET MAUI 应用程序中使用饼图，所以我只想绑定饼图的 API，仅此而已。

为了创建图表绑定，我将使用适用于 Android 的 MPAndroidChart 库以及适用于 iOS 和 Mac Catalyst 的等效图表库。

因此，我希望绑定名称能够反映这一点。对于 Android，我重命名了 android/native/newbinding/src/main/java/com/example/newbinding/DotnetNewBinding.java 中的类、文件名和 DotnetNewBinding 的所有引用。对于 MaciOS，我对 macios/native/NewBinding/NewBinding/DotnetNewBinding.swift 执行了同样的操作。虽然这是可选的，但我还是决定将项目中的所有文件夹、文件和“newBinding”实例重命名为“charts”。

很好，很简单。接下来是什么？

设置 .NET 绑定库

我计划为 Android、iOS 和 Mac Catalyst 绑定库，我很幸运能够使用我找到的库来支持这三个平台！如果我对所有平台都不感兴趣，我只需删除我不感兴趣平台的文件夹、目标框架和引用即可。

至于 .NET 版本，我目前会继续使用 .NET 8。不过，当我准备使用 .NET 9 时，我会分别更新 Charts.MaciOS.Binding.csproj 和 Charts.Android.Binding.csproj 中的 TargetFrameworks 和版本。

就是这样！虽然我可以选择在这里进行自定义，但除了模板已经为我设置的内容之外，我不需要采取任何额外的步骤来设置 .NET 绑定库。

设置本机包装器项目和库

现在，让我们确保相同的内容反映在本机项目中，并引入本机库！

iOS & Mac Catalyst

首先，我在 Xcode 中打开本机项目 macios/native/Charts/Charts.xcodeproj。我在 Targets > General 中检查支持的目标和 iOS 版本是否符合我的需求，这里我已经准备好了。在这里插入图片描述
现在，是时候引入本机 Charts 库了！由于引入本机库有多种选择，因此此步骤将根据最适合特定库和个人偏好的方式而有所不同。在我的例子中，我将选择使用 Swift 包管理器，方法是导航至 File > Add Package Dependencies…
在这里插入图片描述
搜索图表库包，

然后单击添加包。图表库已添加到我的本机 Xcode 项目中！

Android

现在，是时候在 Android 领域做同样的事情了！首先，我在 Android Studio 中打开本机项目 android/native。项目加载后，我打开 build.gradle.kts (:charts) 并确认 compileSdk 版本反映了我的需求。

现在，为了引入本机图表库，我在 build.gradle.kts 中进行了以下编辑：

dependencies {
    // 添加绑定库的包依赖
    implementation("com.github.PhilJay:MPAndroidChart:v3.1.0")
    // 复制绑定库的依赖项
     "copyDependencies"("com.github.PhilJay:MPAndroidChart:v3.1.0")
}

我还在 settings.gradle.kts 中添加了相关的 maven 存储库：

dependencyResolutionManagement {
    ...
    repositories {
        ...
        // 在此处添加存储库
        maven { url = uri("https://jitpack.io") }
    }
}

最后但同样重要的一点是，我点击右上角的“Sync Project with Gradle Files”按钮，让可爱的 Gradle 大象开心。

创建 API 接口

现在我们已经引入了本机库，是时候构建我们将在 .NET 应用程序中使用的 API 了！Native Library Interop 方法的妙处在于所有这些都发生在本机端。这意味着我们可以利用库提供的任何现有文档直接用本机语言编写 - 适用于 iOS 和 Mac Catalyst 的 Swift / Objective-C，以及适用于 Android 的 Java / Kotlin。这也意味着我们可以更轻松地更新这些 API，而无需手动将所有内容翻译成 .NET 术语所带来的额外负担。

iOS & Mac Catalyst

在 DotnetCharts.swift 中，我定义了所有我想要的 API。虽然这实际上意味着我可以在 Swift 中定义任何 API，但正如模板字符串示例所示，我现在将专注于创建图表 API 接口的任务，并将在文件顶部导入 DGCharts。

然后，我编写了创建饼图的 API 定义。作为一名 .NET 开发人员，我不能说我是 Swift 方面的专家，但可以直接从 Charts 库存储库中利用 Swift 示例，并获得 GitHub Copilot 的帮助，这无疑是一个改变游戏规则的举措，使这一部分变得不再那么令人生畏。

一旦我通过成功构建 Xcode 项目来确保我的 Swift 代码有效后，我就会尽快回到 .NET 这边，以确保本机库确实可以互操作。

我从 macios/Charts.MaciOS.Binding 运行 dotnet build。这会在 macios/native/Charts/bin/Release/net8.0-ios/sharpie/Charts/ApiDefinitions.cs 中生成 .NET API 定义，然后我将其复制到 charts/macios/Charts.MaciOS.Binding/ApiDefinition.cs 中。

然后，我再次运行 dotnet build 以确保一切正常。🙂
在这里插入图片描述

Android

现在又回到 Android 世界了！在 DotnetCharts.java 中，我可以用 Java 定义任何 API，正如这里的模板字符串示例所示。不过，为了专注于图表，我将导入我需要的所有内容。虽然这些库非常相似，但它们的实现略有不同，这也会影响我在此处导入和定义 API 的方式。

因此，我从 com.github.mikephil.charting 导入以下内容：

import com.github.mikephil.charting.charts.PieChart;
import com.github.mikephil.charting.data.PieData;
import com.github.mikephil.charting.data.PieDataSet;
import com.github.mikephil.charting.data.PieEntry;
import com.github.mikephil.charting.utils.ColorTemplate;

然后，我再次编写了创建饼图的 API 定义。正如我不是最精通 Swift 的专家一样，我也不是最精通 Android 的专家……但我仍然是一名移动应用开发人员！能够直接利用在线资源和 GitHub Copilot 使这一切变得非常可行。🙂

再次回到舒适的 .NET，我导航到 android/Charts.Android.Binding 并运行 dotnet build。
在这里插入图片描述
这将在 android/native/charts/bin/Release/net8.0-android/outputs/deps/MPAndroidChart-v3.1.0.aar 中生成依赖项的副本，与 iOS 和 Mac Catalyst 不同，我需要在我的 .NET 示例应用程序中直接引用它，方法是将以下内容添加到 MauiSample.csproj：

<!-- Reference the Android binding dependencies -->
<ItemGroup Condition="$(TargetFramework.Contains('android'))">
    <AndroidLibrary Include="..\android\native\charts\bin\Release\net8.0-android\outputs\deps\MPAndroidChart-v3.1.0.aar">
        <Bind>false</Bind>
        <Visible>false</Visible>
    </AndroidLibrary>
</ItemGroup>

在 .NET 应用中使用 API

现在是关键时刻！图表绑定现在可以用于任何新的或现有的 .NET MAUI 应用程序，包括任何 .NET for iOS、.NET for Mac Catalyst 和 .NET for Android 应用程序。为了简单起见，我将在模板附带的 .NET MAUI 示例应用程序中使用它，该示例应用程序已在 MauiSample.csproj 中为我引用了 .NET 绑定库：

<!-- 参考 MaciOS Binding 项目 -->
<ItemGroup Condition="$(TargetFramework.Contains('ios')) Or $(TargetFramework.Contains('maccatalyst'))">
    <ProjectReference Include="..\macios\Charts.MaciOS.Binding\Charts.MaciOS.Binding.csproj" />
</ItemGroup>
<!-- 参考Android Binding项目 -->
<ItemGroup Condition="$(TargetFramework.Contains('android'))">
    <ProjectReference Include="..\android\Charts.Android.Binding\Charts.Android.Binding.csproj" />
</ItemGroup>

在 MainPage.xaml.cs 中，我导入 ChartsMaciOS.DotnetCharts 和 ChartsAndroid.DotnetCharts，并使用平台指令来直接利用我创建的 API，就像我在 .NET MAUI 中使用任何其他特定于平台的实现一样。

public class MauiPieChart : View
{
    public List<PieChartSlice> Slices { get; set; } = new List<PieChartSlice>();
}
public class PieChartSlice
{
    public string Name { get; set; } = string.Empty;
    public int Count { get; set; }
    public Color Color
    {
        get => _color ??= GenerateRandomColor();
        set => _color = value;
    }
    private Color? _color = null;
    private Color GenerateRandomColor()
    {
        Random random = new Random();
        return new Color(random.Next(256), random.Next(256), random.Next(256));
    }
}
public partial class MauiPieChartHandler
{
    public static IPropertyMapper<MauiPieChart, MauiPieChartHandler> PropertyMapper = new PropertyMapper<MauiPieChart, MauiPieChartHandler>(ViewHandler.ViewMapper)
    {
    };
    public MauiPieChartHandler() : base(PropertyMapper)
    {
    }
}
#if IOS || MACCATALYST
public partial class MauiPieChartHandler : ViewHandler<MauiPieChart, UIKit.UIView>
{
    protected override UIKit.UIView CreatePlatformView()
    {   
        var data = Foundation.NSDictionary<Foundation.NSString, Foundation.NSNumber>.FromObjectsAndKeys (
            VirtualView.Slices.Select(s => new Foundation.NSNumber(s.Count)).ToArray(),
            VirtualView.Slices.Select(s => s.Name).ToArray()
        );
        var colors = VirtualView.Slices.Select(s => s.Color.ToPlatform()).ToArray();
        var pieChart = Charts.CreatePieChartWithData(data, colors);
        return pieChart;
    }
}
#elif ANDROID
public partial class MauiPieChartHandler : ViewHandler<MauiPieChart, Android.Views.View>
{
    protected override Android.Views.View CreatePlatformView()
    {
        var data = new Java.Util.LinkedHashMap();
        var colors = new List<Java.Lang.Integer>();
        foreach (var slice in VirtualView.Slices) {
            data.Put(slice.Name, slice.Count);
            colors.Add(new Java.Lang.Integer(slice.Color.ToPlatform().ToArgb()));
        }
        var pieChart = Charts.CreatePieChart(Microsoft.Maui.ApplicationModel.Platform.CurrentActivity, data, colors);
        return pieChart;
    }
}
#endif

现在，我可以从我的用户界面访问这个新的 MauiPieChart：

<local:MauiPieChart WidthRequest="300" HeightRequest="300">
    <local:MauiPieChart.Slices>
        <local:PieChartSlice Name="Dave's fans" Count="1" />
        <local:PieChartSlice Name="Rachel's fans" Count="5" />
        <local:PieChartSlice Name="Maddy's fans" Count="7" />
        <local:PieChartSlice Name="Beth's fans" Count="10" />
    </local:MauiPieChart.Slices>
</local:MauiPieChart>

瞧！我向您展示了 .NET MAUI 中漂亮的饼图！
在这里插入图片描述

您要绑定什么？

感谢你跟随我创建图表绑定的 Native Library Interop 之旅！若要查看所有代码，包括我的 API 定义和示例用法的详细信息，您可以在 https://github.com/rachelkang/MauiCharts 找到完整示例。若要了解有关 Native Library Interop 方法的更多信息，发现简化这一过程的内在魔力，并更好地了解何时使用它，请务必查看我们的文档。

我希望看到我的过程能够给您带来一些令人兴奋的想法，让您了解使用 Native Library Interop 的无限可能性！

请务必亲自查看 CommunityToolkit/Maui.NativeLibraryInterop。我很想看看您创建了哪些绑定，并听听您的使用体验！