Vinculando uma biblioteca Java

A comunidade Android oferece muitas bibliotecas Java que você pode querer usar em seu aplicativo. Essas bibliotecas Java geralmente são empacotadas nos formatos .JAR (Java Archive) ou .AAR (Android Archive), mas você pode empacotar um .JAR/.AAR em uma Biblioteca de Associações Java para que sua funcionalidade esteja disponível para aplicativos .NET para Android. O objetivo da biblioteca Java Bindings é tornar as APIs nos arquivos .JAR/.AAR disponíveis para o código C# por meio de wrappers de código gerados automaticamente.

Passo a passo

Neste passo a passo, vamos associar a versão 3.1.0 de CircleImageView, uma biblioteca que exibe uma imagem em uma tela circular.

No repositório Maven, faça o download circleimageview-3.1.0.aar localmente para ser vinculado.

Criando a biblioteca de vinculações

Primeiro, crie um novo projeto de Biblioteca de Bindings. Isso pode ser feito com o modelo de projeto "Android Java Binding Library" disponível no Visual Studio ou por meio da linha de dotnet comando com:

dotnet new android-bindinglib

Copie o circleimageview-3.1.0.aar arquivo para o diretório do projeto.

Assim como projetos no estilo do SDK do .NET, os projetos de associação do .NET para Android incluem automaticamente quaisquer arquivos .JAR/.AAR no diretório do projeto como um arquivo do tipo AndroidLibrary, portanto, nenhuma configuração adicional é necessária.

Agora compile o projeto usando o comando Build do Visual Studio ou na linha de comando:

dotnet build

Esta biblioteca Java foi vinculada e agora está pronta para ser referenciada por um projeto .NET para aplicativo Android ou publicada no NuGet para uso público.

Opções adicionais

Ignorar associações gerenciadas

Por padrão, as vinculações C# serão criadas para qualquer .JAR/.AAR colocado no projeto. No entanto, as associações C# podem ser difíceis de criar e não são necessárias se você não pretende chamar a API Java do C#.

Esse é especialmente o caso quando a biblioteca Java é simplesmente uma dependência de outra biblioteca Java e não precisa ser chamada diretamente do C#. Nesse caso, o Bind="false" atributo pode ser usado apenas para incluir a dependência Java, mas não para vinculá-la.

<ItemGroup>
  <AndroidLibrary Update="circleimageview-3.1.0.aar" Bind="false" />
</ItemGroup>

Observe que, se estiver usando importações automáticas, você precisará usar Update para alterar o arquivo importado automaticamente em vez de adicionar uma cópia adicional com Include.

Dependências Java

Uma biblioteca Java pode depender de outras bibliotecas Java que precisarão ser empacotadas com seu aplicativo para que seu aplicativo funcione. Essas informações são tradicionalmente fornecidas em um arquivo . POM, e é sua responsabilidade garantir que todas as dependências necessárias sejam referenciadas corretamente, geralmente por meio de um pacote NuGet ou agrupando o arquivo . JARRO/. AAR em seu projeto.

No .NET 9, o recurso Verificação de Dependência Java foi adicionado. Ao fornecer o . POM, o conjunto de ferramentas de vinculação pode ajudar a garantir que você atenda a todas as dependências Java necessárias.

Para habilitar a Verificação de Dependência Java para nosso passo a passo, verifique se você está usando o .NET 9+ e se o seu projeto tem como alvo net9.0-android ou superior.

No repositório Maven, baixe-o circleimageview-3.1.0.pom localmente e coloque-o na pasta do seu projeto. Observe que os arquivos .POM não serão detectados automaticamente porque precisam ser associados ao arquivo correto .JAR/.AAR.

Atualize o arquivo importado AndroidLibrary automaticamente para especificar o local do arquivo . POM com Manifest atributo. Além disso, especifique o JavaArtifact e JavaVersion da biblioteca Java:

<!-- JavaArtifact format is {GroupId}:{ArtifactId} -->
<ItemGroup>
  <AndroidLibrary
    Update="circleimageview-3.1.0.aar"
    Manifest="circleimageview-3.1.0.pom"
    JavaArtifact="de.hdodenhof:circleimageview"
    JavaVersion="3.1.0" />
</ItemGroup>

Esta biblioteca é trivial e não possui dependências do Java, mas se o fizesse e não fossem atendidas, um erro como este seria emitido:

error XA4241: Java dependency 'androidx.collection:collection:1.0.0' is not satisfied.
error XA4242: Java dependency 'org.jetbrains.kotlin:kotlin-stdlib:1.9.0' is not satisfied. Microsoft maintains the NuGet package 'Xamarin.Kotlin.StdLib' that could fulfill this dependency.

Informações adicionais sobre como configurar a Verificação de Dependência Java e como satisfazer dependências podem ser encontradas na documentação.

Próximas etapas

• Personalizando associações com metadados – a biblioteca Java associada no passo a passo é trivial e as ferramentas de associação foram capazes de convertê-la automaticamente em uma API C#. Infelizmente, muitas vezes não é esse o caso e muitas vezes haverá erros de compilação. Esses erros devem ser corrigidos com "metadados" para instruir manualmente as ferramentas de associação sobre como resolver as diferenças entre as linguagens Java e C#.

• Alterando namespaces - Os tipos no passo a passo terminam no namespace DE.Hdodenhof.Circleimageview do .NET. Os nomes de pacotes Java tendem a ser mais detalhados do que os namespaces .NET e pode ser mais desejável alterá-lo, por exemplo, para CircleImageViewLibrary usando um AndroidNamespaceReplacement:

<ItemGroup>
  <AndroidNamespaceReplacement Include='DE.Hdodenhof.Circleimageview' Replacement='CircleImageViewLibrary' />
</ItemGroup>