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 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
設定最終將會淘汰。
預先編譯
$(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
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應