itens de build

  • Artigo

Os itens de compilação controlam como um aplicativo .NET para Android ou projeto de biblioteca é criado.

Eles são especificados no arquivo de projeto, por exemplo , MyApp.csproj, em um MSBuild ItemGroup.

Observação

No .NET para Android, tecnicamente não há distinção entre um aplicativo e um projeto de associações, portanto, os itens de build funcionarão em ambos. Na prática, é altamente recomendável criar projetos separados de aplicativos e associações. Os itens de build usados principalmente em projetos de associações estão documentados no guia de referência de itens de projeto de associações do MSBuild.

AndroidAdditionalJavaManifest

<AndroidAdditionalJavaManifest> é usado em conjunto com a Resolução de Dependência Java para especificar arquivos POM adicionais que serão necessários para verificar as dependências. Geralmente, são arquivos POM pai ou importados referenciados pelo arquivo POM de uma biblioteca Java.

<ItemGroup>
  <AndroidAdditionalJavaManifest Include="mylib-parent.pom" JavaArtifact="com.example:mylib-parent" JavaVersion="1.0.0" />
</ItemGroup>

Os seguintes metadados do MSBuild são necessários:

  • %(JavaArtifact): O grupo e o ID do artefato da biblioteca Java correspondente ao arquivo POM especificado no formato {GroupId}:{ArtifactId}.
  • %(JavaVersion): A versão da biblioteca Java que corresponde ao arquivo POM especificado.

Consulte a documentação da Resolução de Dependência Java para obter mais detalhes.

Essa ação de build foi introduzida no .NET 9.

Ativo Android

Suporta Android Assets, arquivos que seriam incluídos na assets pasta em um projeto Java Android.

A partir do .NET 9, a @(AndroidAsset) ação de build também dá suporte a metadados adicionais para gerar Asset Packs. Os %(AndroidAsset.AssetPack) metadados podem ser usados para gerar automaticamente um pacote de ativos com esse nome. Esse recurso só é suportado quando o $(AndroidPackageFormat) é definido como .aab. O exemplo a seguir colocará movie2.mp4 e movie3.mp4 em pacotes de ativos separados.

<ItemGroup>
   <AndroidAsset Update="Asset/movie.mp4" />
   <AndroidAsset Update="Asset/movie2.mp4" AssetPack="assets1" />
   <AndroidAsset Update="Asset/movie3.mp4" AssetPack="assets2" />
</ItemGroup>

Esse recurso pode ser usado para incluir arquivos grandes em seu aplicativo que normalmente excederiam os limites máximos de tamanho de pacote do Google Play.

Se você tiver um grande número de ativos, pode ser mais eficiente usar o base pacote de ativos. Nesse cenário, você atualiza TODOS os ativos para estarem em um único pacote de ativos e, em seguida, usa os AssetPack="base" metadados para declarar quais ativos específicos terminam no arquivo aab base. Com isso, você pode usar curingas para mover a maioria dos ativos para o pacote de ativos.

<ItemGroup>
   <AndroidAsset Update="Assets/*" AssetPack="assets1" />
   <AndroidAsset Update="Assets/movie.mp4" AssetPack="base" />
   <AndroidAsset Update="Assets/some.png" AssetPack="base" />
</ItemGroup>

Neste exemplo, movie.mp4 e some.png terminará no base arquivo aab, enquanto todos os outros ativos terminarão no assets1 pacote de ativos.

Os metadados adicionais só têm suporte no .NET para Android 9 e superior.

AndroidAarLibrary

A ação Compilar AndroidAarLibrary de deve ser usada para referenciar .aar arquivos diretamente. Essa ação do build será mais usada pelos componentes do Xamarin. Ou seja, incluir referências a .aar arquivos necessários para que o Google Play e outros serviços funcionem.

Os arquivos com essa ação Compilar serão tratados de maneira semelhante aos recursos incorporados encontrados nos projetos da Biblioteca. O .aar será extraído para o diretório intermediário. Em seguida, todos os ativos, recursos e .jar arquivos serão incluídos nos grupos de itens apropriados.

AndroidAotProfile

Usado para fornecer um perfil AOT, para uso com AOT guiado por perfil.

Ele também pode ser usado no Visual Studio definindo a AndroidAotProfile ação de build como um arquivo que contém um perfil AOT.

AndroidAppBundleMetaDataFile

Especifica um arquivo que será incluído como metadados no Android App Bundle. O formato do valor do sinalizador é <bundle-path>:<physical-file> onde bundle-path indica o local do arquivo dentro do diretório de metadados do App Bundle e physical-file é um arquivo existente que contém os dados brutos a serem armazenados.

<ItemGroup>
  <AndroidAppBundleMetaDataFile
    Include="com.android.tools.build.obfuscation/proguard.map:$(OutputPath)mapping.txt"
  />
</ItemGroup>

Consulte a documentação do bundletool para obter mais detalhes.

AndroidBoundLayout

Indica que o arquivo de layout deve ter code-behind gerado para ele caso a $(AndroidGenerateLayoutBindings) propriedade seja definida como false. Em todos os outros aspectos, é idêntico a AndroidResource.

Essa ação pode ser usada apenas com arquivos de layout:

<AndroidBoundLayout Include="Resources\layout\Main.axml" />

AndroidEnvironment

Arquivos com uma ação de build AndroidEnvironment são usados para inicializar variáveis de ambiente e propriedades do sistema durante a inicialização do processo. A ação de build AndroidEnvironment pode ser aplicada a vários arquivos, e eles serão avaliados sem nenhuma ordem específica (então não especifique a mesma propriedade de sistema ou variável de ambiente em vários arquivos).

Projeto AndroidGradle

<AndroidGradleProject> pode ser usado para criar e consumir as saídas de projetos do Android Gradle criados no Android Studio ou em outro lugar.

Os Include metadados devem apontar para o nível build.gradle superior ou build.gradle.kts arquivo que será usado para construir o projeto. Isso será encontrado no diretório raiz do seu projeto Gradle, que também deve conter gradlew scripts wrapper.

<ItemGroup>
  <AndroidGradleProject Include="path/to/project/build.gradle.kts" ModuleName="mylibrary" />
</ItemGroup>

Há suporte para os seguintes metadados do MSBuild:

  • %(Configuration): O nome da configuração a ser usada para compilar ou montar o projeto ou o módulo de projeto especificado. O valor padrão é Release.
  • %(ModuleName): o nome do módulo ou subprojeto que deve ser criado. O valor padrão é vazio.
  • %(OutputPath): pode ser definido para substituir o caminho de saída do build do projeto Gradle. O valor padrão é $(IntermediateOutputPath)gradle/%(ModuleName)%(Configuration)-{Hash}.
  • %(CreateAndroidLibrary): Os arquivos AAR de saída serão adicionados como um AndroidLibrary ao projeto. Os metadados suportados por <AndroidLibrary> like %(Bind) ou %(Pack) serão encaminhados se definidos. O valor padrão é true.

Essa ação de build foi introduzida no .NET 9.

AndroidJavaLibrary

Os arquivos com uma ação Build de AndroidJavaLibrary são Java Archives ( .jar arquivos) que serão incluídos no pacote final do Android.

AndroidIgnoredJavaDependency

<AndroidIgnoredJavaDependency> é usado em conjunto com a Resolução de Dependência Java.

Ele é usado para especificar uma dependência Java que deve ser ignorada. Isso pode ser usado se uma dependência for atendida de uma forma que a resolução de dependência Java não possa detectar.

<!-- Include format is {GroupId}:{ArtifactId} -->
<ItemGroup>
  <AndroidIgnoredJavaDependency Include="com.google.errorprone:error_prone_annotations" Version="2.15.0" />
</ItemGroup>

Os seguintes metadados do MSBuild são necessários:

  • %(Version): A versão da biblioteca Java correspondente ao arquivo %(Include).

Consulte a documentação da Resolução de Dependência Java para obter mais detalhes.

Essa ação de build foi introduzida no .NET 9.

AndroidJavaSource

Os arquivos com uma ação Build de AndroidJavaSource são código-fonte Java que serão incluídos no pacote final do Android.

A partir do .NET 7, todos os **\*.java arquivos no diretório do projeto têm automaticamente uma ação Build de e serão associados antes do build do AndroidJavaSourceAssembly. Permite que o código C# use facilmente tipos e membros presentes nos **\*.java arquivos.

Defina %(AndroidJavaSource.Bind) como False para desabilitar esse comportamento.

Biblioteca Android

AndroidLibrary é uma nova ação de compilação para simplificar como .jar e .aar os arquivos são incluídos nos projetos.

Qualquer projeto pode especificar:

<ItemGroup>
  <AndroidLibrary Include="foo.jar" />
  <AndroidLibrary Include="bar.aar" />
</ItemGroup>

O resultado do snippet de código acima tem um efeito diferente para cada tipo de projeto do .NET para Android:

Essa simplificação significa que você pode usar AndroidLibrary em qualquer lugar.

AndroidLintConfig

A ação Build 'AndroidLintConfig' deve ser usada em conjunto com o Propriedade $(AndroidLintEnabled). Os arquivos com essa ação de build serão mesclados e passados para as ferramentas lint do Android. Eles devem ser arquivos XML contendo informações sobre testes a serem habilitados e desabilitados.

Confira a documentação do lint para obter mais detalhes.

AndroidManifestOverlay

A AndroidManifestOverlay ação de compilação pode ser usada para fornecer AndroidManifest.xml arquivos para a ferramenta Manifest Merge . Os arquivos com essa ação de build serão passados para a Fusão de Manifesto junto com o arquivo principal AndroidManifest.xml e os arquivos de manifesto das referências. Eles serão então mesclados no manifesto final.

Você pode usar essa ação de compilação para fornecer alterações e configurações ao seu aplicativo, dependendo da configuração de compilação. Por exemplo, se você precisar ter uma permissão específica somente durante a depuração, poderá usar a sobreposição para injetar essa permissão durante a depuração. Por exemplo, considerando o seguinte conteúdo de arquivo de sobreposição:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <uses-permission android:name="android.permission.CAMERA" />
</manifest>

Você pode usar o seguinte para adicionar uma sobreposição de manifesto para um build de depuração:

<ItemGroup>
  <AndroidManifestOverlay Include="DebugPermissions.xml" Condition=" '$(Configuration)' == 'Debug' " />
</ItemGroup>

AndroidInstallModules

Especifica os módulos que são instalados pelo comando bundletool ao instalar pacotes de aplicativos.

AndroidMavenBiblioteca

<AndroidMavenLibrary> permite que um artefato Maven seja especificado, que será baixado automaticamente e adicionado a um projeto de associação do .NET para Android. Isso pode ser útil para simplificar a manutenção de associações do .NET para Android para artefatos hospedados no Maven.

<!-- Include format is {GroupId}:{ArtifactId} -->
<ItemGroup>
  <AndroidMavenLibrary Include="com.squareup.okhttp3:okhttp" Version="4.9.3" />
</ItemGroup>

Há suporte para os seguintes metadados do MSBuild:

  • %(Version): Versão necessária da biblioteca Java referenciada por %(Include).
  • %(Repository): Repositório Maven opcional a ser usado. Os valores suportados são Central (padrão), Google, ou uma https URL para um repositório Maven.

O <AndroidMavenLibrary> item é traduzido para AndroidLibrary, portanto, todos os metadados suportados por <AndroidLibrary> like %(Bind) ou %(Pack) também são suportados.

Consulte a documentação do AndroidMavenLibrary para obter mais detalhes.

Essa ação de build foi introduzida no .NET 9.

AndroidNativeLibrary

Bibliotecas nativas são adicionadas ao build definindo-se as ações de build delas para AndroidNativeLibrary.

Observe que, como o Android é compatível com várias interfaces binárias de aplicativos (ABIs), o sistema de compilação deve conhecer a ABI para a qual a biblioteca nativa foi criada. Há duas maneiras de especificar a ABI:

  1. "Detecção" de caminho.
  2. Usando os metadados do %(Abi) item.

Com a detecção de caminho, o nome do diretório pai da biblioteca nativa é usado para especificar a ABI usada como destino pela biblioteca. Portanto, se você adicionar lib/armeabi-v7a/libfoo.so ao build, em a ABI será "detectada" como armeabi-v7a.

Nome do atributo do item

Abi – Especifica a ABI da biblioteca nativa.

<ItemGroup>
  <AndroidNativeLibrary Include="path/to/libfoo.so">
    <Abi>armeabi-v7a</Abi>
  </AndroidNativeLibrary>
</ItemGroup>

AndroidPackagingOptionsExcluir

Um conjunto de itens compatíveis com glob de arquivo que permitirá que os itens sejam excluídos do pacote final. Os valores padrão são os seguintes

<ItemGroup>
	<AndroidPackagingOptionsExclude Include="DebugProbesKt.bin" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('*.kotlin_*')" />
</ItemGroup>

Os itens podem usar caracteres de blob de arquivo para curingas, como * e ?. No entanto, esses itens DEVEM ser codificados por URL ou usar $([MSBuild]::Escape('')). Isso ocorre para que o MSBuild não tente interpretá-los como curingas de arquivo reais.

Por exemplo

<ItemGroup>
	<AndroidPackagingOptionsExclude Include="%2A.foo_%2A" />
  <AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('*.foo')" />
</ItemGroup>

NOTA: *, ? e . será substituído na BuildApk tarefa pelos globs de arquivo apropriados.

Se o glob de arquivo padrão for muito restritivo, você poderá removê-lo adicionando o seguinte ao seu csproj

<ItemGroup>
	<AndroidPackagingOptionsExclude Remove="$([MSBuild]::Escape('*.kotlin_*')" />
</ItemGroup>

Adicionado no .NET 7.

AndroidPackagingOptionsInclude

Um conjunto de itens compatíveis com file glob que permitirá que os itens sejam incluídos no pacote final. Os valores padrão são os seguintes

<ItemGroup>
	<AndroidPackagingOptionsInclude Include="$([MSBuild]::Escape('*.kotlin_builtins')" />
</ItemGroup>

Os itens podem usar caracteres de blob de arquivo para curingas, como * e ?. No entanto, esses itens DEVEM usar a codificação de URL ou '$([MSBuild]::Escape(''))'. Isso ocorre para que o MSBuild não tente interpretá-los como curingas de arquivo reais. Por exemplo

<ItemGroup>
	<AndroidPackagingOptionsInclude Include="%2A.foo_%2A" />
  <AndroidPackagingOptionsInclude Include="$([MSBuild]::Escape('*.foo')" />
</ItemGroup>

NOTA: *, ? e . será substituído na BuildApk tarefa pelos globs de arquivo apropriados.

Adicionado no .NET 9.

AndroidResource

Todos os arquivos com uma ação de build AndroidResource são compilados em recursos do Android durante o processo de build e tornados acessíveis por meio de $(AndroidResgenFile).

<ItemGroup>
  <AndroidResource Include="Resources\values\strings.xml" />
</ItemGroup>

Usuários mais avançados talvez queiram usar diferentes recursos em configurações diferentes, mas com o mesmo caminho efetivo. Isso pode ser alcançado tendo vários diretórios do recurso e tendo arquivos com os mesmos caminhos relativos dentro desses diferentes diretórios, além de usar condições do MSBuild para incluir condicionalmente arquivos diferentes em configurações diferentes. Por exemplo:

<ItemGroup Condition=" '$(Configuration)' != 'Debug' ">
  <AndroidResource Include="Resources\values\strings.xml" />
</ItemGroup>
<ItemGroup  Condition=" '$(Configuration)' == 'Debug' ">
  <AndroidResource Include="Resources-Debug\values\strings.xml"/>
</ItemGroup>
<PropertyGroup>
  <MonoAndroidResourcePrefix>Resources;Resources-Debug</MonoAndroidResourcePrefix>
</PropertyGroup>

LogicalName – Especifica o caminho do recurso explicitamente. Permite arquivos de "aliasing" para que eles estejam disponíveis como vários nomes de recursos distintos.

<ItemGroup Condition="'$(Configuration)'!='Debug'">
  <AndroidResource Include="Resources/values/strings.xml"/>
</ItemGroup>
<ItemGroup Condition="'$(Configuration)'=='Debug'">
  <AndroidResource Include="Resources-Debug/values/strings.xml">
    <LogicalName>values/strings.xml</LogicalName>
  </AndroidResource>
</ItemGroup>

Sumário

A ação de build Content normal não é compatível (pois ainda não descobrimos como dar suporte a ela sem uma etapa de primeira execução de custo possivelmente alto).

A tentativa de usar a @(Content) ação Build resultará em um aviso XA0101 .

Jarro incorporado

Em um projeto de associação do .NET para Android, a ação de build EmbeddedJar associa a biblioteca Java/Kotlin e insere o .jar arquivo na biblioteca. Quando um projeto de aplicativo .NET para Android consome a biblioteca, ele tem acesso às APIs Java/Kotlin do C#, além de incluir o código Java/Kotlin no aplicativo Android final.

Em vez disso, você deve usar a ação de compilação AndroidLibrary como uma alternativa, como:

<Project>
  <ItemGroup>
    <AndroidLibrary Include="Library.jar" />
  </ItemGroup>
</Project>

Biblioteca Nativa Incorporada

Em uma biblioteca de classes do .NET para Android ou em um projeto de associação Java, a ação de build EmbeddedNativeLibrary agrupa uma biblioteca nativa, como lib/armeabi-v7a/libfoo.so na biblioteca. Quando um aplicativo .NET para Android consome a biblioteca, o libfoo.so arquivo será incluído no aplicativo Android final.

Você pode usar a ação de build AndroidNativeLibrary como alternativa.

EmbeddedReferenceJar

Em um projeto de associação do .NET para Android, a ação de build EmbeddedReferenceJar insere o .jar arquivo na biblioteca, mas não cria uma associação C# como EmbeddedJar faz. Quando um projeto de aplicativo .NET para Android consome a biblioteca, ele inclui o código Java/Kotlin no aplicativo Android final.

Você pode usar a ação de compilação AndroidLibrary como uma alternativa, como:<AndroidLibrary Include="..." Bind="false" />

<Project>
  <ItemGroup>
    <!-- A .jar file to bind & embed -->
    <AndroidLibrary Include="Library.jar" />
    <!-- A .jar file to only embed -->
    <AndroidLibrary Include="Dependency.jar" Bind="false" />
  </ItemGroup>
</Project>

JavaSourceJar

Em um projeto de associação do .NET para Android, a ação de build JavaSourceJar é usada em .jar arquivos que contêm código-fonte Java, que contêm comentários de documentação Javadoc.

Em vez disso, o Javadoc será convertido em Comentários de Documentação XML C# dentro do código-fonte de associação gerado.

$(AndroidJavadocVerbosity) controla o quão "detalhado" ou "completo" é o Javadoc importado.

Há suporte para os seguintes metadados do MSBuild:

  • %(CopyrightFile): Um caminho para um arquivo que contém informações de direitos autorais para o conteúdo do Javadoc, que será anexado a toda a documentação importada.

  • %(UrlPrefix): Um prefixo de URL para dar suporte à vinculação à documentação online na documentação importada.

  • %(UrlStyle): O "estilo" dos URLs a serem gerados ao vincular à documentação online. Atualmente, apenas um estilo é suportado: developer.android.com/reference@2020-Nov.

  • %(DocRootUrl): Um prefixo de URL a ser usado no lugar de todas as {@docroot} instâncias na documentação importada.

BibliotecaProjetoZip

A ação de compilação LibraryProjectZip vincula a biblioteca Java/Kotlin e incorpora o .zip arquivo or .aar à biblioteca. Quando um projeto de aplicativo .NET para Android consome a biblioteca, ele tem acesso às APIs Java/Kotlin do C#, além de incluir o código Java/Kotlin no aplicativo Android final.

LinkDescription

Arquivos com uma ação de build LinkDescription são usados para controlar o comportamento do vinculador.

ProguardConfiguration

Arquivos com uma ação de build ProguardConfiguration contêm opções que são usadas para controlar o comportamento de proguard. Para obter mais informações sobre essa ação de build, consulte ProGuard.

Esses arquivos são ignorados, a menos que o $(EnableProguard) A propriedade do MSBuild é True.