Interoperabilidad de biblioteca nativa

Información general

La interoperabilidad de biblioteca nativa (anteriormente denominada enfoque "Slim Binding"), hace referencia a un patrón para acceder a SDK nativos en aplicaciones de .NET MAUI, como .NET para Android, .NET para iOS y .NET para aplicaciones Mac Catalyst. La idea es crear su propia abstracción o "contenedor" fino con una superficie de API simplificada para los SDK nativos que le interesa llamar desde .NET. Los proyectos de "contenedor" de biblioteca o marco de trabajo nativos se crean en Android Studio mediante Java/Kotlin o Xcode mediante Objective-C/Swift. Este enfoque es especialmente beneficioso cuando solo se necesita un pequeño segmento de la superficie de la API del SDK, aunque también funciona bien para un uso de superficie de API mayor.

Descripción de cuándo y por qué usar la interoperabilidad de biblioteca nativa

La interoperabilidad de biblioteca nativa es un enfoque muy eficaz para la integración con bibliotecas nativas, aunque podría no siempre ser la mejor opción para su proyecto. Por lo general, si ya mantiene enlaces y se siente cómodo, no es necesario cambiar los enfoques. En el caso de los proyectos que requieren un uso extensivo de la API de una biblioteca o para proveedores que admiten desarrolladores de .NET MAUI, es posible que los enlaces tradicionales sigan siendo más adecuados. Sin embargo, la interoperabilidad de biblioteca nativa ofrece una alternativa que a menudo es más fácil de entender, implementar y mantener.

Una ventaja clave de la interoperabilidad de la biblioteca nativa es su eficacia con las superficies de API sencillas. Cuando los contenedores solo incluyen tipos primitivos admitidos por .NET, las herramientas de enlace existentes pueden generar definiciones confiables con una intervención manual mínima, que a menudo es necesaria para los enlaces tradicionales. Esto hace que el proceso sea sencillo, especialmente porque la implementación del contenedor de API suele seguir la documentación del SDK y, a menudo, permite la copia directa desde la documentación del proveedor.

Aunque la configuración inicial puede ser más compleja, la administración de actualizaciones de los SDK subyacentes suele requerir menos esfuerzo. A menudo, las actualizaciones implican simplemente el ajuste de la versión y la recompilación del proyecto. Incluso si se producen cambios importantes en las superficies de API o SDK, es más probable que la superficie de contenedor de API y el uso de la aplicación de .NET permanezcan estables, lo que requerirá menos ajustes en comparación con los enlaces tradicionales.

En resumen, la interoperabilidad de biblioteca nativa proporciona varias ventajas:

• Simplifica el uso de la documentación del SDK mediante lenguajes nativos y herramientas
• Se requiere menos intervención manual para crear enlaces de trabajo
• Facilita el mantenimiento y reduce la frecuencia de las actualizaciones necesarias
• Mejora el aislamiento de la aplicación de los cambios en los SDK subyacentes

Aunque la resolución de cadenas de dependencias (especialmente en Android) puede requerir un esfuerzo similar al de los enlaces tradicionales, las ventajas de implementación y mantenimiento simplificadas hacen que la interoperabilidad de biblioteca nativa sea una opción atractiva para muchos proyectos.

Introducción a Maui.NativeLibraryInterop

Un desafío importante en la creación y el mantenimiento de enlaces creados a través de la interoperabilidad de biblioteca nativa es la fusión manual de los proyectos nativos, sus dependencias nativas, las salidas de compilación y el proyecto de biblioteca de enlaces de .NET. Maui.NativeLibraryInterop le ayuda a iniciar el proceso mediante la compilación y personalización de los ejemplos para las necesidades de su propia aplicación.

Parte de esto incluye la orquestación de partes del proceso de compilación a través de invocaciones de MSBuild. Esto puede incluir:

• Resolver o descargar dependencias nativas del SDK
• Crear el proyecto de "Slim Binding" nativo y sus dependencias
• Mover los artefactos nativos necesarios al directorio de trabajo esperado
• Generar la definición de API para el proyecto de biblioteca de enlaces

El proceso de compilación de enlace se extiende para obtener y compilar dependencias nativas del SDK agregando el paquete NuGet CommunityToolkit.Maui.NativeLibraryInterop.BuildTasks al proyecto de enlace:

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

Los proyectos de enlace de Android agregarán un elemento @(NLIGradleProjectReference) que apunte a la carpeta raíz que contiene el proyecto de Gradle de contenedor nativo:

<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>

Los proyectos de enlace de iOS agregarán un elemento @(NLIXcodeProjectReference) que apunte al proyecto de Xcode de contenedor nativo:

<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>

Los proyectos de enlace de Android generan automáticamente la definición de API teniendo en cuenta las modificaciones manuales opcionales, como las implementadas a través del archivo de transformación Metadata.xml.

Un proyecto de biblioteca de enlaces de iOS debe incluir una API definida explícitamente. Para ayudar con esto, Objective-Sharpie se puede ejecutar automáticamente en el marco nativo resultante para generar un archivo de definición de API (ApiDefinition.cs) junto con él. Esto puede servir como referencia útil al crear y mantener el archivo ApiDefintion.cs usado por el proyecto de enlace de iOS.

Las dependencias nativas necesarias se insertan en el ensamblado de enlace. Cuando un proyecto de .NET agrega una referencia al proyecto nativo, las dependencias nativas se incluyen automáticamente en la aplicación.