Migrasi proyek Xamarin.Android

Proyek .NET 8 untuk aplikasi .NET untuk Android mirip dengan contoh berikut:

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

Untuk proyek pustaka, hilangkan $(OutputType) properti sepenuhnya atau tentukan Library sebagai nilai properti.

File konfigurasi .NET

Tidak ada dukungan untuk file konfigurasi seperti Foo.dll.config atau Foo.exe.config di .NET untuk proyek Android. <dllmap> elemen konfigurasi tidak didukung di .NET Core sama sekali, dan jenis elemen lain untuk paket kompatibilitas seperti System.Configuration.ConfigurationManager tidak pernah didukung dalam proyek Android.

Perubahan pada properti MSBuild

Properti $(AndroidSupportedAbis) tidak boleh digunakan:

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

Sebagai gantinya $(AndroidSupportedAbis) , properti harus diganti dengan pengidentifikasi runtime .NET:

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

Untuk informasi selengkapnya tentang pengidentifikasi runtime, lihat Katalog .NET RID.

Tabel berikut ini memperlihatkan properti MSBuild lain yang telah berubah di .NET untuk Android:

Properti	Komentar
$(AndroidUseIntermediateDesignerFile)	True secara default.
$(AndroidBoundExceptionType)	System secara default. Properti ini mengubah jenis pengecualian yang dilemparkan dari berbagai metode agar lebih selaras dengan semantik .NET, dengan biaya kompatibilitas dengan Xamarin.Android. Untuk informasi selengkapnya, lihat Beberapa pengecualian Java yang dibungkus baru menggunakan pengecualian BCL yang berbeda dari jenis BCL terkait.
$(AndroidClassParser)	class-parse secara default. jar2xml tidak didukung.
$(AndroidDexTool)	d8 secara default. dx tidak didukung.
$(AndroidCodegenTarget)	XAJavaInterop1 secara default. XamarinAndroid tidak didukung.
$(AndroidManifest)	Default ke AndroidManifest.xml di akar proyek karena Properties\AssemblyInfo.cs tidak lagi digunakan dalam proyek bergaya SDK. Properties\AndroidManifest.xml juga akan terdeteksi dan digunakan jika ada, untuk memudahkan migrasi.
$(DebugType)	portable secara default. full dan pdbonly tidak didukung.
$(MonoSymbolArchive)	False, karena mono-symbolicate tidak didukung.

Selain itu, jika pengikatan Java diaktifkan dengan @(InputJar), , @(EmbeddedJar)atau @(LibraryProjectZip), maka $(AllowUnsafeBlocks) properti default ke True.

Catatan

Mereferensikan proyek Android Wear dari aplikasi Android tidak didukung.

Perubahan pada AndroidManifest.xml

Dalam proyek Android Xamarin.Android, Java, dan Kotlin, <uses-sdk/> elemen menunjukkan versi Android minimum yang didukung aplikasi Anda, serta versi Android target yang dikompilasi aplikasi Anda:

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

Untuk informasi selengkapnya tentang elemen , <uses-sdk/> lihat dokumentasi Android.

Di aplikasi Android .NET 8, ada properti MSBuild untuk mengatur nilai-nilai ini. Menggunakan properti MSBuild memiliki manfaat lain. Dalam kebanyakan kasus <uses-sdk/> , elemen harus dihapus demi nilai dalam file proyek .csproj Anda:

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

Dalam contoh ini, net8.0-android singkatan dari net8.0-android34.0. Versi .NET yang akan datang akan melacak versi Android terbaru yang tersedia pada saat rilis .NET.

TargetFramework mematakan ke android:targetSdkVersion. Pada waktu build, nilai ini akan secara otomatis disertakan dalam <uses-sdk/> elemen untuk Anda. Manfaat menggunakan TargetFramework dengan cara ini adalah Anda diberi pengikatan C# yang cocok untuk Android API 34 untuk net8.0-android34.0. Android merilis secara independen dari siklus rilis .NET, jadi kami memiliki fleksibilitas untuk memilih net8.0-android35.0 saat pengikatan tersedia untuk rilis Android berikutnya.

Demikian pula, SupportedOSPlatformVersion memetakan ke android:minSdkVersion. Pada waktu build, nilai ini akan secara otomatis disertakan dalam <uses-sdk/> elemen untuk Anda. API Android dihiasi dengan SupportedOSPlatformAttribute sehingga Anda mendapatkan peringatan build untuk memanggil API yang hanya tersedia untuk beberapa versi Android yang dapat dijalankan aplikasi Anda:

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

Untuk menggunakan API ini dengan aman, Anda dapat mendeklarasikan yang lebih tinggi SupportedOSPlatformVersion dalam proyek Anda atau menggunakan API saat IsAndroidVersionAtLeast runtime:

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

Penyertaan file default

Default .NET untuk perilaku globbing file terkait Android didefinisikan dalam AutoImport.props. Perilaku ini dapat dinonaktifkan untuk item Android dengan mengatur $(EnableDefaultAndroidItems) ke false, atau semua perilaku penyertaan item default dapat dinonaktifkan dengan mengatur $(EnableDefaultItems) ke false. Untuk informasi selengkapnya, lihat File props beban kerja.

Perilaku runtime

Ada perubahan perilaku pada String.IndexOf() metode di .NET 5+ pada platform yang berbeda. Untuk informasi selengkapnya, lihat globalisasi .NET dan ICU.

Linker

.NET 9 memiliki pengaturan baru untuk linker:

• <TrimMode>Full</TrimMode>, yang melakukan pemangkasan penuh.

Untuk mengetahui informasi selengkapnya, lihat Opsi pemangkasan.

Di .NET untuk proyek Android secara default, Debug build tidak menggunakan linker, dan Release build diatur PublishTrimmed=true dan TrimMode=partial.

Kompilasi Sebelumnya

$(RunAOTCompilation) adalah properti MSBuild baru untuk mengaktifkan kompilasi Ahead-of-Time (AoT). Ini adalah properti yang sama yang digunakan untuk Blazor WASM. Properti ini $(AotAssemblies) juga memungkinkan AOT, untuk membantu migrasi dari proyek Xamarin.Android ke .NET untuk proyek Android. Namun, properti ini tidak digunakan lagi di .NET 7.

Rilis membangun default ke nilai properti AOT berikut:

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

Ini adalah perilaku ketika $(RunAOTCompilation) properti dan $(AndroidEnableProfiledAot) tidak diatur, dan memilih pengaturan optimal untuk waktu startup dan ukuran aplikasi.

Untuk menonaktifkan AOT, Anda perlu secara eksplisit mengatur $(RunAOTCompilation) properti dan $(AndroidEnableProfiledAot) ke false:

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

Pengodean yang didukung

Jika aplikasi Xamarin.Android Anda menggunakan set kode internasional tertentu, mereka harus ditentukan secara eksplisit dalam file proyek Anda menggunakan Mandroidl18n properti MSBuild, sehingga linker dapat menyertakan sumber daya pendukung. Untuk informasi selengkapnya tentang properti build ini, lihat MAndroidl18n.

Namun, Mandroidl18n properti MSBuild tidak didukung di .NET untuk aplikasi Android. Sebagai gantinya, dukungan disediakan oleh paket System.TextEncoding.CodePages NuGet. Untuk informasi selengkapnya, lihat CodePagesEncodingProvider .

.NET CLI

.NET untuk Android mendukung penggunaan antarmuka baris perintah .NET (.NET CLI) untuk membuat, membangun, menerbitkan, dan menjalankan aplikasi Android.

dotnet new

dotnet new dapat digunakan untuk membuat .NET baru untuk proyek dan item Android menggunakan templat proyek dan templat item yang diberi nama mengikuti pola dan penamaan templat .NET yang ada:

Templat	Nama Pendek	Bahasa	Tag
Templat Aktivitas Android	android-activity	C#	Android
Pengikatan Pustaka Java Android	android-bindinglib	C#	Android
Templat Tata Letak Android	tata letak android	C#	Android
Pustaka Kelas Android	androidlib	C#	Android
Aplikasi Android	android	C#	Android

Contoh berikut menunjukkan penggunaan dotnet new untuk membuat berbagai jenis .NET untuk proyek Android:

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

Setelah .NET untuk proyek Android dibuat, templat item dapat digunakan untuk menambahkan item ke proyek:

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

dotnet build &publish

Untuk .NET untuk Android, dotnet build menghasilkan aplikasi yang dapat dijalankan. Ini berarti membuat .apk file atau .aab selama proses build, dan menyusun ulang tugas MSBuild dari .NET SDK sehingga berjalan selama build. Oleh karena itu, .NET untuk Android melakukan hal berikut selama build:

• Jalankan aapt untuk menghasilkan Resource.designer.cs dan berpotensi memancarkan kesalahan build untuk masalah dalam @(AndroidResource) file.
• Kompilasi kode C#.
• Jalankan target ILLink MSBuild untuk penautan.
• Hasilkan stub java, dan AndroidManifest.xml.
• Kompilasi kode java melalui javac.
• Mengonversi kode java menjadi .dex melalui d8/r8.
• .apk Buat atau .aab dan tanda tangani.

dotnet publish dicadangkan untuk menerbitkan aplikasi untuk Google Play dan mekanisme distribusi lainnya seperti ad-hoc. Ini juga menandatangani .apk atau .aab dengan kunci yang berbeda.

Catatan

Perilaku di dalam ID Akan berbeda. Target Build tidak akan menghasilkan .apk file jika $(BuildingInsideVisualStudio) adalah true. ID Akan memanggil Install target untuk penyebaran, yang akan menghasilkan .apk file. Perilaku ini cocok dengan Xamarin.Android.

dotnet run

dotnet run dapat digunakan untuk meluncurkan aplikasi di perangkat atau emulator melalui --project argumen:

dotnet run --project HelloAndroid.csproj

Atau, Anda dapat menggunakan Run target MSBuild:

dotnet build HelloAndroid.csproj -t:Run

Lihat juga

• Proyek pengikatan