分享方式：

Xamarin.Android 項目移轉

  • 文章

適用於 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 不支援。

此外，如果使用、 @(EmbeddedJar)或@(LibraryProjectZip)開啟 @(InputJar)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 項目的行為，也可以藉由將 設定$(EnableDefaultItems)false為 false來停用所有預設專案包含行為。 如需詳細資訊，請參閱 工作負載屬性檔案。

運行時間行為

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

連結器

.NET 5+ 具有連結器的新設定：

  • <PublishTrimmed>true</PublishTrimmed>
  • <TrimMode>link</TrimMode>，可啟用成員層級修剪。

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

根據預設，在適用於 Android 專案的 .NET 中， Debug 組建不會使用連結器，而 Release 建置會設定 PublishTrimmed=true 和 TrimMode=link。 TrimMode=copyused 是 .NET SDK 的預設值，但不適用於行動應用程式。 不過，如有需要，您仍然可以加入宣告 TrimMode=copyused 。

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

  • <PublishTrimmed>true</PublishTrimmed>
  • <TrimMode>link</TrimMode>

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

提示

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

預先編譯

$(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，您必須將 與 $(AndroidEnableProfiledAot) 屬性明確設定$(RunAOTCompilation)為 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檔案。true$(BuildingInsideVisualStudio) IDE 會呼叫 Install 部署的目標，以產生 .apk 檔案。 此行為符合 Xamarin.Android。

dotnet run

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

dotnet run --project HelloAndroid.csproj

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

dotnet build HelloAndroid.csproj -t:Run

另請參閱