Compartir a través de

Elementos de compilación

  • Artículo

Los elementos de compilación controlan cómo se compila un proyecto de biblioteca o aplicación de .NET para Android.

Se especifican en el archivo de proyecto, por ejemplo MyApp.csproj, dentro de un ItemGroup de MSBuild.

Nota:

En .NET para Android no hay técnicamente ninguna distinción entre una aplicación y un proyecto de enlaces, por lo que los elementos de compilación funcionarán en ambos. En la práctica, se recomienda crear proyectos de aplicación y enlaces independientes. Los elementos de compilación que se usan principalmente en los proyectos de enlaces se documentan en la guía de referencia de los elementos de proyecto de enlaces de MSBuild.

AndroidAdditionalJavaManifest

<AndroidAdditionalJavaManifest> se usa junto con la resolución de dependencias de Java para especificar archivos POM adicionales que se necesitarán para comprobar las dependencias. A menudo se trata de archivos POM primarios o importados a los que hace referencia el archivo POM de una biblioteca de Java.

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

Se requieren los siguientes metadatos de MSBuild:

  • %(JavaArtifact): el identificador de grupo y artefacto de la biblioteca de Java que coincide con el archivo POM especificado con el formato {GroupId}:{ArtifactId}.
  • %(JavaVersion): la versión de la biblioteca de Java que coincide con el archivo POM especificado.

Consulte la documentación de resolución de dependencias de Java para obtener más información.

Esta acción de compilación se introdujo en .NET 9.

AndroidAsset

Admite recursos de Android, archivos que se incluirán en la carpeta assets en un proyecto de Java Android.

A partir de .NET 9, la @(AndroidAsset) acción de compilación también admite metadatos adicionales para generar Asset Packs. Los %(AndroidAsset.AssetPack) metadatos se pueden usar para generar automáticamente un paquete de recursos de ese nombre. Esta característica solo se admite cuando se establece .aaben $(AndroidPackageFormat) . En el ejemplo siguiente se colocarán movie2.mp4 y movie3.mp4 en paquetes de recursos independientes.

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

Esta característica se puede usar para incluir archivos grandes en la aplicación que normalmente superarían los límites de tamaño máximo del paquete de Google Play.

Si tiene un gran número de recursos, puede ser más eficaz usar el base paquete de recursos. En este escenario, se actualizan todos los recursos para que estén en un único paquete de recursos y, a continuación, se usan los AssetPack="base" metadatos para declarar qué recursos específicos terminan en el archivo aab base. Con esto puede usar caracteres comodín para mover la mayoría de los recursos al paquete de recursos.

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

En este ejemplo, movie.mp4 y some.png terminará en el base archivo aab, mientras que todos los demás recursos terminarán en el paquete de assets1 recursos.

Los metadatos adicionales solo se admiten en .NET para Android 9 y versiones posteriores.

AndroidAarLibrary

La acción de compilación de AndroidAarLibrary se debe utilizar para hacer referencia directamente a los archivos .aar. Esta acción de compilación la utilizan normalmente componentes de Xamarin. Es decir, para incluir referencias a archivos .aar que son necesarios para que funcionen Google Play y otros servicios.

Los archivos con esta acción de compilación se tratarán de un modo bastante similar a los recursos incrustados en proyectos de biblioteca. El archivo .aar se extrae en el directorio intermedio. Después, los recursos y los archivos .jar se incluirán en los grupos de elementos pertinentes.

AndroidAotProfile

Se usa para proporcionar un perfil de AOT, para su uso con el AOT guiado por perfiles.

También se puede usar desde Visual Studio estableciendo la acción de compilación AndroidAotProfile en un archivo que contenga un perfil de AOT.

AndroidAppBundleMetaDataFile

Especifica un archivo que se incluirá como metadatos en el lote de aplicaciones de Android. El formato del valor de la marca es <bundle-path>:<physical-file>, donde bundle-path denota la ubicación del archivo dentro del directorio de metadatos del lote de aplicaciones y physical-file es un archivo existente que contiene los datos sin procesar que se van a almacenar.

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

Consulte la documentación de bundletool para obtener más detalles.

AndroidBoundLayout

Indica que el archivo de diseño debe tener código subyacente generado para él en caso de que la $(AndroidGenerateLayoutBindings) propiedad esté establecida falseen . En todos los demás aspectos es idéntico a AndroidResource.

Esta acción solo se puede usar con archivos de diseño:

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

AndroidEnvironment

Los archivos con una acción de compilación de AndroidEnvironment se usan para inicializar variables de entorno y propiedades del sistema durante el inicio del proceso. La acción de compilación AndroidEnvironment se puede aplicar a varios archivos, y estos se evalúan sin ningún orden determinado (así que no especifique la misma variable de entorno o propiedad de sistema en varios archivos).

AndroidGradleProject

<AndroidGradleProject> se puede usar para compilar y consumir las salidas de los proyectos de Android Gradle creados en Android Studio o en elsewehere.

Los Include metadatos deben apuntar al nivel build.gradle superior o build.gradle.kts al archivo que se usará para compilar el proyecto. Esto se encontrará en el directorio raíz del proyecto de Gradle, que también debe contener gradlew scripts de contenedor.

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

Se admiten los siguientes metadatos de MSBuild:

  • %(Configuration): nombre de la configuración que se va a usar para compilar o ensamblar el proyecto o el módulo de proyecto especificado. El valor predeterminado es Release.
  • %(ModuleName): nombre del módulo o subproyecto que se debe compilar. El valor predeterminado está vacío.
  • %(OutputPath): se puede establecer para invalidar la ruta de acceso de salida de compilación del proyecto de Gradle. El valor predeterminado es $(IntermediateOutputPath)gradle/%(ModuleName)%(Configuration)-{Hash}.
  • %(CreateAndroidLibrary): los archivos AAR de salida se agregarán como un AndroidLibrary elemento al proyecto. Los metadatos admitidos por <AndroidLibrary> like %(Bind) o %(Pack) se reenviarán si se establecen. El valor predeterminado es true.

Esta acción de compilación se introdujo en .NET 9.

AndroidJavaLibrary

Los archivos con una acción de compilación de AndroidJavaLibrary son archivos de Java (archivos .jar) que se incluirán en el paquete final de Android.

AndroidIgnoredJavaDependency

<AndroidIgnoredJavaDependency> se usa junto con la resolución de dependencias de Java.

Se usa para especificar una dependencia de Java que se debe omitir. Esto se puede usar si se cumplirá una dependencia de una manera que la resolución de dependencias de Java no pueda detectar.

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

Se requieren los siguientes metadatos de MSBuild:

  • %(Version): la versión de la biblioteca de Java que coincide con el especificado %(Include).

Consulte la documentación de resolución de dependencias de Java para obtener más información.

Esta acción de compilación se introdujo en .NET 9.

AndroidJavaSource

Los archivos con una acción de compilación de AndroidJavaSource son el código fuente de Java que se incluirá en el paquete final de Android.

A partir de .NET 7, todos los archivos **\*.java del directorio del proyecto tienen automáticamente una acción de compilación de AndroidJavaSource, y se enlazarán antes de la compilación del ensamblado. Permite que el código de C# use con facilidad los tipos y miembros presentes en los archivos **\*.java.

Establezca %(AndroidJavaSource.Bind) en False para deshabilitar este comportamiento.

AndroidLibrary

AndroidLibrary es una nueva acción de compilación para simplificar cómo se incluyen los archivos .jar y .aar en los proyectos.

En cualquier proyecto se puede especificar:

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

El resultado del fragmento de código anterior tiene un efecto diferente para cada tipo de proyecto de .NET para Android:

Esta simplificación significa que puede usar AndroidLibrary en cualquier lugar.

AndroidLintConfig

La acción de compilación "AndroidLintConfig" se debe usar con la propiedad de compilación .Propiedad $(AndroidLintEnabled). Los archivos con esta acción de compilación se combinan y se pasan a las herramientas lint de Android. Deben ser archivos XML que contengan información sobre qué pruebas deben habilitarse o deshabilitarse.

Vea la documentación de lint para obtener más información.

AndroidManifestOverlay

Se puede usar la acción de compilación AndroidManifestOverlay para proporcionar archivos AndroidManifest.xml a la herramienta de fusión de manifiestos. Los archivos con esta acción de compilación se pasarán a la herramienta de fusión de manifiestos junto con el archivo AndroidManifest.xml principal y los archivos de manifiesto de las referencias. Después, se combinarán en el manifiesto final.

Puede usar esta acción de compilación para proporcionar cambios y configuraciones a la aplicación en función de la configuración de compilación. Por ejemplo, si necesita tener un permiso concreto solo durante la depuración, puede utilizar la superposición para insertar ese permiso durante la depuración. Por ejemplo, dado el siguiente contenido de archivo de superposición:

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

Puede usar lo siguiente para agregar una superposición de manifiesto a una compilación de depuración:

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

AndroidInstallModules

Especifica los módulos que se instalan mediante el comando bundletool al instalar lotes de aplicaciones.

AndroidMavenLibrary

<AndroidMavenLibrary> permite especificar un artefacto de Maven que se descargará y agregará automáticamente a un proyecto de enlace de .NET para Android. Esto puede ser útil para simplificar el mantenimiento de los enlaces de .NET para Android para artefactos hospedados en Maven.

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

Se admiten los siguientes metadatos de MSBuild:

  • %(Version): versión necesaria de la biblioteca de Java a la que hace %(Include)referencia .
  • %(Repository): repositorio de Maven opcional que se va a usar. Los valores admitidos son Central (valor predeterminado), Googleo una https dirección URL a un repositorio de Maven.

El <AndroidMavenLibrary> elemento se traduce en AndroidLibrary, por lo que también se admiten los metadatos admitidos por <AndroidLibrary> como %(Bind) o %(Pack) .

Consulte la documentación de AndroidMavenLibrary para obtener más información.

Esta acción de compilación se introdujo en .NET 9.

AndroidNativeLibrary

Las bibliotecas nativas se agregan a la compilación mediante el establecimiento de su acción de compilación en AndroidNativeLibrary.

Tenga en cuenta que, puesto que Android admite varias interfaces binarias de aplicación (ABI), el sistema de compilación debe saber para qué ABI se ha compilado la biblioteca nativa. Hay dos formas de especificar una ABI:

  1. Examinando la ruta de acceso.
  2. Mediante los metadatos del elemento %(Abi).

Con el examen de la ruta de acceso, el nombre del directorio principal de la biblioteca nativa se utiliza para especificar la ABI a la que se dirige la biblioteca. Por lo tanto, si agrega lib/armeabi-v7a/libfoo.so a la compilación, la ABI se examina como armeabi-v7a.

Nombre del atributo Item

Abi: especifica la ABI de la biblioteca nativa.

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

AndroidPackagingOptionsExclude

Conjunto de elementos compatibles con glob de archivo que permitirán que los elementos se excluyan del paquete final. Los valores predeterminados son los siguientes:

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

Los elementos pueden usar caracteres de blob de archivo para caracteres comodín, como * y ?. Sin embargo, estos elementos DEBEN estar codificados en dirección URL o usar $([MSBuild]::Escape('')). Esto es así que MSBuild no intenta interpretarlos como caracteres comodín de archivo reales.

Por ejemplo

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

NOTA: *, ? y . se reemplazarán en la BuildApk tarea por los globs de archivo adecuados.

Si el glob de archivo predeterminado es demasiado restrictivo, puede quitarlo agregando lo siguiente a su csproj.

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

Se ha agregado en .NET 7.

AndroidPackagingOptionsInclude

Conjunto de elementos compatibles con glob de archivo que permitirán que los elementos se incluyan en el paquete final. Los valores predeterminados son los siguientes:

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

Los elementos pueden usar caracteres de blob de archivo para caracteres comodín, como * y ?. Sin embargo, estos elementos DEBEN usar la codificación URL o '$([MSBuild]::Escape(''))'. Esto es así que MSBuild no intenta interpretarlos como caracteres comodín de archivo reales. Por ejemplo

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

NOTA: *, ? y . se reemplazarán en la BuildApk tarea por los globs de archivo adecuados.

Se ha agregado en .NET 9.

AndroidResource

Todos los archivos con una acción de compilación de AndroidResource se compilan en recursos de Android durante el proceso de compilación y se vuelven accesibles mediante $(AndroidResgenFile).

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

Quizás los usuarios más avanzados deseen que recursos diferentes se usen en distintas configuraciones, pero con la misma ruta de acceso efectiva. Para lograr esto, se pueden tener varios directorios de recursos y tener archivos con las mismas rutas de acceso relativas dentro de estos diferentes directorios, y usar condiciones de MSBuild para incluir condicionalmente diferentes archivos en diferentes configuraciones. Por ejemplo:

<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 la ruta de acceso a los recursos de forma explícita. Permite la creación de alias de archivos para que estén disponibles como varios nombres 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>

Contenido

La acción de compilación Content no se admite (dado que no hemos descubierto cómo admitirla sin un paso seguramente costoso de primera ejecución).

Si intenta usar la @(Content) acción Compilar, se producirá una advertencia de XA0101 .

EmbeddedJar

En un proyecto de enlace de .NET para Android, la acción de compilación embeddedJar enlaza la biblioteca java/Kotlin e inserta el .jar archivo en la biblioteca. Cuando un proyecto de aplicación de .NET para Android consume la biblioteca, tendrá acceso a las API de Java/Kotlin desde C#, así como a incluir el código Java/Kotlin en la aplicación android final.

En su lugar, debe usar la acción de compilación de AndroidLibrary como alternativa, como:

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

EmbeddedNativeLibrary

En un proyecto de enlace de la biblioteca de clases de .NET para Android o Java, la acción de compilación EmbeddedNativeLibrary agrupa una biblioteca nativa como lib/armeabi-v7a/libfoo.so en la biblioteca. Cuando una aplicación .NET para Android consume la biblioteca, el libfoo.so archivo se incluirá en la aplicación android final.

Puede usar la acción de compilación AndroidNativeLibrary como alternativa.

EmbeddedReferenceJar

En un proyecto de enlace de .NET para Android, la acción de compilación EmbeddedReferenceJar inserta el .jar archivo en la biblioteca, pero no crea un enlace de C# como EmbeddedJar . Cuando un proyecto de aplicación de .NET para Android consume la biblioteca, incluirá el código Java/Kotlin en la aplicación android final.

Puede usar la acción de compilación androidLibrary como 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

En un proyecto de enlace de .NET para Android, la acción de compilación de JavaSourceJar se usa en .jar archivos que contienen código fuente de Java, que contienen comentarios de documentación de Javadoc.

En su lugar, Javadoc se convertirá en comentarios de documentación XML de C# en el código fuente de enlace generado.

$(AndroidJavadocVerbosity) controla hasta qué punto es "detallado" o "completo" el Javadoc importado.

Se admiten los siguientes metadatos de MSBuild:

  • %(CopyrightFile): ruta de acceso a un archivo que contiene información de copyright para el contenido de Javadoc, que se anexará a toda la documentación importada.

  • %(UrlPrefix): prefijo de dirección URL para admitir la vinculación a documentación en línea dentro de la documentación importada.

  • %(UrlStyle): el "estilo" de las direcciones URL que se generarán al vincular a la documentación en línea. Actualmente, solo se admite un estilo: developer.android.com/reference@2020-Nov.

  • %(DocRootUrl): prefijo de dirección URL que se va a usar en lugar de todas las {@docroot} instancias de la documentación importada.

LibraryProjectZip

La acción de compilación LibraryProjectZip enlaza la biblioteca Java/Kotlin e inserta el .zip archivo o .aar en la biblioteca. Cuando un proyecto de aplicación de .NET para Android consume la biblioteca, tendrá acceso a las API de Java/Kotlin desde C#, así como a incluir el código Java/Kotlin en la aplicación android final.

LinkDescription

Los archivos con una acción de compilación LinkDescription se usan para controlan el comportamiento del enlazador.

ProguardConfiguration

Los archivos con una acción de compilación ProguardConfiguration contienen opciones que se usan para controlar el comportamiento de proguard. Para más información sobre esta acción de compilación, consulte ProGuard.

Estos archivos se omiten a menos que la propiedad de MSBuild la propiedad $(EnableProguard) de MSBuild sea True.