Native Library Interop

Visão geral

Native Library Interop (anteriormente chamada de abordagem "Slim Binding"), refere-se a um padrão para acessar SDKs nativos em aplicativos .NET MAUI, incluindo .NET para Android, .NET para iOS e .NET para aplicativos Mac Catalyst. A ideia é criar sua própria abstração ou "wrapper" fino com uma superfície de API simplificada para os SDKs nativos que você está interessado em chamar do .NET. Os projetos nativos de biblioteca/estrutura "wrapper" são criados no Android Studio usando Java/Kotlin e/ou Xcode usando Objective-C/Swift. Essa abordagem é especialmente benéfica quando você precisa apenas de uma pequena fatia da superfície de API do SDK, embora também funcione bem para uso de superfície de API maior.

Noções básicas sobre quando e por que usar a Interoperabilidade de Biblioteca Nativa

A Interoperabilidade de Biblioteca Nativa é uma abordagem muito eficaz para a integração com bibliotecas nativas, embora nem sempre seja a melhor opção para seu projeto. Em geral, se você já estiver mantendo associações e estiver confortável em continuar a fazê-lo, não será necessário alterar as abordagens. Para projetos que exigem uso extensivo da API de uma biblioteca ou para fornecedores que dão suporte a desenvolvedores do .NET MAUI, as associações tradicionais ainda podem ser mais adequadas. No entanto, a Interoperabilidade de Biblioteca Nativa oferece uma alternativa que geralmente é mais fácil de entender, implementar e manter.

Um dos principais benefícios da Interoperabilidade de Biblioteca Nativa é sua eficácia com superfícies de API simples. Quando os wrappers envolvem apenas tipos primitivos aos quais o .NET dá suporte, as ferramentas de associação existentes podem gerar definições confiáveis com intervenção manual mínima, o que geralmente é necessário para associações tradicionais. Isso torna o processo simples, especialmente porque a implementação da API de wrapper normalmente segue a documentação do SDK e geralmente permite a cópia direta da documentação do fornecedor.

Embora a configuração inicial possa ser mais complexa, o gerenciamento de atualizações para SDKs subjacentes geralmente requer menos esforço. As atualizações geralmente envolvem ajustar a versão e recriar o projeto. Mesmo que ocorram alterações significativas nas superfícies de API ou SDKs, a superfície da API do wrapper e o uso do aplicativo .NET são mais propensos a permanecer estáveis, exigindo menos ajustes em comparação com as associações tradicionais.

Em resumo, a Interoperabilidade de Biblioteca Nativa oferece vários benefícios:

• Simplifica a documentação do SDK a seguir com ferramentas e idiomas nativos
• Requer menos intervenção manual para criar associações de trabalho
• Facilita a manutenção e reduz a frequência das atualizações necessárias
• Aprimora o isolamento do aplicativo de alterações em SDKs subjacentes

Embora a resolução de cadeias de dependência (particularmente no Android) possa exigir esforço semelhante às associações tradicionais, as vantagens simplificadas de implementação e manutenção tornam a Interoperabilidade de Biblioteca Nativa uma opção atraente para muitos projetos.

Noções básicas sobre Maui.NativeLibraryInterop

Um desafio notável com a criação e manutenção de associações criadas por meio da Interoperabilidade de Biblioteca Nativa é unir manualmente os projetos nativos, suas dependências nativas, saídas de build e o projeto de biblioteca de associação do .NET. O Maui.NativeLibraryInterop ajuda você a iniciar o processo criando e personalizando os exemplos para as necessidades do seu próprio aplicativo.

Parte disso inclui a orquestração de partes do processo de build por meio de invocações do MSBuild. São elas:

• Resolvendo ou baixando dependências nativas do SDK
• Criando o projeto de associação fina nativa e suas dependências
• Movendo os artefatos nativos necessários para o diretório de trabalho esperado
• Gerando a definição de API para o projeto de biblioteca de associação

O processo de build de associação é estendido para obter e criar dependências nativas do SDK adicionando o pacote NuGet CommunityToolkit.Maui.NativeLibraryInterop.BuildTasks ao seu projeto de associação:

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

Os projetos de associação do Android adicionarão um item @(NLIGradleProjectReference) que aponta para a pasta raiz que contém o projeto de gradle de wrapper 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>

Os projetos de associação do iOS adicionarão um item @(NLIXcodeProjectReference) que aponta para o projeto Xcode do wrapper 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>

Os projetos de associação do Android geram a definição de API automaticamente levando em conta as modificações manuais opcionais, como as implementadas por meio do arquivo de transformação Metadata.xml.

Um projeto de biblioteca de associação do iOS deve incluir uma API definida explicitamente. Para ajudar com isso, Objective-Sharpie pode ser executado automaticamente na estrutura nativa resultante para produzir um arquivo de definição de API (ApiDefinition.cs) ao lado dele. Isso pode servir como uma referência útil ao criar e manter o arquivo de ApiDefintion.cs usado pelo projeto de associação do iOS.

As dependências nativas necessárias são inseridas no assembly de associação. Quando um projeto .NET adiciona uma referência ao projeto nativo, as dependências nativas são incluídas no aplicativo automaticamente.