Freigeben über

Buildelemente

  • Artikel

Buildelemente steuern, wie ein .NET für Android-Anwendungs- oder Bibliotheksprojekt erstellt wird.

Sie werden in der Projektdatei angegeben, z . B. MyApp.csproj, innerhalb einer MSBuild ItemGroup.

Hinweis

In .NET für Android gibt es technisch keinen Unterschied zwischen einer Anwendung und einem Bindungsprojekt, sodass Buildelemente in beiden funktionieren. In der Praxis wird dringend empfohlen, separate Anwendungs- und Bindungsprojekte zu erstellen. Buildelemente, die in erster Linie in Bindungen projekten verwendet werden, werden im Referenzhandbuch für MSBuild-Bindungen für Projektelemente dokumentiert.

AndroidAdditionalJavaManifest

<AndroidAdditionalJavaManifest> wird in Verbindung mit der Java-Abhängigkeitsauflösung verwendet, um zusätzliche POM-Dateien anzugeben, die zum Überprüfen von Abhängigkeiten erforderlich sind. Dies sind häufig übergeordnete oder importierte POM-Dateien, auf die von der POM-Datei einer Java-Bibliothek verwiesen wird.

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

Die folgenden MSBuild-Metadaten sind erforderlich:

  • %(JavaArtifact): Die Gruppen- und Artefakt-ID der Java-Bibliothek, die der angegebenen POM-Datei im Formular {GroupId}:{ArtifactId}entspricht.
  • %(JavaVersion): Die Version der Java-Bibliothek, die der angegebenen POM-Datei entspricht.

Weitere Details finden Sie in der Dokumentation zur Java-Abhängigkeitsauflösung.

Diese Buildaktion wurde in .NET 9 eingeführt.

AndroidAsset

Unterstützt Android-Ressourcen, also Dateien, die in einem Java-Android-Projekt im Ordner assets gespeichert werden.

Ab .NET 9 unterstützt die @(AndroidAsset) Buildaktion auch zusätzliche Metadaten zum Generieren von Asset Packs. Die %(AndroidAsset.AssetPack) Metadaten können verwendet werden, um automatisch ein Objektpaket mit diesem Namen zu generieren. Dieses Feature wird nur unterstützt, wenn die $(AndroidPackageFormat) Einstellung auf .aab. Das folgende Beispiel platziert movie2.mp4 und movie3.mp4 in separaten Bestandspaketen.

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

Dieses Feature kann verwendet werden, um große Dateien in Ihre Anwendung einzuschließen, die normalerweise die maximalen Grenzwerte für die Paketgröße von Google Play überschreiten würden.

Wenn Sie über eine große Anzahl von Ressourcen verfügen, ist es möglicherweise effizienter, das base Asset Pack zu nutzen. In diesem Szenario aktualisieren Sie ALLE Objekte in einem einzelnen Objektpaket, und verwenden Sie dann die AssetPack="base" Metadaten, um zu deklarieren, welche bestimmten Ressourcen in der Basisabdatei enden. Damit können Sie mithilfe von Wildcards die meisten Ressourcen in das Bestandspaket verschieben.

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

In diesem Beispiel movie.mp4 endet base die some.png aab-Datei, während alle anderen Ressourcen im assets1 Bestandspaket enden.

Die zusätzlichen Metadaten werden nur unter .NET für Android 9 und höher unterstützt.

AndroidAarLibrary

Die Buildaktion von AndroidAarLibrary sollte verwendet werden, um direkt auf .aar-Dateien zu verweisen. Diese Buildaktion wird am häufigsten von Xamarin-Komponenten verwendet. Um Verweise auf Dateien einzuschließen .aar , die erforderlich sind, um Google Play und andere Dienste funktionieren zu lassen.

Dateien mit dieser Buildaktion werden ähnlich behandelt wie die eingebetteten Ressourcen in Bibliotheksprojekten. Die .aar-Datei wird in das Zwischenverzeichnis extrahiert. Danach werden Objekte, Ressourcen und .jar-Dateien in die entsprechenden Elementgruppen eingefügt.

AndroidAotProfile

Wird zur Bereitstellung eines AOT-Profils zur Verwendung mit einem profilgesteuerten AOT verwendet.

Dieses Element kann auch in Visual Studio verwendet werden, indem die Buildaktion AndroidAotProfile auf eine Datei mit einem AOT-Profil festgelegt wird.

AndroidAppBundleMetaDataFile

Gibt eine Datei an, die als Metadaten im Android-App-Bundle enthalten sein wird. Das Format des Flagwerts ist <bundle-path>:<physical-file> der bundle-path Ort, an dem der Dateispeicherort im Metadatenverzeichnis des App Bundles angegeben ist und physical-file eine vorhandene Datei mit den zu speichernden Rohdaten ist.

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

Weitere Details finden Sie in der Bundletool-Dokumentation .

AndroidBoundLayout

Gibt an, dass für die Layoutdatei CodeBehind generiert werden soll, falls die $(AndroidGenerateLayoutBindings) Eigenschaft auf false ". In allen anderen Aspekten ist es identisch mit AndroidResource.

Diese Aktion kann nur mit Layoutdateien verwendet werden:

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

AndroidEnvironment

Dateien mit einer Buildaktion von AndroidEnvironment werden verwendet, um Umgebungsvariablen und Systemeigenschaften während des Prozessstarts zu initialisieren. Die Buildaktion AndroidEnvironment kann auf mehrere Dateien angewendet werden. Diese werden in keiner bestimmten Reihenfolge ausgewertet (geben Sie daher nicht die gleiche Umgebungsvariable oder Systemeigenschaft in mehreren Dateien an).

AndroidGradleProject

<AndroidGradleProject> kann verwendet werden, um die Ausgaben von Android Gradle-Projekten zu erstellen und zu nutzen, die in Android Studio oder sonstwehere erstellt wurden.

Die Include Metadaten sollten auf die oberste Ebene build.gradle oder build.gradle.kts Datei verweisen, die zum Erstellen des Projekts verwendet wird. Dies befindet sich im Stammverzeichnis Ihres Gradle-Projekts, das auch Wrapperskripts enthalten gradlew sollte.

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

Die folgenden MSBuild-Metadaten werden unterstützt:

  • %(Configuration): Der Name der Konfiguration, die zum Erstellen oder Zusammenstellen des angegebenen Projekt- oder Projektmoduls verwendet werden soll. Der Standardwert ist Release.
  • %(ModuleName): Der Name des Moduls oder Teilprojekts , das erstellt werden soll. Der Standardwert ist leer.
  • %(OutputPath): Kann so festgelegt werden, dass der Buildausgabepfad des Gradle-Projekts außer Kraft gesetzt wird. Der Standardwert ist $(IntermediateOutputPath)gradle/%(ModuleName)%(Configuration)-{Hash}.
  • %(CreateAndroidLibrary): Ausgabe-AAR-Dateien werden dem Projekt hinzugefügt AndroidLibrary . Metadaten, die von <AndroidLibrary> "Gefällt mir" %(Bind) unterstützt werden, oder %(Pack) werden weitergeleitet, wenn diese festgelegt sind. Der Standardwert ist true.

Diese Buildaktion wurde in .NET 9 eingeführt.

AndroidJavaLibrary

Dateien mit einer Buildaktion AndroidJavaLibrary sind Java Archives ( .jar Dateien), die im endgültigen Android-Paket enthalten sein werden.

AndroidIgnoredJavaDependency

<AndroidIgnoredJavaDependency> wird in Verbindung mit der Java-Abhängigkeitsauflösung verwendet.

Es wird verwendet, um eine Java-Abhängigkeit anzugeben, die ignoriert werden soll. Dies kann verwendet werden, wenn eine Abhängigkeit so erfüllt wird, dass die Java-Abhängigkeitsauflösung nicht erkannt werden kann.

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

Die folgenden MSBuild-Metadaten sind erforderlich:

  • %(Version): Die Version der Java-Bibliothek, die dem angegebenen %(Include)entspricht.

Weitere Details finden Sie in der Dokumentation zur Java-Abhängigkeitsauflösung.

Diese Buildaktion wurde in .NET 9 eingeführt.

AndroidJavaSource

Dateien mit einer Buildaktion AndroidJavaSource sind Java-Quellcode, der im endgültigen Android-Paket enthalten sein wird.

Ab .NET 7 verfügen alle **\*.java Dateien im Projektverzeichnis automatisch über eine Buildaktion von AndroidJavaSourceund werden vor dem Assemblybuild gebunden. Ermöglicht C#-Code die einfache Verwendung von Typen und Elementen, die in den **\*.java Dateien vorhanden sind.

Legen Sie %(AndroidJavaSource.Bind) diesen Wert auf "False" fest, um dieses Verhalten zu deaktivieren.

AndroidLibrary

AndroidLibrary ist eine neue Buildaktion, die das Einschließen von .jar- und .aar-Dateien in Projekte vereinfacht.

In jedem Projekt kann Folgendes angegeben werden:

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

Das Ergebnis des obigen Codeausschnitts hat für jeden .NET für Android-Projekttyp einen anderen Effekt:

Durch diese Vereinfachung können Sie AndroidLibrary überall verwenden.

AndroidLintConfig

Die Buildaktion AndroidLintConfig sollte in Verbindung mit der -Eigenschaft verwendet werden.$(AndroidLintEnabled)-Eigenschaft. Dateien mit dieser Buildaktion werden zusammengeführt und an die Android-lint-Tools übergeben. Sie sollten XML-Dateien sein, die Informationen zu Tests enthalten, um sie zu aktivieren und zu deaktivieren.

Weitere Details finden Sie in der Lint-Dokumentation.

AndroidManifestOverlay

Die AndroidManifestOverlay Buildaktion kann verwendet werden, um Dateien für das Manifestzusammenführungstool bereitzustellenAndroidManifest.xml. Dateien mit dieser Buildaktion werden zusammen mit den Hauptdatei AndroidManifest.xml - und Manifestdateien aus Verweisen an die Manifestzusammenführung übergeben. Diese Dateien werden dann im endgültigen Manifest zusammengeführt.

Sie können diese Buildaktion verwenden, um Je nach Buildkonfiguration Änderungen und Einstellungen für Ihre App bereitzustellen. Wenn Sie z. B. eine bestimmte Berechtigung nur beim Debuggen benötigen, können Sie diese durch die Überlagerung beim Debuggen einfügen. Bei einer Überlagerungsdatei mit dem folgenden Inhalt:

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

Sie können folgendes verwenden, um ein Manifestüberlagerung für einen Debugbuild hinzuzufügen:

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

AndroidInstallModules

Gibt die Module an, die beim Installieren von App-Bündeln durch den Bundletool-Befehl installiert werden.

AndroidMavenLibrary

<AndroidMavenLibrary> ermöglicht die Angabe eines Maven-Artefakts, das automatisch heruntergeladen und einem .NET für Android-Bindungsprojekt hinzugefügt wird. Dies kann hilfreich sein, um die Wartung von .NET für Android-Bindungen für Artefakte zu vereinfachen, die in Maven gehostet werden.

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

Die folgenden MSBuild-Metadaten werden unterstützt:

  • %(Version): Erforderliche Version der Java-Bibliothek, auf die verwiesen wird.%(Include)
  • %(Repository): Optionales Maven-Repository, das verwendet werden soll. Unterstützte Werte sind Central (Standard), Googleoder eine https URL zu einem Maven-Repository.

Das <AndroidMavenLibrary> Element wird übersetzt AndroidLibrary, sodass alle metadaten, die von <AndroidLibrary> "Gefällt %(Bind) mir" unterstützt werden oder %(Pack) auch unterstützt werden.

Weitere Details finden Sie in der AndroidMavenLibrary-Dokumentation .

Diese Buildaktion wurde in .NET 9 eingeführt.

AndroidNativeLibrary

Native Bibliotheken werden dem Build hinzugefügt, indem ihre Buildaktion auf AndroidNativeLibrary festgelegt wird.

Da Android mehrere Application Binary Interfaces (ABIs) unterstützt, muss das Buildsystem wissen, für welche ABI die systemeigene Bibliothek erstellt wurde. Es gibt zwei Möglichkeiten, wie die ABI angegeben werden kann:

  1. Pfadermittlung.
  2. Verwenden der %(Abi) Elementmetadaten.

Bei der Pfadermittlung wird der Name des übergeordneten Verzeichnisses der nativen Bibliothek verwendet, um die ABI anzugeben, die die Bibliothek als Ziel verwendet. Wenn Sie dem Build also lib/armeabi-v7a/libfoo.so hinzufügen, wird die ABI als armeabi-v7a „ermittelt“.

Element-Attributname

Abi – Gibt die ABI der nativen Bibliothek an.

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

AndroidPackagingOptionsExclude

Eine Reihe von dateikompatiblen Elementen, die es ermöglichen, dass Elemente aus dem endgültigen Paket ausgeschlossen werden. Die Standardwerte sind wie folgt:

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

Elemente können Datei-BLOB-Zeichen für Wildcards wie * z. B. und ?. Diese Elemente müssen jedoch URL-codiert oder verwendet $([MSBuild]::Escape(''))werden. Dies ist so, dass MSBuild sie nicht als tatsächliche Datei-Wildcards interpretiert.

Beispiel:

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

HINWEIS: *, ? und . wird in der BuildApk Aufgabe durch die entsprechenden Datei-Globs ersetzt.

Wenn die Standarddatei glob zu restriktiv ist, können Sie sie entfernen, indem Sie Folgendes zu Ihrem csproj hinzufügen.

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

In .NET 7 hinzugefügt.

AndroidPackagingOptionsInclude

Eine Reihe von dateikompatiblen Elementen, mit denen Elemente aus dem endgültigen Paket eingeschlossen werden können. Die Standardwerte sind wie folgt:

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

Elemente können Datei-BLOB-Zeichen für Wildcards wie * z. B. und ?. Diese Elemente müssen jedoch die URL-Codierung oder "$([MSBuild]::Escape(')")" verwenden. Dies ist so, dass MSBuild sie nicht als tatsächliche Datei-Wildcards interpretiert. Beispiel:

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

HINWEIS: *, ? und . wird in der BuildApk Aufgabe durch die entsprechenden Datei-Globs ersetzt.

In .NET 9 hinzugefügt.

AndroidResource

Alle Dateien mit einer AndroidResource-Buildaktion werden während des Buildprozesses in Android-Ressourcen kompiliert und über $(AndroidResgenFile) zugänglich gemacht.

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

Fortgeschrittene Benutzer wünschen sich vielleicht, dass verschiedene Ressourcen in verschiedenen Konfigurationen, aber mit demselben effektiven Pfad verwendet werden. Dies kann erreicht werden, indem mehrere Ressourcenverzeichnisse und Dateien mit den gleichen relativen Pfaden innerhalb dieser verschiedenen Verzeichnisse vorhanden sind und MSBuild-Bedingungen verwendet werden, um bedingt verschiedene Dateien in verschiedenen Konfigurationen einzubinden. Zum Beispiel:

<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 – Gibt den Ressourcenpfad explizit an. Ermöglicht "Aliasing"-Dateien, sodass sie als mehrere unterschiedliche Ressourcennamen verfügbar sind.

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

Inhalt

Die normale Content-Buildaktion wird nicht unterstützt (da wir noch nicht herausgefunden haben, wie wir sie ohne einen möglicherweise kostspieligen ersten Ausführungsschritt unterstützen können).

Wenn Sie versuchen, die @(Content) Build-Aktion zu verwenden, wird eine XA0101-Warnung angezeigt.

EmbeddedJar

In einem .NET für Android-Bindungsprojekt bindet die EmbeddedJar-Buildaktion die Java/Kotlin-Bibliothek und bettet die .jar Datei in die Bibliothek ein. Wenn ein .NET für Android-Anwendungsprojekt die Bibliothek nutzt, hat es Zugriff auf die Java/Kotlin-APIs von C# sowie den Java/Kotlin-Code in die endgültige Android-Anwendung.

Sie sollten stattdessen die AndroidLibrary-Buildaktion als Alternative verwenden, z. B.:

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

EmbeddedNativeLibrary

In einer .NET für Android-Klassenbibliothek oder einem Java-Bindungsprojekt bündelt das EmbeddedNativeLibrary-Buildaktion eine systemeigene Bibliothek, z lib/armeabi-v7a/libfoo.so . B. in der Bibliothek. Wenn eine .NET für Android-Anwendung die Bibliothek nutzt, wird die libfoo.so Datei in die endgültige Android-Anwendung aufgenommen.

Sie können die AndroidNativeLibrary-Buildaktion als Alternative verwenden.

EmbeddedReferenceJar

In einem .NET für Android-Bindungsprojekt bettet die EmbeddedReferenceJar-Buildaktion die Datei in die .jar Bibliothek ein, erstellt aber keine C#-Bindung wie EmbeddedJar. Wenn ein .NET für Android-Anwendungsprojekt die Bibliothek nutzt, enthält es den Java/Kotlin-Code in die endgültige Android-Anwendung.

Sie können die AndroidLibrary-Buildaktion als Alternative wie <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

In einem .NET für Android-Bindungsprojekt wird die JavaSourceJar-Buildaktion für .jar Dateien verwendet, die Java-Quellcode enthalten, die Javadoc-Dokumentationskommentare enthalten.

Javadoc wird stattdessen in C#-XML-Dokumentationskommentare im generierten Bindungsquellcode konvertiert.

$(AndroidJavadocVerbosity) steuert, wie ausführlich oder vollständig die importierten Javadoc-Kommentare sind.

Die folgenden MSBuild-Metadaten werden unterstützt:

  • %(CopyrightFile): Hiermit wird ein Pfad zu einer Datei angegeben, die Copyrightinformationen für die Javadoc-Inhalte enthält, die an sämtliche importierte Dokumentation angefügt werden.

  • %(UrlPrefix): Hiermit wird ein URL-Präfix zur Unterstützung einer Verlinkung auf die Onlinedokumentation in der importierten Dokumentation angegeben.

  • %(UrlStyle): Hiermit wird der „Stil“ der URLs angegeben, die für die Verlinkung auf die Onlinedokumentation generiert werden sollen. Derzeit wird nur ein Stil unterstützt: developer.android.com/reference@2020-Nov.

  • %(DocRootUrl): Ein URL-Präfix, das anstelle aller {@docroot} Instanzen in der importierten Dokumentation verwendet werden soll.

LibraryProjectZip

Die LibraryProjectZip-Buildaktion bindet die Java/Kotlin-Bibliothek und bettet die .zip Datei .aar in die Bibliothek ein. Wenn ein .NET für Android-Anwendungsprojekt die Bibliothek nutzt, hat es Zugriff auf die Java/Kotlin-APIs von C# sowie den Java/Kotlin-Code in die endgültige Android-Anwendung.

LinkDescription

Dateien mit einer LinkDescription-Buildaktion werden verwendet, um das Verhalten des Linkers zu steuern.

ProguardConfiguration

Dateien mit einer ProguardConfiguration-Buildaktion enthalten Optionen, mit denen das Verhalten von proguard gesteuert werden kann. Weitere Informationen zu dieser Buildaktion finden Sie unter ProGuard.

Diese Dateien werden ignoriert, sofern die MSBuild-Eigenschaft $(EnableProguard) MSBuild-Eigenschaft ist True.