通过

本机库互操作

  • 项目

概述

原生库互操作（以前称为“精简绑定”方法）指在 .NET MAUI 应用（包括适用于 Android 的 .NET、适用于 iOS 的 .NET 和适用于 Mac Catalyst 应用的 .NET）中访问本机 SDK 的模式。 思路是使用简化的 API 图面，对你有兴趣从 .NET 调用的本地 SDK 创建自己的抽象或精简“包装器”。 本机“包装器”库/框架项目在使用 Java/Kotlin 的 Android Studio 中和/或使用 Objective-C/Swift 的 Xcode 中创建。 当你只需要 SDK 的 API 图面的一小部分时，此方法特别有用（尽管它也同样适用于大型 API 图面使用情况）。

概念性概述：NativeLibraryInterop

了解何时及为什么使用本机库互操作

本机库互操作是一种非常有效的与本机库集成的方法（尽管它可能并不总是最适合你的项目）。 一般来说，如果你已经在维护绑定，并且可以放心地继续这样做，则无需改变方法。 对于需要广泛使用库的 API 的项目或对于支持 .NET MAUI 开发人员的供应商，传统绑定可能仍然更合适。 但是，本机库互操作提供了一种通常更容易理解、实现和维护的替代方案。

本机库互操作的一个主要优点是其对简单 API 图面的有效性。 当包装器仅涉及 .NET 支持的基元类型时，现有绑定工具可通过最少的手动干预生成可靠的定义，这通常是传统绑定所必需的。 这使得该过程变得简单明了，特别是因为包装器 API 实现通常遵循 SDK 文档，并且通常允许从供应商文档直接复制。

虽然初始设置可能更为复杂，但管理基础 SDK 的更新通常需要更少的工作。 更新通常仅涉及调整版本和重新生成项目。 即使 API 图面或 SDK 中发生了中断性变更，包装 API 图面和 .NET 应用程序的使用也更有可能保持稳定，与传统绑定相比，需要进行的调整更少。

总之，本机库互操作提供了以下几个优点：

  • 使用本机语言和工具简化以下 SDK 文档
  • 需要更少的手动干预来创建工作绑定
  • 使维护更轻松并降低必要更新的频率
  • 增强应用与基础 SDK 更改的隔离

尽管解析依赖项链（尤其是在 Android 上）可能需要与传统绑定类似的工作，但简化的实现和维护优势使得本机库互操作成为许多项目的一个有吸引力的选择。

了解 Maui.NativeLibraryInterop

创建和维护通过本机库互操作创建的绑定的一个显著挑战是手动合并本机项目、其本机依赖项、生成输出和 .NET 绑定库项目。 Maui.NativeLibraryInterop 针对你自己的应用需求，基于示例进行生成并自定义示例，从而帮助你快速启动该过程。

其中一部分包括通过 MSBuild 调用协调部分生成过程。 这可能包括：

  • 解析或下载本机 SDK 依赖项
  • 生成本机精简绑定项目及其依赖项
  • 将必要的本机项目移动到预期的工作目录
  • 生成绑定库项目的 API 定义

通过将 CommunityToolkit.Maui.NativeLibraryInterop.BuildTasks NuGet 包添加到绑定项目，绑定生成过程被扩展以获取和生成本机 SDK 依赖项：

<ItemGroup>
    <PackageReference Include="CommunityToolkit.Maui.NativeLibraryInterop.BuildTasks" Version="0.0.1-pre1" />
</ItemGroup>

Android 绑定项目将添加指向包含本机包装器 gradle 项目的根文件夹的 @(NLIGradleProjectReference) 项：

<ItemGroup>
    <NLIGradleProjectReference Include="../native" >
        <ModuleName>newbinding</ModuleName>
        <!-- Metadata applicable to @(AndroidLibrary) will be used if set, otherwise the following defaults will be used:
        <Bind>true</Bind>
        <Pack>true</Pack>
        -->
    </NLIGradleProjectReference>
</ItemGroup>

iOS 绑定项目将添加指向本机包装器 Xcode 项目的 @(NLIXcodeProjectReference) 项：

<ItemGroup>
    <NLIXcodeProjectReference Include="../native/NewBinding/NewBinding.xcodeproj">
        <SchemeName>NewBinding</SchemeName>
        <SharpieNamespace>NewBinding</SharpieNamespace>
        <SharpieBind>true</SharpieBind>
        <!-- Metadata applicable to @(NativeReference) will be used if set, otherwise the following defaults will be used:
        <Kind>Framework</Kind>
        <SmartLink>true</SmartLink>
        -->
    </NLIXcodeProjectReference>
</ItemGroup>

Android 绑定项目自动生成 API 定义，并考虑到任何可选的手动修改，例如通过 Metadata.xml 转换文件实现的修改。

概念概述：适用于 Android 的 NativeLibraryInterop

iOS 绑定库项目必须包含显式定义的 API。 为了帮助实现这一点，Objective-Sharpie 可在生成的本机框架上自动运行，以随之生成一个 API 定义文件 (ApiDefinition.cs)。 在创建和维护 iOS 绑定项目使用的 ApiDefintion.cs 文件时，这可充当一个有用的引用。

概念概述：适用于 iOS 的 NativeLibraryInterop

必要的本机依赖项嵌入到绑定程序集中。 当 .NET 项目添加对本机项目的引用时，本机依赖项自动包含在应用中。