Vincular uma biblioteca Java

A comunidade Android oferece muitas bibliotecas Java que pode querer usar na sua aplicação. Estas bibliotecas Java são frequentemente embaladas em . JAR (Java Archive) ou . AAR (Android Archive), mas podes empacotar um arquivo . JAR/. AAR numa Java Bindings Library para que a sua funcionalidade esteja disponível para .NET para aplicações Android. O objetivo da biblioteca Java Bindings é tornar as APIs no arquivo . JAR/. AAR disponível para código C# através de wrappers de código gerados automaticamente.

Walkthrough

Neste walkthrough, vamos associar a versão 3.1.0 do CircleImageView, uma biblioteca que apresenta uma imagem numa tela circular.

Do repositório Maven, descarregue circleimageview-3.1.0.aar localmente para ser vinculado.

Criação da biblioteca de vínculo

Primeiro, crie um novo projeto Bindings Library. Isto pode ser feito com o modelo de projeto "Android Java Binding Library" disponível no Visual Studio ou através da dotnet linha de comandos com:

dotnet new android-bindinglib

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

Tal como projetos ao estilo SDK .NET, os projetos de binding .NET para Android incluem automaticamente quaisquer ficheiros .JAR/.AAR no diretório do projeto como fichiero do tipo AndroidLibrary, pelo que não é necessária configuração adicional.

Agora constrói o projeto usando o comando Build do Visual Studio, ou a partir da linha de comandos:

dotnet build

Esta biblioteca Java já foi encadernada e pronta para ser referenciada por um projeto de aplicação .NET para Android ou publicada no NuGet para consumo público.

Opções adicionais

Saltar fixações geridas

Por defeito, serão criados bindings de C# para qualquer ficheiro .JAR/.AAR colocado no projeto. No entanto, os bindings em C# podem ser complicados de criar e não são necessários se não pretender chamar a API Java a partir do C#.

Isto é especialmente verdade quando a biblioteca Java é simplesmente uma dependência de outra biblioteca Java e não precisa de ser chamada diretamente de C#. Neste caso, o Bind="false" atributo pode ser usado apenas para incluir a dependência do Java, mas sem a vincular.

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

Note que, se usar importações automáticas, terá de usar Update para alterar o ficheiro importado automaticamente em vez de adicionar uma cópia adicional com Include.

Dependências de Java

Uma biblioteca Java pode depender de outras bibliotecas Java que terão de ser empacotadas com a sua aplicação para que esta funcione. Esta informação é tradicionalmente fornecida num ficheiro .POM, e é sua responsabilidade garantir que quaisquer dependências necessárias são devidamente referenciadas, normalmente através de um pacote NuGet ou agrupando os ficheiros .JAR/.AAR necessários no seu projeto.

No .NET 9, foi adicionada a funcionalidade de Verificação de Dependências de Java. Ao fornecer o .POM, a ferramenta de ligação pode ajudar a garantir que cumpriu com todas as dependências de Java necessárias.

Para ativar a Verificação de Dependências Java no nosso guia, certifique-se de que está a usar o .NET 9+ e que o seu projeto tenha como alvo net9.0-android ou superior.

Do repositório Maven, descarrega circleimageview-3.1.0.pom localmente e coloca-o na pasta do teu projeto. Note que . Os ficheiros POM não serão detetados automaticamente porque precisam de ser associados ao arquivo correto . JAR/. AAR.

Atualize o AndroidLibrary importado automaticamente para especificar a localização do ficheiro .POM com o atributo Manifest. Adicionalmente, 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 tem quaisquer dependências de Java, mas se tivesse e não fossem cumpridas, seria emitido um erro como este:

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 a configuração da Verificação de Dependências Java e como satisfazer dependências podem ser encontradas na documentação.

Passos seguintes

• Personalização de Bindings com Metadados - A biblioteca Java vinculada no passo a passo é trivial e as ferramentas de binding conseguiram convertê-la totalmente de forma automática para uma API C#. Infelizmente, isso muitas vezes não acontece e haverá frequentemente erros de compilação. Estes erros devem ser corrigidos com "metadados" para instruir manualmente a ferramenta de binding como resolver diferenças entre as linguagens Java e C#.

• Alteração de Namespaces - Os tipos no tutorial acabam por ficar no namespace DE.Hdodenhof.Circleimageview.NET. Os nomes dos pacotes Java tendem a ser mais verbosos do que os namespaces .NET e pode ser mais desejável alterá-los, por exemplo, para CircleImageViewLibrary usar um AndroidNamespaceReplacement:

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