Interoperabilidad con bibliotecas nativas

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 vuestra propia abstracción o un "envoltorio" ligero con una interfaz de API simplificada para los SDK nativos que os interese invocar desde .NET. Los proyectos nativos de biblioteca o framework de tipo "envoltorio" se crean en Android Studio con Java/Kotlin y/o en Xcode con 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 vinculaciones y se siente cómodo haciéndolo, no es necesario cambiar de enfoque. 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 que rompan la compatibilidad en las interfaces de las API o de los SDK, es más probable que la interfaz de la API contenedora y el uso que hace la aplicación .NET permanezcan estables, por lo que requerirán menos ajustes que 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
• Requiere menos intervención manual para crear vinculaciones funcionales
• 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
• Compilar el proyecto de enlace nativo ligero 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

Los proyectos de enlace de Android agregarán un @(AndroidGradleProject) elemento que apunte a un archivo build.gradle que se usará para compilar el proyecto de gradle:

<ItemGroup>
    <AndroidGradleProject Include="../native/build.gradle.kts" >
        <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>
        -->
    </AndroidGradleProject>
</ItemGroup>

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

<ItemGroup>
    <XcodeProject Include="../native/NewBinding/NewBinding.xcodeproj">
        <SchemeName>NewBinding</SchemeName>
        <!-- Metadata applicable to @(NativeReference) will be used if set, otherwise the following defaults will be used:
        <Kind>Framework</Kind>
        <SmartLink>true</SmartLink>
        -->
    </XcodeProject>
</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 debe ejecutarse en el marco nativo resultante para generar un archivo de definición de API (ApiDefinition.cs) junto con él. Esto sirve como referencia útil al crear y mantener el archivo ApiDefinition.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.