Bagikan melalui

Mem-build item

  • Artikel

Item build mengontrol bagaimana aplikasi .NET untuk Android atau proyek pustaka dibuat.

Mereka ditentukan dalam file proyek, misalnya MyApp.csproj, dalam ItemGroup MSBuild.

Catatan

Di .NET untuk Android secara teknis tidak ada perbedaan antara aplikasi dan proyek pengikatan, sehingga item build akan berfungsi di keduanya. Dalam praktiknya, sangat disarankan untuk membuat proyek aplikasi dan pengikatan terpisah. Item build yang terutama digunakan dalam proyek pengikatan didokumenkan dalam panduan referensi item proyek pengikatan MSBuild.

AndroidAdditionalJavaManifest

<AndroidAdditionalJavaManifest> digunakan bersama dengan Resolusi Dependensi Java untuk menentukan file POM tambahan yang akan diperlukan untuk memverifikasi dependensi. Ini sering kali merupakan file POM induk atau impor yang direferensikan oleh file POM pustaka Java.

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

Metadata MSBuild berikut diperlukan:

  • %(JavaArtifact): Grup dan id artefak pustaka Java yang cocok dengan file POM yang ditentukan dalam bentuk {GroupId}:{ArtifactId}.
  • %(JavaVersion): Versi pustaka Java yang cocok dengan file POM yang ditentukan.

Lihat dokumentasi Resolusi Dependensi Java untuk detail selengkapnya.

Tindakan build ini diperkenalkan di .NET 9.

AndroidAsset

Mendukung Android Assets, file yang akan disertakan dalam assets folder dalam proyek Java Android.

Dimulai dengan .NET 9 @(AndroidAsset) , tindakan build juga mendukung metadata tambahan untuk menghasilkan Paket Aset. Metadata %(AndroidAsset.AssetPack) dapat digunakan untuk secara otomatis menghasilkan paket aset dari nama tersebut. Fitur ini hanya didukung ketika $(AndroidPackageFormat) diatur ke .aab. Contoh berikut akan menempatkan movie2.mp4 dan movie3.mp4 dalam paket aset terpisah.

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

Fitur ini dapat digunakan untuk menyertakan file besar dalam aplikasi Anda yang biasanya melebihi batas ukuran paket maksimum Google Play.

Jika Anda memiliki sejumlah besar aset, mungkin lebih efisien untuk menggunakan base paket aset. Dalam skenario ini Anda memperbarui SEMUA aset untuk berada dalam satu paket aset lalu menggunakan AssetPack="base" metadata untuk mendeklarasikan aset tertentu mana yang berakhir di file aab dasar. Dengan ini Anda dapat menggunakan kartubebas untuk memindahkan sebagian besar aset ke dalam paket aset.

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

Dalam contoh ini, movie.mp4 dan some.png akan berakhir dalam base file aab, sementara semua aset lainnya akan berakhir dalam assets1 paket aset.

Metadata tambahan hanya didukung di .NET untuk Android 9 ke atas.

AndroidAarLibrary

Tindakan AndroidAarLibrary Build harus digunakan untuk mereferensikan .aar file secara langsung. Tindakan build ini akan paling umum digunakan oleh Komponen Xamarin. Yaitu menyertakan referensi ke .aar file yang diperlukan untuk membuat Google Play dan layanan lain berfungsi.

File dengan tindakan Build ini akan diperlakukan dengan cara yang sama dengan sumber daya tersemat yang ditemukan dalam proyek Pustaka. .aar akan diekstrak ke direktori perantara. Kemudian aset, sumber daya, dan .jar file apa pun akan disertakan dalam grup item yang sesuai.

AndroidAotProfile

Digunakan untuk menyediakan profil AOT, untuk digunakan dengan AOT yang dipandu profil.

Ini juga dapat digunakan dari Visual Studio dengan mengatur AndroidAotProfile tindakan build ke file yang berisi profil AOT.

AndroidAppBundleMetaDataFile

Menentukan file yang akan disertakan sebagai metadata di Android App Bundle. Format nilai bendera adalah <bundle-path>:<physical-file> tempat bundle-path menunjukkan lokasi file di dalam direktori metadata App Bundle, dan physical-file merupakan file yang sudah ada yang berisi data mentah yang akan disimpan.

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

Lihat dokumentasi bundletool untuk detail selengkapnya.

AndroidBoundLayout

Menunjukkan bahwa file tata letak adalah memiliki code-behind yang dihasilkan untuk itu jika $(AndroidGenerateLayoutBindings) properti diatur ke false. Dalam semua aspek lain itu identik dengan AndroidResource.

Tindakan ini hanya dapat digunakan dengan file tata letak:

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

AndroidEnvironment

File dengan tindakan AndroidEnvironment Build digunakan untuk menginisialisasi variabel lingkungan dan properti sistem selama startup proses. Tindakan AndroidEnvironment Build dapat diterapkan ke beberapa file, dan akan dievaluasi tanpa urutan tertentu (jadi jangan tentukan variabel lingkungan atau properti sistem yang sama dalam beberapa file).

AndroidGradleProject

<AndroidGradleProject> dapat digunakan untuk membuat dan menggunakan output proyek Android Gradle yang dibuat di Android Studio atau di tempat lain.

Metadata Include harus menunjuk ke tingkat build.gradle atas atau build.gradle.kts file yang akan digunakan untuk membangun proyek. Ini akan ditemukan di direktori akar proyek Gradle Anda, yang juga harus berisi gradlew skrip pembungkus.

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

Metadata MSBuild berikut didukung:

  • %(Configuration): Nama konfigurasi yang digunakan untuk membangun atau merakit modul proyek atau proyek yang ditentukan. Nilai defaultnya adalah Release.
  • %(ModuleName): Nama modul atau subproyek yang harus dibuat. Nilai default kosong.
  • %(OutputPath): Dapat diatur untuk mengambil alih jalur output build proyek Gradle. Nilai defaultnya adalah $(IntermediateOutputPath)gradle/%(ModuleName)%(Configuration)-{Hash}.
  • %(CreateAndroidLibrary): File AAR output akan ditambahkan sebagai AndroidLibrary ke proyek. Metadata yang didukung oleh <AndroidLibrary> seperti %(Bind) atau %(Pack) akan diteruskan jika diatur. Nilai defaultnya adalah true.

Tindakan build ini diperkenalkan di .NET 9.

AndroidJavaLibrary

File dengan tindakan AndroidJavaLibrary Build adalah Java Archives ( .jar file) yang akan disertakan dalam paket Android akhir.

AndroidIgnoredJavaDependency

<AndroidIgnoredJavaDependency> digunakan bersama dengan Resolusi Dependensi Java.

Ini digunakan untuk menentukan dependensi Java yang harus diabaikan. Ini dapat digunakan jika dependensi akan terpenuhi dengan cara yang tidak dapat dideteksi oleh resolusi dependensi Java.

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

Metadata MSBuild berikut diperlukan:

  • %(Version): Versi pustaka Java yang cocok dengan yang ditentukan %(Include).

Lihat dokumentasi Resolusi Dependensi Java untuk detail selengkapnya.

Tindakan build ini diperkenalkan di .NET 9.

AndroidJavaSource

File dengan tindakan AndroidJavaSource Build adalah kode sumber Java yang akan disertakan dalam paket Android akhir.

Dimulai dengan .NET 7, semua **\*.java file dalam direktori proyek secara otomatis memiliki tindakan Build , AndroidJavaSourcedan akan terikat sebelum build Assembly. Memungkinkan kode C# untuk dengan mudah menggunakan jenis dan anggota yang ada dalam **\*.java file.

Atur %(AndroidJavaSource.Bind) ke False untuk menonaktifkan perilaku ini.

AndroidLibrary

AndroidLibrary adalah tindakan build baru untuk menyederhanakan cara .jar dan .aar file disertakan dalam proyek.

Proyek apa pun dapat menentukan:

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

Hasil cuplikan kode di atas memiliki efek yang berbeda untuk setiap .NET untuk jenis proyek Android:

Penyederhanaan ini berarti Anda dapat menggunakan AndroidLibrary di mana saja.

AndroidLintConfig

Tindakan Build 'AndroidLintConfig' harus digunakan bersama dengan properti $(AndroidLintEnabled). File dengan tindakan build ini akan digabungkan bersama-sama dan diteruskan ke alat android lint . Mereka harus berupa file XML yang berisi informasi tentang pengujian untuk mengaktifkan dan menonaktifkan.

Lihat dokumentasi lint untuk detail selengkapnya.

AndroidManifestOverlay

Tindakan AndroidManifestOverlay build dapat digunakan untuk menyediakan AndroidManifest.xml file ke alat Manifest Merger . File dengan tindakan build ini akan diteruskan ke Manifest Merger bersama dengan file utama AndroidManifest.xml dan file manifes dari referensi. Ini kemudian akan digabungkan ke dalam manifes akhir.

Anda dapat menggunakan tindakan build ini untuk memberikan perubahan dan pengaturan ke aplikasi Anda tergantung pada konfigurasi build Anda. Misalnya, jika Anda hanya perlu memiliki izin tertentu saat penelusuran kesalahan, Anda dapat menggunakan overlay untuk menyuntikkan izin tersebut saat menelusuri kesalahan. Misalnya, mengingat konten file overlay berikut:

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

Anda dapat menggunakan yang berikut ini untuk menambahkan overlay manifes untuk build debug:

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

AndroidInstallModules

Menentukan modul yang diinstal oleh perintah bundletool saat menginstal bundel aplikasi.

AndroidMavenLibrary

<AndroidMavenLibrary> memungkinkan artefak Maven ditentukan yang akan secara otomatis diunduh dan ditambahkan ke proyek pengikatan .NET untuk Android. Ini dapat berguna untuk menyederhanakan pemeliharaan .NET untuk pengikatan Android untuk artefak yang dihosting di Maven.

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

Metadata MSBuild berikut didukung:

  • %(Version): Versi pustaka Java yang diperlukan yang dirujuk oleh %(Include).
  • %(Repository): Repositori Maven opsional untuk digunakan. Nilai yang didukung adalah Central (default), Google, atau https URL ke repositori Maven.

Item <AndroidMavenLibrary> diterjemahkan ke AndroidLibrary, sehingga metadata apa pun yang didukung oleh <AndroidLibrary> seperti %(Bind) atau %(Pack) juga didukung.

Lihat dokumentasi AndroidMavenLibrary untuk detail selengkapnya.

Tindakan build ini diperkenalkan di .NET 9.

AndroidNativeLibrary

Pustaka asli ditambahkan ke build dengan mengatur tindakan Build mereka ke AndroidNativeLibrary.

Perhatikan bahwa karena Android mendukung beberapa Antarmuka Biner Aplikasi (ABI), sistem build harus mengetahui ABI tempat pustaka asli dibuat. Ada dua cara ABI dapat ditentukan:

  1. Jalur "sniffing".
  2. %(Abi) Menggunakan metadata item.

Dengan sniffing jalur, nama direktori induk pustaka asli digunakan untuk menentukan ABI yang ditargetkan pustaka. Dengan demikian, jika Anda menambahkan lib/armeabi-v7a/libfoo.so ke build, maka ABI akan "diendus" sebagai armeabi-v7a.

Nama atribut item

Abi – Menentukan ABI pustaka asli.

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

AndroidPackagingOptionsExclude

Sekumpulan item yang kompatibel dengan glob file yang akan memungkinkan item dikecualikan dari paket akhir. Nilai defaultnya adalah sebagai berikut

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

Item dapat menggunakan karakter blob file untuk kartubebas seperti * dan ?. Namun Item ini HARUS dikodekan URL atau menggunakan $([MSBuild]::Escape('')). Ini sehingga MSBuild tidak mencoba menafsirkannya sebagai kartubebas file aktual.

Misalnya

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

CATATAN: *, ? dan . akan diganti dalam BuildApk tugas dengan glob file yang sesuai.

Jika glob file default terlalu ketat, Anda dapat menghapusnya dengan menambahkan hal berikut ke csproj Anda

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

Ditambahkan dalam .NET 7.

AndroidPackagingOptionsInclude

Sekumpulan item yang kompatibel dengan glob file yang akan memungkinkan item disertakan dari paket akhir. Nilai defaultnya adalah sebagai berikut

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

Item dapat menggunakan karakter blob file untuk kartubebas seperti * dan ?. Namun Item ini HARUS menggunakan pengodean URL atau '$([MSBuild]::Escape(''))'. Ini sehingga MSBuild tidak mencoba menafsirkannya sebagai kartubebas file aktual. Misalnya

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

CATATAN: *, ? dan . akan diganti dalam BuildApk tugas dengan glob file yang sesuai.

Ditambahkan dalam .NET 9.

AndroidResource

Semua file dengan tindakan build AndroidResource dikompilasi ke dalam sumber daya Android selama proses build dan dapat diakses melalui $(AndroidResgenFile).

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

Pengguna yang lebih canggih mungkin ingin memiliki sumber daya yang berbeda yang digunakan dalam konfigurasi yang berbeda tetapi dengan jalur efektif yang sama. Ini dapat dicapai dengan memiliki beberapa direktori sumber daya dan memiliki file dengan jalur relatif yang sama dalam direktori yang berbeda ini, dan menggunakan kondisi MSBuild untuk secara kondisional menyertakan file yang berbeda dalam konfigurasi yang berbeda. Contohnya:

<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 – Menentukan jalur sumber daya secara eksplisit. Memungkinkan file "aliasing" sehingga akan tersedia sebagai beberapa nama sumber daya yang berbeda.

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

Konten

Tindakan Build normal Content tidak didukung (karena kami belum mengetahui cara mendukungnya tanpa langkah eksekusi pertama yang mungkin mahal).

Mencoba menggunakan @(Content) tindakan Build akan menghasilkan peringatan XA0101 .

EmbeddedJar

Dalam proyek pengikatan .NET untuk Android, tindakan build EmbeddedJar mengikat pustaka Java/Kotlin dan menyematkan .jar file ke dalam pustaka. Ketika proyek aplikasi .NET untuk Android menggunakan pustaka, ia akan memiliki akses ke API Java/Kotlin dari C# serta menyertakan kode Java/Kotlin di aplikasi Android akhir.

Sebagai gantinya , Anda harus menggunakan tindakan build AndroidLibrary sebagai alternatif seperti:

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

EmbeddedNativeLibrary

Dalam pustaka kelas .NET untuk Android atau proyek pengikatan Java, tindakan build EmbeddedNativeLibrary membundel pustaka asli seperti lib/armeabi-v7a/libfoo.so ke dalam pustaka. Ketika aplikasi .NET untuk Android menggunakan pustaka, libfoo.so file akan disertakan dalam aplikasi Android akhir.

Anda dapat menggunakan tindakan build AndroidNativeLibrary sebagai alternatif.

EmbeddedReferenceJar

Dalam proyek pengikatan .NET untuk Android, tindakan build EmbeddedReferenceJar menyematkan .jar file ke dalam pustaka tetapi tidak membuat pengikatan C# seperti yang dilakukan EmbeddedJar. Ketika proyek aplikasi .NET untuk Android menggunakan pustaka, itu akan menyertakan kode Java/Kotlin di aplikasi Android akhir.

Anda dapat menggunakan tindakan build AndroidLibrary sebagai alternatif seperti <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

Dalam proyek pengikatan .NET untuk Android, tindakan build JavaSourceJar digunakan pada .jar file yang berisi kode sumber Java, yang berisi komentar dokumentasi Javadoc.

Javadoc akan dikonversi menjadi Komentar Dokumentasi C# XML dalam kode sumber pengikatan yang dihasilkan.

$(AndroidJavadocVerbosity) mengontrol bagaimana "verbose" atau "lengkapi" Javadoc yang diimpor.

Metadata MSBuild berikut ini didukung:

  • %(CopyrightFile): Jalur ke file yang berisi informasi hak cipta untuk konten Javadoc, yang akan ditambahkan ke semua dokumentasi yang diimpor.

  • %(UrlPrefix): Awalan URL untuk mendukung penautan ke dokumentasi online dalam dokumentasi yang diimpor.

  • %(UrlStyle): "Gaya" URL yang akan dihasilkan saat menautkan ke dokumentasi online. Hanya satu gaya yang saat ini didukung: developer.android.com/reference@2020-Nov.

  • %(DocRootUrl): Awalan URL yang akan digunakan sebagai pengganti semua {@docroot} instans dalam dokumentasi yang diimpor.

LibraryProjectZip

Tindakan build LibraryProjectZip mengikat pustaka Java/Kotlin dan menyematkan .zip file atau .aar ke pustaka. Ketika proyek aplikasi .NET untuk Android menggunakan pustaka, ia akan memiliki akses ke API Java/Kotlin dari C# serta menyertakan kode Java/Kotlin di aplikasi Android akhir.

LinkDescription

File dengan tindakan build LinkDescription digunakan untuk mengontrol perilaku linker.

ProguardConfiguration

File dengan tindakan build ProguardConfiguration berisi opsi yang digunakan untuk mengontrol proguard perilaku. Untuk informasi selengkapnya tentang tindakan build ini, lihat ProGuard.

File-file ini diabaikan kecuali jika $(EnableProguard) Properti MSBuild adalah True.