組建項目

發行項
11/10/2024

建置專案會控制 .NET for Android 應用程式或連結庫專案的建置方式。

這些專案是在 MSBuild ItemGroup 內的項目檔內指定，例如 MyApp.csproj。

注意

在適用於 Android 的 .NET 中，應用程式與系結專案在技術上沒有區別，因此建置專案會在兩者中運作。在實務上，強烈建議建立個別的應用程式和系結專案。主要用於系結專案的建置項目記載於 MSBuild 系結項目項目參考指南中。

AndroidAdditionalJavaManifest

<AndroidAdditionalJavaManifest>會與 Java 相依性解析搭配使用，以指定驗證相依性所需的其他 POM 檔案。這些通常是 Java 連結庫 POM 檔案所參考的父系或匯入 POM 檔案。

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

需要下列 MSBuild 元資料：

%(JavaArtifact)：Java 連結庫的群組和成品標識符，格式符合指定的 POM 檔案 {GroupId}:{ArtifactId}。
%(JavaVersion)：符合指定 POM 檔案的 Java 連結庫版本。

如需詳細資訊，請參閱 Java 相依性解析檔。

此建置動作是在 .NET 9 中引進的。

AndroidAsset

支援 Android 資產，這些檔案會包含在 assets Java Android 專案中的資料夾中。

從 .NET 9 開始，@(AndroidAsset)建置動作也支持產生資產套件的其他元數據。 %(AndroidAsset.AssetPack)元數據可用來自動產生該名稱的資產套件。只有在設定為 .aab時$(AndroidPackageFormat)，才支援此功能。下列範例會將和 movie3.mp4 放在movie2.mp4個別的資產套件中。

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

這項功能可用來在應用程式中包含大型檔案，通常超過 Google Play 的套件大小上限。

如果您有大量資產，使用資產套件可能會更有效率 base 。在此案例中，您會將 ALL 資產更新為位於單一資產套件中，然後使用 AssetPack="base" 元數據來宣告哪些特定資產最終出現在基底 aab 檔案中。您可以使用通配符將大部分資產移至資產套件。

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

在此範例中， movie.mp4 和 some.png 最後會放在 aab 檔案中 base ，而所有其他資產最終都會出現在資產套件中 assets1 。

只有適用於 Android 9 和更新版本的 .NET 才支援額外的元數據。

AndroidAarLibrary

的建置動作 AndroidAarLibrary 應該用來直接參考 .aar 檔案。 Xamarin 元件最常使用此建置動作。也就是包含取得Google Play和其他服務運作所需的檔案參考 .aar 。

此建置動作的檔案會以類似連結庫專案中找到的內嵌資源來處理。 .aar將會擷取至中繼目錄。然後，任何資產、資源和 .jar 檔案都會包含在適當的專案群組中。

AndroidAotProfile

用來提供 AOT 配置檔，以搭配設定檔引導的 AOT 使用。

您也可以從 Visual Studio 使用，方法是將 AndroidAotProfile 建置動作設定為包含 AOT 配置檔的檔案。

AndroidAppBundleMetaDataFile

指定將包含在 Android 應用程式套件組合中做為元數據的檔案。旗標值的格式代表<bundle-path>:<physical-file>bundle-path應用程式套件組合元數據目錄內的檔案位置，而 physical-file 是包含要儲存之原始數據的現有檔案。

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

如需詳細資訊，請參閱 bundletool 檔。

AndroidBoundLayout

指出當屬性設定為時 $(AndroidGenerateLayoutBindings)，配置檔案會為其產生程式false代碼後置。在其他所有方面，它都與 AndroidResource相同。

此動作只能與配置檔案搭配使用：

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

AndroidEnvironment

建置動作為 AndroidEnvironment 的檔案可用來在程序啟動期間初始化環境變數和系統屬性。 AndroidEnvironment 建置動作可套用到多個檔案，這些檔案並不會依特定順序來進行評估 (因此，請勿在多個檔案中指定相同的環境變數或系統屬性)。

AndroidGradleProject

<AndroidGradleProject> 可用來建置及取用在 Android Studio 中建立的 Android Gradle 項目輸出，或是在 Android Studio 中建立的輸出。

元數據 Include 應該指向將用來建置專案的最上層 build.gradle 或 build.gradle.kts 檔案。這會在 Gradle 專案的根目錄中找到，其中也應該包含 gradlew 包裝函式腳本。

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

支援下列 MSBuild 元資料：

%(Configuration)：用來建置或組合指定之專案或專案模組的組態名稱。預設值是 Release。
%(ModuleName)：應該建置之模組或子項目的名稱。預設值為空白。
%(OutputPath)：可以設定為覆寫 Gradle 專案的建置輸出路徑。預設值是 $(IntermediateOutputPath)gradle/%(ModuleName)%(Configuration)-{Hash}。
%(CreateAndroidLibrary)：輸出 AAR 檔案將會新增為 AndroidLibrary 專案。如或 %(Bind) %(Pack) 所支援的<AndroidLibrary>元數據，將會在設定時轉送。預設值是 true。

此建置動作是在 .NET 9 中引進的。

AndroidJavaLibrary

具有建置動作的 AndroidJavaLibrary 檔案為 Java 封存（ .jar 檔案），將會包含在最終 Android 套件中。

AndroidIgnoredJavaDependency

<AndroidIgnoredJavaDependency>與 Java 相依性解析搭配使用。

它用來指定應該忽略的 Java 相依性。如果以 Java 相依性解析無法偵測的方式完成相依性，則可以使用此選項。

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

需要下列 MSBuild 元資料：

%(Version)：符合指定 %(Include)之的 Java 連結庫版本。

如需詳細資訊，請參閱 Java 相依性解析檔。

此建置動作是在 .NET 9 中引進的。

AndroidJavaSource

具有建置動作的 AndroidJavaSource 檔案是將包含在最終 Android 套件中的 Java 原始程式碼。

從 .NET 7 開始，專案目錄中的所有 **\*.java 檔案都會自動具有的 [建置] 動作 AndroidJavaSource，而且會在元件組建之前系結。允許 C# 程式代碼輕鬆地使用檔案記憶體 **\*.java 的類型和成員。

設定 %(AndroidJavaSource.Bind) 為 False 以停用此行為。

AndroidLibrary

AndroidLibrary 是新的建置動作，可簡化專案中包含和.aar檔案的方式.jar。

任何專案都可以指定：

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

上述代碼段的結果對於每個適用於 Android 的 .NET 專案類型有不同的效果：

應用程式和類別庫專案：
- foo.jar對應至 AndroidJavaLibrary。
- bar.aar對應至 AndroidAarLibrary。
Java 系結專案：
- foo.jar對應至 EmbeddedJar。
- foo.jar如果已新增元數據，則會對應至EmbeddedReferenceJar。Bind="false"
- bar.aar會對應至 LibraryProjectZip。

這種簡化表示您可以在任何地方使用 AndroidLibrary 。

AndroidLintConfig

建置動作『AndroidLintConfig』應該與搭配使用 $(AndroidLintEnabled) 屬性。具有此建置動作的檔案會合併在一起，並傳遞給 Android lint 工具。它們應該是包含測試資訊以啟用和停用的 XML 檔案。

如需詳細資訊，請參閱 Lint 文件。

AndroidManifestOverlay

建AndroidManifestOverlay置動作可用來將檔案提供給AndroidManifest.xml指令清單合併工具。具有此建置動作的檔案將會傳遞至指令清單合併，以及來自參考的主要 AndroidManifest.xml 檔案和指令清單檔案。然後，這些會合併到最終指令清單中。

您可以使用此組建動作，根據您的組建組態，將變更和設定提供給您的應用程式。例如，如果您只有在偵錯時才需要有特定許可權，您可以使用重疊在偵錯時插入該許可權。例如，假設有下列重疊檔案內容：

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

您可以使用下列專案來新增偵錯組建的指令清單重疊：

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

AndroidInstallModules

指定安裝應用程式套件組合時， bundletool 命令所安裝的模組。

AndroidMavenLibrary

<AndroidMavenLibrary> 允許指定 Maven 成品，這會自動下載並新增至適用於 Android 系結專案的 .NET。對於裝載於 Maven 中的成品，簡化 .NET for Android 系結的維護相當實用。

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

支援下列 MSBuild 元資料：

%(Version)：所 %(Include)參考之 Java 連結庫的必要版本。
%(Repository)：要使用的選擇性 Maven 存放庫。支援的值為 Central Maven 存放庫的 URL（預設值）、 Google或 https URL。

項目<AndroidMavenLibrary>會轉譯為 AndroidLibrary，因此也支持類似 %(Bind) 或 %(Pack) 的任何元數據<AndroidLibrary>。

如需詳細資訊，請參閱 AndroidMavenLibrary 檔。

此建置動作是在 .NET 9 中引進的。

AndroidNativeLibrary

原生程式庫可藉由將其建置動作設定為 AndroidNativeLibrary 來新增至組建中。

請注意，由於Android支援多個應用程式二進位介面（ABI），因此建置系統必須知道建置原生連結庫的ABI。有兩種方式可以指定 ABI：

路徑「探查」。
%(Abi)使用專案元數據。

路徑探查會使用原生程式庫的父目錄名稱來指定程式庫的目標 ABI。因此，如果您將 lib/armeabi-v7a/libfoo.so 新增至組建，則會以 armeabi-v7a 的形式來「探查」ABI。

項目屬性名稱

Abi – 指定原生連結庫的 ABI。

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

AndroidPackagingOptionsExclude

一組檔案 glob 相容專案，可讓專案從最終套件中排除。預設值如下所示

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

專案可以使用檔案 Blob 字元作為通配符，例如 * 和 ?。不過，這些項目必須是 URL 編碼或使用 $([MSBuild]::Escape(''))。因此 MSBuild 不會嘗試將它們解譯為實際的檔案通配符。

例如：

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

注意：和 *? . 將會在工作中取代BuildApk為適當的檔案 Glob。

如果預設檔案 glob 太嚴格，您可以將下列內容新增至 csproj 來移除它

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

已在 .NET 7 中新增。

AndroidPackagingOptionsInclude

一組檔案 glob 相容專案，可讓專案包含在最終套件中。預設值如下所示

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

專案可以使用檔案 Blob 字元作為通配符，例如 * 和 ?。不過，這些項目必須使用 URL 編碼或『$（[MSBuild]：：Escape（''））』。因此 MSBuild 不會嘗試將它們解譯為實際的檔案通配符。例如：

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

注意：和 *? . 將會在工作中取代BuildApk為適當的檔案 Glob。

已在 .NET 9 中新增。

AndroidResource

所有具有 AndroidResource 建置動作的檔案都會在建置程序進行期間編譯成 Android 資源，並可供透過 $(AndroidResgenFile) 來存取。

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

更進階的使用者或許會想要在不同的組態中擁有不同的資源，但又想具有相同的有效路徑。若要實現此目的，他們可以在手上準備多個資源目錄並在這些不同的目錄內放入具有相同相對路徑的檔案，以及使用 MSBuild 條件，有條件地將不同檔案納入到不同組態中。例如：

<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 – 明確指定資源路徑。允許「別名」檔案，使其可供多個不同的資源名稱使用。

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

Content

不支援一般的 Content 建置動作 (因為我們還沒想出該如何提供支援，而又不會讓首次執行步驟的成本太高)。

嘗試使用 @(Content) 建置動作會導致 XA0101 警告。

EmbeddedJar

在適用於Android的 .NET系結專案中， EmbeddedJar 建置動作會系結 Java/Kotlin 連結庫，並將檔案內嵌 .jar 至連結庫。當適用於 Android 的 .NET 應用程式項目取用連結庫時，它會從 C# 存取 Java/Kotlin API，並在最終的 Android 應用程式中包含 Java/Kotlin 程式代碼。

您應該改用 AndroidLibrary 建置動作作為替代方式，例如：

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

EmbeddedNativeLibrary

在適用於 Android 類別庫或 Java 系結專案的 .NET 中，EmbeddedNativeLibrary 建置動作會將原生連結庫組合在一起，例如lib/armeabi-v7a/libfoo.so連結庫。當適用於 Android 的 .NET 應用程式取用連結庫時， libfoo.so 檔案將會包含在最終的 Android 應用程式中。

您可以使用 AndroidNativeLibrary 建置動作作為替代方案。

EmbeddedReferenceJar

在適用於 Android 的 .NET 系結專案中，EmbeddedReferenceJar 建置動作會將.jar檔案內嵌至連結庫，但不會像 EmbeddedJar 一樣建立 C# 系結。當 .NET for Android 應用程式專案取用連結庫時，它會在最終的 Android 應用程式中包含 Java/Kotlin 程式代碼。

您可以使用 AndroidLibrary 建置動作作為替代專案，例如 <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

在適用於 Android 系結專案的 .NET 中， JavaSourceJar 建置動作用於 .jar 包含 Java 原始碼的檔案上，其中包含 Javadoc 檔批注。

Javadoc 會改為轉換成所產生系結原始程式碼內的 C# XML 檔批注。

$(AndroidJavadocVerbosity) 控制匯入 Javadoc 的「詳細資訊」或「完成」的方式。

支援下列 MSBuild 元資料：

%(CopyrightFile)：檔案的路徑，其中包含 Javadoc 內容的著作權資訊，其會附加至所有匯入的檔。
%(UrlPrefix)：支援連結至匯入檔內在線檔的 URL 前置詞。
%(UrlStyle)：鏈接至在線檔時要產生之 URL 的「樣式」。目前僅支援一種樣式： developer.android.com/reference@2020-Nov。
%(DocRootUrl)：用來取代匯入檔中所有 {@docroot} 實例的 URL 前置詞。

LibraryProjectZip

LibraryProjectZip 建置動作會將 Java/Kotlin 連結庫系結，並將或 .aar 檔案內嵌.zip至連結庫。當適用於 Android 的 .NET 應用程式項目取用連結庫時，它會從 C# 存取 Java/Kotlin API，並在最終的 Android 應用程式中包含 Java/Kotlin 程式代碼。

LinkDescription

具有 LinkDescription 建置動作的檔案可用來控制連結器行為。

ProguardConfiguration

具有 ProguardConfiguration 建置動作的檔案包含可用來控制 proguard 行為的選項。如需此建置動作的詳細資訊，請參閱 ProGuard。

除非 $(EnableProguard) MSBuild 屬性為 True。

共用方式為

組建項目

AndroidAdditionalJavaManifest

AndroidAsset

AndroidAarLibrary

AndroidAotProfile

AndroidAppBundleMetaDataFile

AndroidBoundLayout

AndroidEnvironment

AndroidGradleProject

AndroidJavaLibrary

AndroidIgnoredJavaDependency

AndroidJavaSource

AndroidLibrary

AndroidLintConfig

AndroidManifestOverlay

AndroidInstallModules

AndroidMavenLibrary

AndroidNativeLibrary

項目屬性名稱

AndroidPackagingOptionsExclude

AndroidPackagingOptionsInclude

AndroidResource

Content

EmbeddedJar

EmbeddedNativeLibrary

EmbeddedReferenceJar

JavaSourceJar

LibraryProjectZip

LinkDescription

ProguardConfiguration

意見反應

其他資源