建構元件

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

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

注意

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

應用程式工件

@(ApplicationArtifact) 包含由封裝、簽署及發佈目標產生的最終應用程式成品檔案。 此項目群組可被自訂的 MSBuild 目標使用,以發現 APK 與 Android App Bundle 的輸出,而無需重新計算最終檔案名稱。 Android 版 .NET 會用 Android 專屬的產物填充此項目組,其他 .NET 行動平台也可以將相同項目名稱用於最終應用產物。

每個項目包含以下中繼資料:

  • %(ApplicationId):最後合併 AndroidManifest.xml的套件名稱。
  • %(ApplicationTitle):來自最終合併資訊清單中的 android:label 值。
  • %(ApplicationName):與 %(ApplicationTitle) 相同的最終資訊清單 android:label 值。
  • %(ApplicationDisplayVersion):來自最終合併資訊清單中的 android:versionName 值。
  • %(ApplicationVersion):來自最終合併資訊清單中的 android:versionCode 值。
  • %(PackageFormat): apk 或 aab。
  • %(Signed):true 當包裹簽收時。
  • %(PackageId):解析後的 Android 套件名稱,也會以 %(ApplicationId) 公開。
  • %(Abi): Android ABI 用於每個 ABI 的 APK 輸出。 此元資料僅針對每個 ABI 的 APK 設定。

最終合併清單對通用應用程式的元資料具有權威性。 其數值優先於專案屬性,如 $(ApplicationId)、 $(ApplicationTitle)、 $(ApplicationDisplayVersion)$(ApplicationVersion)、 。 這同樣適用於自訂清單和設定 $(GenerateApplicationManifest) 為 false的專案。

資源支援的應用程式標籤則以不更改的方式回傳。 例如,android:label 的值為 @string/app_name 時,會產生 ApplicationTitle="@string/app_name" 和 ApplicationName="@string/app_name";建置不會選取或解析出特定地區設定的資源值。

MSBuild 也為每個項目提供知名的元資料。 例如, %(Filename)%(Extension) 是套件檔名, 是 %(FullPath) 完整的套件路徑。

當另一個目標需要直接查詢應用程式產物時,使用該 GetApplicationArtifacts 目標。 附加到 $(GetApplicationArtifactsDependsOn) 的 Targets 會在 Android 版 .NET 填入此項目群組後執行,因此可在 GetApplicationArtifacts 或 Publish 傳回這些項目之前,以額外的中繼資料更新現有項目。

例如:

<Target Name="WriteApplicationArtifacts" AfterTargets="Publish">
  <WriteLinesToFile
      File="$(PublishDir)application-artifacts.txt"
      Lines="@(ApplicationArtifact->'%(FullPath)|%(Filename)%(Extension)|%(PackageFormat)|%(Signed)|%(PackageId)|%(Abi)|%(ApplicationTitle)|%(ApplicationDisplayVersion)|%(ApplicationVersion)')"
      Overwrite="true" />
</Target>

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):符合指定 POM 檔案形式的 Java 函式庫的群組與 artifact 標識符 {GroupId}:{ArtifactId}。
  • %(JavaVersion):符合指定 POM 檔案的 Java 連結庫版本。

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

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

AndroidAsset

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

從 .NET 9 開始,@(AndroidAsset)建置動作也支持附加元數據,用於生成資產套件。 %(AndroidAsset.AssetPack)元數據可以用來自動生成同名的資產包。 只有當$(AndroidPackageFormat)設定為.aab時,才支援此功能。 以下範例將movie2.mp4和movie3.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(Android AAR 資料庫)

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

此 Build 動作的檔案會被像程式庫專案中的內嵌資源一樣來進行處理。 .aar將會擷取至中繼目錄。 然後,任何資產、資源和 .jar 檔案都會包含在適當的專案群組中。

AndroidAotProfile

用於在支援的 .NET 10 及更早版本、使用 Mono 的專案中,為設定檔導向 AOT 提供 Mono AOT 設定檔。

此項目會在…時被消耗 $(AndroidEnableProfiledAot) 是 true。 它不是 MIBC 設定檔或動態 PGO 輸入。

也可以在 Visual Studio 中,透過對包含 Mono AOT 設定檔的檔案設定 AndroidAotProfile 建置動作來使用。

Android App Bundle Meta Data File (安卓應用程式套件元數據檔案)

指定將包含在 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)。 在其他所有方面,它都與 AndroidResource相同。

此動作只能與佈局檔搭配使用:

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

AndroidEnvironment

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

AndroidGradleProject

<AndroidGradleProject> 可用來建置及取用在 Android Studio 或其他地方建立的 Android Gradle 專案輸出。

元數據 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 專案。 如果設置,則由 <AndroidLibrary>、%(Bind) 或 %(Pack) 所支援的元數據將被轉送。 預設值是 true。

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

AndroidJavaLibrary

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

Android忽略的Java依賴項

<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 是一種新的建置動作,可簡化在專案中包含 .jar 和 .aar 檔案的方式。

任何專案都可以指定:

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

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

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

AndroidLintConfig

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

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

AndroidManifestOverlay

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

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

<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。
  • %(AllowInsecureHttp):選用的布林值。 當 %(Repository) 是 http:// URL 時,必須將其設為 true,以允許不安全連線。 預設為 false。 強烈建議使用 HTTPS 以保障供應鏈安全。

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

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

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

AndroidNativeLibrary

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

請注意,由於 Android 支援多個應用程式二進位介面(ABI),因此建構系統必須知道建置原生程式庫的 ABI。 有兩種方式可以指定 ABI:

  1. 路徑「嗅探」。
  2. 使用%(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>

Android原生庫無JNI預加載

本項目群組中所有原生函式庫將免於 JNI 函式庫預載機制。 預設情況下,所有此類函式庫會在應用程式啟動初期的執行時階段載入,以確保其初始化的正確。 然而,在某些情況下,這可能不是理想的行為,而此項目組允許對函式庫進行個別排除,以不加入此過程。

部分必須在應用程式啟動時載入的框架函式庫,若包含在此項目群組中,則不會受到影響。

另請參閱 $(AndroidIgnoreAllJniPreload)

AndroidPackagingOptionsExclude

一組適用於檔案模式匹配的項目,可用於從最終包裝中排除特定項目。 預設值如下所示

<ItemGroup>
	<AndroidPackagingOptionsExclude Include="DebugProbesKt.bin" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('*.kotlin*'))" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('*.jar$'))" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('*.knm$'))" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)[^/]+Main/default/(manifest|linkdata/*)$'))" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)R.txt$'))" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)proguard.txt$'))" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)META-INF/kotlin-project-structure-metadata.json$'))" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)META-INF/proguard/*$'))" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)META-INF/com.android.tools/proguard/*$'))" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)META-INF/com.android.tools/r8*/*$'))" />
	<AndroidPackagingOptionsExclude Include="$([MSBuild]::Escape('^(|root/)META-INF/com/android/build/gradle/aar-metadata.properties$'))" />
</ItemGroup>

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

例如:

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

注意:*、?和.將在BuildApk任務中被替換為適當的檔案匹配模式。

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

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

已在 .NET 7 中新增。

Android 包裝選項包括

一組與檔案 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任務中被替換為適當的檔案匹配模式。

已在 .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) 建置動作會導致 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>

嵌入式原生庫

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

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

EmbeddedReferenceJar

在適用於 Android 的 .NET 系結專案中,EmbeddedReferenceJar 建置動作會將檔案內嵌至連結庫,但不會像 EmbeddedJar.jar 一樣建立 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 連結庫系結,並將 或 .zip 檔案內嵌.aar至連結庫。 當適用於 Android 的 .NET 應用程式項目取用連結庫時,它會從 C# 存取 Java/Kotlin API,並在最終的 Android 應用程式中包含 Java/Kotlin 程式代碼。

鏈結描述

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

ProguardConfiguration

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

這些檔案會被忽略,除非 $(EnableProguard) MSBuild 屬性為 True。

執行階段環境變數

@(RuntimeEnvironmentVariable) 項目可讓環境變數在執行階段透過 dotnet run -e 傳遞給 Android 應用程式。 例如:

dotnet run -e DOTNET_RUN_FOO=TestValue123 -e DOTNET_RUN_BAR=AnotherValue456

這些項目在使用 dotnet run -e NAME=VALUE .NET SDK 時會自動填充,並包含在建置過程中產生的環境檔案中。 每個項目的 Value %(Identity) 是變數名稱, %(Value) 是變數值。

<ItemGroup>
  <RuntimeEnvironmentVariable Include="DOTNET_RUN_FOO" Value="TestValue123" />
</ItemGroup>

此功能僅適用於 Android 應用程式專案,且需要支援RuntimeEnvironmentVariableSupport專案能力的 .NET SDK。

此建置項目於 .NET 10.0.300 SDK 與 .NET 11 中引入。