Xamarin.Android 項目移轉

發行項
12/20/2024

適用於 Android 應用程式的 .NET 8 項目類似於下列範例：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-android</TargetFramework>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
</Project>

對於連結庫專案，請完全省略 $(OutputType) 屬性，或指定 Library 為屬性值。

.NET 組態檔

不支援適用於 Android 專案的組態檔，例如 Foo.dll.config 或 Foo.exe.config .NET for Android 專案。 <dllmap>.NET Core 完全不支持組態專案，Android 專案中從未支援過 System.Configuration.ConfigurationManager 等相容性套件的其他項目類型。

MSBuild 屬性的變更

$(AndroidSupportedAbis)不應該使用屬性：

<PropertyGroup>
  <!-- Used in Xamarin.Android projects -->
  <AndroidSupportedAbis>armeabi-v7a;arm64-v8a;x86;x86_64</AndroidSupportedAbis>
</PropertyGroup>

相反地， $(AndroidSupportedAbis) 屬性應該取代為 .NET 運行時間識別碼：

<PropertyGroup>
  <!-- Used in .NET for Android projects -->
  <RuntimeIdentifiers>android-arm;android-arm64;android-x86;android-x64</RuntimeIdentifiers>
</PropertyGroup>

如需運行時間標識碼的詳細資訊，請參閱 .NET RID 目錄。

下表顯示已在 .NET for Android 中變更的其他 MSBuild 屬性：

屬性	註解
`$(AndroidUseIntermediateDesignerFile)`	預設為 `True`。
`$(AndroidBoundExceptionType)`	預設為 `System`。這個屬性會改變從各種方法擲回的例外狀況類型，以更好地配合 .NET 語意，代價是與 Xamarin.Android 相容。如需詳細資訊，請參閱某些新包裝的 Java 例外狀況使用與相關 BCL 類型不同的 BCL 例外狀況。
`$(AndroidClassParser)`	預設為 `class-parse`。不支援 `jar2xml`。
`$(AndroidDexTool)`	預設為 `d8`。不支援 `dx`。
`$(AndroidCodegenTarget)`	預設為 `XAJavaInterop1`。不支援 `XamarinAndroid`。
`$(AndroidManifest)`	預設為 `AndroidManifest.xml` 專案根目錄中的，因為 `Properties\AssemblyInfo.cs` SDK 樣式專案中不再使用。 `Properties\AndroidManifest.xml` 如果存在，也會加以偵測並使用，以簡化移轉。
`$(DebugType)`	預設為 `portable`。不支援`full` 和 `pdbonly` 。
`$(MonoSymbolArchive)`	`False`，因為 `mono-symbolicate` 不支援。

此外，如果使用、 @(InputJar)或@(EmbeddedJar)開啟 @(LibraryProjectZip)Java 系結，則 $(AllowUnsafeBlocks) 屬性預設為 True。

注意

不支援從 Android 應用程式參考 Android Wear 專案。

AndroidManifest.xml的變更

在 Xamarin.Android、Java 和 Kotlin Android 專案中， <uses-sdk/> 元素代表應用程式支援的最低 Android 版本，以及您的應用程式編譯的目標 Android 版本：

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    android:versionCode="1"
    android:versionName="1.0"
    package="com.companyname.myapp">
  <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="33" />
  <application android:icon="@mipmap/ic_launcher" android:label="@string/app_name" android:theme="@style/AppTheme" />
</manifest>

如需元素的詳細資訊 <uses-sdk/> ，請參閱 Android 檔。

在 .NET 8 Android 應用程式中，有 MSBuild 屬性可設定這些值。使用 MSBuild 屬性有其他優點。在大部分情況下， <uses-sdk/> 應該移除元素，以偏向項目 .csproj 檔案中的值：

<Project>
  <PropertyGroup>
    <TargetFramework>net8.0-android</TargetFramework>
    <SupportedOSPlatformVersion>21</SupportedOSPlatformVersion>
  </PropertyGroup>
</Project>

在此範例中， net8.0-android 是的 net8.0-android34.0速記。未來的 .NET 版本將會追蹤 .NET 版本時可用的最新 Android 版本。

TargetFramework 對應至 android:targetSdkVersion。在建置階段，此值會自動包含在 <uses-sdk/> 專案中。以這種方式使用 TargetFramework 的優點是，您會為的Android API 34 net8.0-android34.0提供相符的 C# 系結。 Android 版本與 .NET 發行周期無關，因此我們可以彈性地選擇加入 net8.0-android35.0 系結以供下一個 Android 版本使用。

同樣地，對應 SupportedOSPlatformVersion 至 android:minSdkVersion。在建置階段，此值會自動包含在 <uses-sdk/> 專案中。 Android API 會裝飾 SupportedOSPlatformAttribute 為，因此您會收到呼叫 API 的組建警告，這些 API 僅適用於您的應用程式可執行的部分 Android 版本：

error CA1416: This call site is reachable on 'Android' 21.0 and later. `ConnectivityManager.ActiveNetwork` is only supported on: 'Android' 23.0 and later.

若要安全地使用此 API，您可以在專案中宣告較高的 SupportedOSPlatformVersion 宣告， IsAndroidVersionAtLeast 或在運行時間使用 API：

if (OperatingSystem.IsAndroidVersionAtLeast(23))
{
    // Use the API here
}

默認檔案包含

Android 相關檔案 Globbing 行為的預設 .NET 定義於中 AutoImport.props。您可以藉由將設定$(EnableDefaultAndroidItems)為來停用 Android 項目的行為，也可以藉由將設定false$(EnableDefaultItems)為 false來停用所有預設專案包含行為。如需詳細資訊，請參閱工作負載屬性檔案。

運行時間行為

在不同平臺上，.NET 5+ 中的方法有行為變更 String.IndexOf() 。如需詳細資訊，請參閱 .NET 全球化和ICU。

連結器

.NET 8 有鏈接器的新設定：

<PublishTrimmed>true</PublishTrimmed>
<TrimMode>partial</TrimMode>，其會修剪已選擇加入修剪的元件。

如需詳細資訊，請參閱修剪選項。

根據預設，在適用於 Android 專案的 .NET 中， Debug 組建不會使用連結器，而 Release 建置會設定 PublishTrimmed=true 和 TrimMode=partial。

如果使用舊版 AndroidLinkMode 設定， SdkOnly 和 Full 預設為對等的連結器設定：

<PublishTrimmed>true</PublishTrimmed>
<TrimMode>partial</TrimMode>

使用 AndroidLinkMode=SdkOnly時，只有標示 %(Trimmable) 為的 BCL 和 SDK 元件會連結在成員層級。 AndroidLinkMode=Full 在所有 .NET 元件上設定 %(TrimMode)=partial 。

提示

您應該移轉至新的連結器設定，因為 AndroidLinkMode 設定最終將會淘汰。

.NET 9 有鏈接器的新設定：

<TrimMode>Full</TrimMode>，其會執行完整修剪。

如需詳細資訊，請參閱修剪選項。

根據預設，在適用於 Android 專案的 .NET 中， Debug 組建不會使用連結器，而 Release 建置會設定 PublishTrimmed=true 和 TrimMode=partial。

預先編譯

$(RunAOTCompilation) 是新的 MSBuild 屬性，用於啟用預先編譯（AoT）編譯。這是用於 Blazor WASM 的相同屬性。屬性 $(AotAssemblies) 也會啟用 AOT，以協助從 Xamarin.Android 專案移轉至適用於 Android 專案的 .NET。不過，這個屬性在 .NET 7 中已被取代。

發行組建預設為下列 AOT 屬性值：

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <RunAOTCompilation>true</RunAOTCompilation>
  <AndroidEnableProfiledAot>true</AndroidEnableProfiledAot>
</PropertyGroup>

這是當 $(RunAOTCompilation) 和 $(AndroidEnableProfiledAot) 屬性未設定時的行為，並針對啟動時間和應用程式大小選擇最佳設定。

若要停用 AOT，您必須將與 $(RunAOTCompilation) 屬性明確設定$(AndroidEnableProfiledAot)為 false：

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <RunAOTCompilation>false</RunAOTCompilation>
  <AndroidEnableProfiledAot>false</AndroidEnableProfiledAot>
</PropertyGroup>

支援的編碼

如果您的 Xamarin.Android 應用程式使用特定國際代碼集，則必須使用 Mandroidl18n MSBuild 屬性明確地在專案檔中指定它們，以便連結器可以包含支持的資源。如需此組建屬性的詳細資訊，請參閱 MAndroidl18n。

不過， Mandroidl18n 適用於Android應用程式的 .NET 不支援 MSBuild 屬性。相反地，System.TextEncoding.CodePages NuGet 套件會提供支援。如需詳細資訊，請參閱CodePagesEncodingProvider。

.NET CLI

適用於 Android 的 .NET 支援使用 .NET 命令行介面（.NET CLI）來建立、建置、發佈和執行 Android 應用程式。

dotnet new

dotnet new 可用來使用以現有 .NET 範本和現有 .NET 範本命名的專案範本和專案範本，為 Android 專案和專案建立新的 .NET：

範本	簡短名稱	語言	標籤
Android 活動範本	android-activity	C#	Android
Android Java 連結庫系結	android-bindinglib	C#	Android
Android 版面配置範本	android-layout	C#	Android
Android 類別庫	androidlib	C#	Android
Android 應用程式	android	C#	Android

下列範例示範如何使用 dotnet new 為 Android 專案建立不同類型的 .NET：

dotnet new android            --output MyAndroidApp     --packageName com.mycompany.myandroidapp
dotnet new androidlib         --output MyAndroidLibrary
dotnet new android-bindinglib --output MyJavaBinding

一旦建立適用於 Android 專案的 .NET，專案範本就可以用來將專案新增至專案：

dotnet new android-activity --name LoginActivity --namespace MyAndroidApp
dotnet new android-layout   --name MyLayout      --output Resources/layout

dotnet build & publish

針對適用於 Android 的 .NET， dotnet build 產生可執行的應用程式。這表示在建置程式期間建立 .apk 或 .aab 檔案，並從 .NET SDK 重新排序 MSBuild 工作，以便在建置期間執行。因此，適用於Android的.NET會在建置期間執行下列動作：

執行 aapt 以產生 Resource.designer.cs 並可能針對檔案中 @(AndroidResource) 的問題發出建置錯誤。
編譯 C# 程式代碼。
執行 ILLink MSBuild 目標以進行連結。
產生 java 存根和 AndroidManifest.xml。
透過 javac編譯 Java 程式代碼。
透過 d8/r8 將 Java 程式代碼轉換成 .dex 。
.apk建立或 .aab 並簽署。

dotnet publish 保留用於發佈適用於Google Play的應用程式和其他散發機制，例如臨機操作。它也會 .apk 簽署或 .aab 使用不同的按鍵。

注意

IDE 內的行為會有所不同。如果為，則Build目標不會產生.apk檔案。$(BuildingInsideVisualStudio)true IDE 會呼叫 Install 部署的目標，以產生 .apk 檔案。此行為符合 Xamarin.Android。

dotnet run

dotnet run 可用來透過 --project 自變數在裝置或模擬器上啟動應用程式：

dotnet run --project HelloAndroid.csproj

或者，您可以使用 Run MSBuild 目標：

dotnet build HelloAndroid.csproj -t:Run

另請參閱

系結專案

共用方式為