Éléments de construction

Les éléments de génération contrôlent la façon dont un projet d’application ou de bibliothèque .NET pour Android est généré.

Ils sont spécifiés dans le fichier projet, par exemple MyApp.csproj, dans un groupe d’éléments MSBuild.

Remarque

Dans .NET pour Android, il n’existe techniquement aucune distinction entre une application et un projet de liaisons. Les éléments de build fonctionnent donc dans les deux. Dans la pratique, il est vivement recommandé de créer des projets d’application et de liaisons distincts. Les éléments de build qui sont principalement utilisés dans les projets de liaisons sont documentés dans le guide de référence des éléments de projet des liaisons MSBuild.

AndroidAdditionalJavaManifest

<AndroidAdditionalJavaManifest> est utilisé conjointement avec la résolution des dépendances Java pour spécifier des fichiers POM supplémentaires qui seront nécessaires pour vérifier les dépendances. Il s’agit souvent de fichiers POM parent ou importés référencés par le fichier POM d’une bibliothèque Java.

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

Les métadonnées MSBuild suivantes sont requises :

  • %(JavaArtifact): Le groupe et l’ID d’artefact de la bibliothèque Java correspondant au fichier POM spécifié dans le formulaire {GroupId}:{ArtifactId}.
  • %(JavaVersion): version de la bibliothèque Java correspondant au fichier POM spécifié.

Pour plus d’informations, consultez la documentation sur la résolution des dépendances Java.

Cette action de génération a été introduite dans .NET 9.

AndroidAsset

Prend en charge les Android Assets, fichiers qui seraient inclus dans le dossier assets d'un projet Android Java.

À compter de .NET 9, l’action de @(AndroidAsset) génération prend également en charge des métadonnées supplémentaires pour générer des packs d’actifs. Les %(AndroidAsset.AssetPack) métadonnées peuvent être utilisées pour générer automatiquement un pack de ressources de ce nom. Cette fonctionnalité est prise en charge uniquement lorsque $(AndroidPackageFormat) est défini sur .aab. L’exemple suivant place movie2.mp4 et movie3.mp4 dans des packs d’éléments distincts.

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

Cette fonctionnalité peut être utilisée pour inclure des fichiers volumineux dans votre application, ce qui dépasserait normalement les limites maximales de taille de package de Google Play.

Si vous avez un grand nombre de ressources, il peut être plus efficace d’utiliser le base pack d’actifs. Dans ce scénario, vous mettez à jour toutes les ressources pour qu’elles se trouvent dans un seul pack d’actifs, puis utilisez les AssetPack="base" métadonnées pour déclarer les ressources spécifiques qui se retrouvent dans le fichier aab de base. Avec cela, vous pouvez utiliser des caractères génériques pour déplacer la plupart des ressources dans le pack de ressources.

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

Dans cet exemple, movie.mp4 et some.png se retrouve dans le base fichier aab, tandis que toutes les autres ressources se retrouvent dans le assets1 pack de ressources.

Les métadonnées supplémentaires sont uniquement prises en charge sur .NET pour Android 9 et versions ultérieures.

AndroidAarLibrary

L’action Build de AndroidAarLibrary devrait être utilisée pour référencer directement les fichiers .aar. Cette action de génération est le plus souvent utilisée par les composants Xamarin. Pour inclure des références aux .aar fichiers requis pour faire fonctionner Google Play et d'autres services.

Les fichiers avec cette action de génération sont traités de manière similaire aux ressources incorporées trouvées dans les projets de bibliothèque. Le .aar fichier sera extrait dans le répertoire intermédiaire. Ensuite, tous les actifs, ressources et .jar fichiers seront inclus dans les groupes d’éléments appropriés.

AndroidAotProfile

Utilisé pour fournir un profil AOT, pour une utilisation avec AOT guidé par profil.

Il peut également être utilisé à partir de Visual Studio en définissant l’action AndroidAotProfile de génération sur un fichier contenant un profil AOT.

AndroidAppBundleMetaDataFile

Spécifie un fichier qui sera inclus en tant que métadonnées dans le bundle d’applications Android. Le format de la valeur d’indicateur correspond <bundle-path>:<physical-file>bundle-path à l’emplacement du fichier dans le répertoire de métadonnées de l’offre groupée d’applications, et physical-file il s’agit d’un fichier existant contenant les données brutes à stocker.

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

Pour plus d’informations, consultez la documentation bundletool .

AndroidBoundLayout

Indique que le fichier de disposition doit avoir un code-behind généré lorsque la propriété $(AndroidGenerateLayoutBindings) est définie sur false. Dans tous les autres aspects, il est identique à AndroidResource.

Cette action peut être utilisée uniquement avec les fichiers de disposition :

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

Environnement Android

Les fichiers avec une action de génération AndroidEnvironment sont utilisés pour initialiser des variables d’environnement et des propriétés système lors du démarrage du processus. L’action de génération AndroidEnvironment peut être appliquée à plusieurs fichiers : dans ce cas, ils sont évalués sans suivre un ordre particulier (ne spécifiez donc pas la même variable d’environnement ou la même propriété système dans plusieurs fichiers).

AndroidGradleProject

<AndroidGradleProject> peut être utilisé pour générer et consommer les sorties des projets Android Gradle créés dans Android Studio ou elsewehere.

Les métadonnées Include doivent pointer vers le fichier build.gradle supérieur ou build.gradle.kts qui sera utilisé pour générer le projet. Ceci se trouvera dans le répertoire racine de votre projet Gradle, qui doit également contenir des scripts wrapper gradlew.

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

Les métadonnées MSBuild suivantes sont prises en charge :

  • %(Configuration): nom de la configuration à utiliser pour générer ou assembler le projet ou le module de projet spécifié. La valeur par défaut est Release.
  • %(ModuleName): nom du module ou du sous-projet qui doit être généré. La valeur par défaut est vide.
  • %(OutputPath): peut être défini pour remplacer le chemin de sortie de build du projet Gradle. La valeur par défaut est $(IntermediateOutputPath)gradle/%(ModuleName)%(Configuration)-{Hash}.
  • %(CreateAndroidLibrary) : Les fichiers AAR de sortie seront ajoutés au projet AndroidLibrary. Les métadonnées prises en charge par <AndroidLibrary> like %(Bind) ou %(Pack) seront transférées si elles sont définies. La valeur par défaut est true.

Cette action de génération a été introduite dans .NET 9.

AndroidJavaLibrary

Les fichiers avec une action de génération AndroidJavaLibrary sont des archives Java (fichiers .jar) qui seront inclus dans le package Android final.

DépendanceJavaIgnoréeParAndroid

<AndroidIgnoredJavaDependency> est utilisé conjointement avec la résolution des dépendances Java.

Il est utilisé pour spécifier une dépendance Java qui doit être ignorée. Cela peut être utilisé si une dépendance est remplie d'une manière que la résolution des dépendances Java ne peut pas détecter.

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

Les métadonnées MSBuild suivantes sont requises :

  • %(Version): version de la bibliothèque Java correspondant à la valeur spécifiée %(Include).

Pour plus d’informations, consultez la documentation sur la résolution des dépendances Java.

Cette action de génération a été introduite dans .NET 9.

AndroidJavaSource

Les fichiers ayant une action de génération de AndroidJavaSource sont du code source Java qui seront inclus dans le package Android final.

À compter de .NET 7, tous les fichiers du répertoire du projet ont automatiquement une action de génération , et seront liés avant la génération d’assembly. Permet au code C# d’utiliser facilement des types et des membres présents dans les **\*.java fichiers.

Définissez %(AndroidJavaSource.Bind) la valeur False pour désactiver ce comportement.

AndroidLibrary

AndroidLibrary est une nouvelle action de génération pour simplifier l'inclusion des fichiers .jar et .aar dans les projets.

N’importe quel projet peut spécifier :

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

Le résultat de l’extrait de code ci-dessus a un effet différent pour chaque type de projet .NET pour Android :

Cette simplification signifie que vous pouvez utiliser AndroidLibrary partout.

AndroidLintConfig

L’action de génération « AndroidLintConfig » doit être utilisée conjointement avec le Propriété $(AndroidLintEnabled). Les fichiers avec cette action de génération seront fusionnés et transmis à l'outillage lint Android. Il doit s’agir de fichiers XML contenant des informations sur les tests pour activer et désactiver.

Consultez la documentation Lint pour plus d’informations.

AndroidManifestOverlay

L’action AndroidManifestOverlay de génération peut être utilisée pour fournir des AndroidManifest.xml fichiers à l’outil Manifest Merger. Les fichiers avec cette action de génération sont transmis au fusionneur de manifestes, ainsi que le fichier principal AndroidManifest.xml et les fichiers de manifeste provenant des références. Celles-ci seront ensuite fusionnées dans le manifeste final.

Vous pouvez utiliser cette action de génération pour fournir des modifications et des paramètres à votre application en fonction de votre configuration de build. Par exemple, si vous devez disposer d’une autorisation spécifique uniquement pendant le débogage, vous pouvez utiliser la superposition pour injecter cette autorisation lors du débogage. Par exemple, étant donné le contenu du fichier de superposition suivant :

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

Vous pouvez utiliser le suivant pour ajouter une superposition du manifeste à une compilation de débogage :

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

AndroidInstallModules

Spécifie les modules installés par la commande bundletool lors de l’installation d’ensembles d’applications.

AndroidMavenLibrary

<AndroidMavenLibrary> permet à un artefact Maven d’être spécifié, qui sera automatiquement téléchargé et ajouté à un projet de liaison .NET pour Android. Cela peut être utile pour simplifier la maintenance des liaisons .NET pour Android pour les artefacts hébergés dans Maven.

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

Les métadonnées MSBuild suivantes sont prises en charge :

  • %(Version): version requise de la bibliothèque Java référencée par %(Include).
  • %(Repository): référentiel Maven facultatif à utiliser. Les valeurs prises en charge sont Central (par défaut), Googleou une https URL vers un référentiel Maven.

L’élément <AndroidMavenLibrary> est traduit en AndroidLibrary, donc toutes les métadonnées prises en charge par <AndroidLibrary> comme %(Bind) ou %(Pack) sont également acceptées.

Pour plus d’informations, consultez la documentation AndroidMavenLibrary.

Cette action de génération a été introduite dans .NET 9.

AndroidNativeLibrary

Les bibliothèques natives sont ajoutées à la compilation en définissant leur action de compilation sur AndroidNativeLibrary.

Notez que, étant donné que Android prend en charge plusieurs interfaces binaires d’application (ABIs), le système de génération doit connaître l’ABI pour lequel la bibliothèque native est générée. Il existe deux façons de spécifier l’ABI :

  1. « Détection » du chemin.
  2. Utilisation des métadonnées d’élément %(Abi) .

Avec la détection de chemin, le nom du répertoire parent de la bibliothèque native est utilisé pour spécifier l’ABI ciblée par la bibliothèque. Ainsi, si vous ajoutez lib/armeabi-v7a/libfoo.so à la build, l’ABI sera « détectée » en tant que armeabi-v7a.

Nom de l’attribut d’élément

Abi : spécifie l’ABI de la bibliothèque native.

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

AndroidNativeLibraryNoJniPreload

Chaque bibliothèque native incluse dans ce groupe d’éléments sera exemptée du mécanisme de préchargement de la bibliothèque JNI. Par défaut, toutes ces bibliothèques seront chargées par le runtime au début du démarrage de l’application afin de garantir leur initialisation appropriée. Toutefois, dans certains cas, il peut ne pas s’agir du comportement souhaité et ce groupe d’éléments autorise l’exclusion des bibliothèques de ce processus individuellement.

Certaines bibliothèques d’infrastructure qui doivent être chargées au démarrage de l’application ne seront pas affectées si elles sont incluses dans ce groupe d’éléments.

Voir aussi $(AndroidIgnoreAllJniPreload)

AndroidPackagingOptionsExclude

Ensemble d’éléments compatibles glob de fichier qui permettent aux éléments d’être exclus du package final. Les valeurs par défaut sont les suivantes :

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

Les éléments peuvent utiliser des caractères blob de fichiers pour les caractères génériques tels que * et ?. Toutefois, ces éléments DOIVENT être encodés en URL ou utiliser $([MSBuild]::Escape('')). C’est pourquoi MSBuild n’essaie pas de les interpréter comme des caractères génériques de fichier réels.

Par exemple

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

REMARQUE : *et ?. sera remplacé dans la BuildApk tâche par les globs de fichier appropriés.

Si le fichier glob par défaut est trop restrictif, vous pouvez le supprimer en ajoutant ce qui suit à votre csproj

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

Ajouté dans .NET 7.

Options d'emballage d'Android Inclure

Ensemble d’éléments compatibles avec les modèles glob de fichiers permettant d’inclure des éléments dans le package final. Les valeurs par défaut sont les suivantes :

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

Les éléments peuvent utiliser des caractères blob de fichiers pour les caractères génériques tels que * et ?. Toutefois, ces éléments DOIVENT utiliser l’encodage d’URL ou '$([MSBuild] ::Escape(''))'. C’est pourquoi MSBuild n’essaie pas de les interpréter comme des caractères génériques de fichier réels. Par exemple

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

REMARQUE : *et ?. sera remplacé dans la BuildApk tâche par les globs de fichier appropriés.

Ajouté dans .NET 9.

AndroidResource

Tous les fichiers avec une action de génération AndroidResource sont compilés en ressources Android pendant le processus de génération et rendus accessible via $(AndroidResgenFile).

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

Les utilisateurs plus expérimentés souhaitent éventuellement avoir des ressources différentes utilisées dans des configurations différentes, mais avec le même chemin effectif. Il faut pour cela avoir plusieurs répertoires de ressources et des fichiers avec les mêmes chemins relatifs au sein de ces différents répertoires, et utiliser des conditions MSBuild pour inclure de façon conditionnelle des fichiers différents dans les différentes configurations. Par exemple :

<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 : spécifie explicitement le chemin d’accès de la ressource. Permet de créer des alias pour les fichiers afin qu'ils soient disponibles sous la forme de plusieurs noms de ressources distincts.

<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>

Contenu

L’action de génération Content normale n’est pas supportée (car nous n'avons pas déterminé comment la supporter sans une étape de première exécution potentiellement coûteuse).

Toute tentative d’utilisation de l’action @(Content) Build génère un avertissement XA0101 .

EmbeddedJar

Dans un projet de liaison .NET pour Android, l’action de génération EmbeddedJar lie la bibliothèque Java/Kotlin et incorpore le .jar fichier dans la bibliothèque. Lorsqu’un projet d’application .NET pour Android consomme la bibliothèque, il aura accès aux API Java/Kotlin à partir de C# et inclura le code Java/Kotlin dans l’application Android finale.

Vous devriez à la place utiliser l’action de build AndroidLibrary :

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

BibliothèqueNativeIntégrée

Dans une bibliothèque de classes .NET pour Android ou un projet de liaison Java, l’action de génération EmbeddedNativeLibrary regroupe une bibliothèque native telle que lib/armeabi-v7a/libfoo.so dans la bibliothèque. Lorsqu’une application .NET pour Android consomme la bibliothèque, le libfoo.so fichier est inclus dans l’application Android finale.

Vous pouvez utiliser l’action de construction AndroidNativeLibrary comme alternative.

EmbeddedReferenceJar

Dans un projet de liaison .NET pour Android, l’action de génération EmbeddedReferenceJar incorpore le .jar fichier dans la bibliothèque, mais ne crée pas de liaison C# comme EmbeddedJar . Lorsqu’un projet d’application .NET pour Android consomme la bibliothèque, il inclut le code Java/Kotlin dans l’application Android finale.

Vous pouvez utiliser l'action de construction AndroidLibrary comme alternative, par exemple <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

Dans un projet de liaison .NET pour Android, l’action de génération JavaSourceJar est utilisée sur .jar les fichiers qui contiennent du code source Java, qui contiennent des commentaires de documentation Javadoc.

Javadoc sera converti en commentaires de documentation XML C# dans le code source de liaison généré.

$(AndroidJavadocVerbosity) contrôle la façon dont « verbose » ou « complete » est le javadoc importé.

Les métadonnées MSBuild suivantes sont prises en charge :

  • %(CopyrightFile): chemin d’accès à un fichier qui contient des informations de copyright pour le contenu Javadoc, qui sera ajouté à toutes les documentations importées.

  • %(UrlPrefix): préfixe d’URL permettant de prendre en charge la liaison à la documentation en ligne dans la documentation importée.

  • %(UrlStyle): le « style » des URL à générer lors de la liaison à la documentation en ligne. Un seul style est actuellement pris en charge : developer.android.com/reference@2020-Nov.

  • %(DocRootUrl): préfixe d’URL à utiliser à la place de toutes les {@docroot} instances de la documentation importée.

LibraryProjectZip

L’action de génération LibraryProjectZip lie la bibliothèque Java/Kotlin et incorpore le fichier .zip ou .aar dans la bibliothèque. Lorsqu’un projet d’application .NET pour Android consomme la bibliothèque, il aura accès aux API Java/Kotlin à partir de C# et inclura le code Java/Kotlin dans l’application Android finale.

Description du lien

Des fichiers avec une action de génération LinkDescription sont utilisés pour contrôler le comportement de l’éditeur de liens.

ProguardConfiguration

Les fichiers avec une action de génération ProguardConfiguration contiennent des options qui permettent de contrôler le comportement de proguard. Pour plus d’informations sur cette action de génération, consultez ProGuard.

Ces fichiers sont ignorés, sauf si les conditions spécifiées sont remplies. $(EnableProguard) La propriété MSBuild est True.

  • Last updated on