Gambaran Umum API Terpadu

Artikel
05/18/2023

API Terpadu Xamarin memungkinkan untuk berbagi kode antara Mac dan iOS dan mendukung aplikasi 32 dan 64-bit dengan biner yang sama. API Terpadu digunakan secara default dalam proyek Xamarin.iOS dan Xamarin.Mac baru.

Penting

API Klasik Xamarin, yang mendahului API Terpadu, telah ditolak.

Versi terakhir Xamarin.iOS yang mendukung API Klasik (monotouch.dll) adalah Xamarin.iOS 9.10.
Xamarin.Mac masih mendukung API Klasik, tetapi tidak lagi diperbarui. Karena tidak digunakan lagi, pengembang harus memindahkan aplikasi mereka ke API Terpadu.

Memperbarui Aplikasi berbasis API Klasik

Ikuti instruksi yang relevan untuk platform Anda:

Tips untuk Memperbarui Kode ke API Terpadu

Terlepas dari aplikasi apa yang Anda migrasikan, lihat tips ini untuk membantu Anda berhasil memperbarui ke API Terpadu.

Pemisahan Pustaka

Mulai saat ini, API kami akan muncul dengan dua cara:

API Klasik: Terbatas pada 32-bit (hanya) dan diekspos dalam monotouch.dll rakitan dan XamMac.dll .
API Terpadu: Mendukung pengembangan 32 dan 64 bit dengan satu API yang tersedia di Xamarin.iOS.dll rakitan dan Xamarin.Mac.dll .

Ini berarti bahwa untuk pengembang Enterprise (tidak menargetkan App Store), Anda dapat terus menggunakan API Klasik yang ada, karena kami akan terus mempertahankannya selamanya, atau Anda dapat meningkatkan ke API baru.

Perubahan Namespace

Untuk mengurangi gesekan untuk berbagi kode antara produk Mac dan iOS kami, kami mengubah namespace layanan untuk API dalam produk.

Kami menghilangkan awalan "MonoTouch" dari produk iOS kami dan "MonoMac" dari produk Mac kami pada jenis data.

Ini membuatnya lebih mudah untuk berbagi kode antara platform Mac dan iOS tanpa menggunakan kompilasi bersyarat dan akan mengurangi kebisingan di bagian atas file kode sumber Anda.

API Klasik: Namespace menggunakan MonoTouch. atau MonoMac. awalan.
API Terpadu: Tidak ada awalan namespace

Default Runtime

API Terpadu secara default menggunakan pengumpul sampah SGen dan sistem Penghitungan Referensi Baru untuk melacak kepemilikan objek. Fitur yang sama ini telah di-port ke Xamarin.Mac.

Ini memecahkan sejumlah masalah yang dihadapi pengembang dengan sistem lama dan juga memudahkan manajemen memori.

Perhatikan bahwa dimungkinkan untuk mengaktifkan New Refcount bahkan untuk API Klasik, tetapi defaultnya konservatif dan tidak mengharuskan pengguna untuk membuat perubahan apa pun. Dengan API Terpadu, kami mengambil kesempatan untuk mengubah default dan memberi pengembang semua peningkatan pada saat yang sama ketika mereka merefaktor dan menguji ulang kode mereka.

Perubahan API

API Terpadu menghapus metode yang tidak digunakan lagi dan ada beberapa instans di mana ada kesalahan ketik dalam nama API ketika terikat ke namespace MonoTouch dan MonoMac asli di API Klasik. Instans ini telah dikoreksi di API Terpadu baru dan perlu diperbarui di aplikasi komponen, iOS, dan Mac Anda. Berikut adalah daftar yang paling umum yang mungkin Anda jalankan:

Nama Metode API Klasik	Nama Metode API Terpadu
`UINavigationController.PushViewControllerAnimated()`	`UINavigationController.PushViewController()`
`UINavigationController.PopViewControllerAnimated()`	`UINavigationController.PopViewController()`
`CGContext.SetRGBFillColor()`	`CGContext.SetFillColor()`
`NetworkReachability.SetCallback()`	`NetworkReachability.SetNotification()`
`CGContext.SetShadowWithColor`	`CGContext.SetShadow`
`UIView.StringSize`	`UIKit.UIStringDrawing.StringSize`

Untuk daftar lengkap perubahan saat beralih dari API Klasik ke API Terpadu, silakan lihat dokumentasi perbedaan API Klasik (monotouch.dll) vs Terpadu (Xamarin.iOS.dll) kami.

Memperbarui ke Terpadu

Beberapa API lama/rusak/tidak digunakan lagi dalam versi klasik tidak tersedia di API Terpadu . Mungkin lebih mudah untuk memperbaiki CS0616 peringatan sebelum memulai peningkatan (manual atau otomatis) Karena Anda akan memiliki [Obsolete] pesan atribut (bagian dari peringatan) untuk memandu Anda ke API yang tepat.

Perhatikan bahwa kami menerbitkan perbedaan perubahan API klasik vs terpadu yang dapat digunakan baik sebelum atau sesudah pembaruan proyek Anda. Masih memperbaiki panggilan usang di Klasik sering kali akan menjadi penghemat waktu (lebih sedikit pencarian dokumentasi).

Ikuti petunjuk ini untuk memperbarui app iOS yang ada, atau app Mac ke API Terpadu. Tinjau sisa halaman ini, dan tips ini untuk informasi tambahan tentang memigrasikan kode Anda.

NuGet

Paket NuGet yang sebelumnya mendukung Xamarin.iOS melalui API Klasik menerbitkan rakitannya menggunakan moniker platform Monotouch10 .

API Terpadu memperkenalkan pengidentifikasi platform baru untuk paket yang kompatibel - Xamarin.iOS10. Paket NuGet yang ada perlu diperbarui untuk menambahkan dukungan untuk platform ini, dengan membangun terhadap API Terpadu.

Penting

Jika Anda memiliki kesalahan dalam formulir "Kesalahan 3 Tidak dapat menyertakan 'monotouch.dll' dan 'Xamarin.iOS.dll' dalam proyek Xamarin.iOS yang sama - 'Xamarin.iOS.dll' dirujuk secara eksplisit, sementara 'monotouch.dll' dirujuk oleh 'xxx, Version=0.0.000, Culture=netral, PublicKeyToken=null'" setelah mengonversi aplikasi Anda ke API Terpadu, biasanya karena memiliki komponen atau Paket NuGet dalam proyek yang belum diperbarui ke API Terpadu. Anda harus menghapus komponen/NuGet yang ada, memperbarui ke versi yang mendukung API Terpadu dan melakukan build bersih.

Jalan menuju 64 Bit

Untuk latar belakang dalam mendukung aplikasi 32 dan 64 bit dan informasi tentang kerangka kerja, lihat Pertimbangan Platform 32 dan 64 bit.

Tipe Data Baru

Pada inti perbedaannya, API Mac dan iOS menggunakan jenis data khusus arsitektur yang selalu 32 bit pada platform 32 bit dan 64 bit pada platform 64 bit.

Misalnya, Objective-C memetakan NSInteger jenis data ke int32_t pada sistem 32 bit dan ke int64_t pada sistem 64 bit.

Untuk mencocokkan perilaku ini, pada API Terpadu kami, kami mengganti penggunaan int sebelumnya (yang di .NET didefinisikan sebagai selalu System.Int32) ke jenis data baru: System.nint. Anda dapat menganggap "n" sebagai arti "asli", sehingga jenis bilangan bulat asli platform.

Kami memperkenalkan nint, nuint dan nfloat juga menyediakan jenis data yang dibangun di atasnya jika perlu.

Untuk mempelajari selengkapnya tentang perubahan jenis data ini, lihat dokumen Jenis Asli.

Cara mendeteksi arsitektur aplikasi iOS

Mungkin ada situasi di mana aplikasi Anda perlu mengetahui apakah aplikasi berjalan pada sistem iOS 32 bit atau 64 bit. Kode berikut dapat digunakan untuk memeriksa arsitektur:

if (IntPtr.Size == 4) {
    Console.WriteLine ("32-bit App");
} else if (IntPtr.Size == 8) {
    Console.WriteLine ("64-bit App");
}

Array dan System.Collections.Generic

Karena pengindeks C# mengharapkan jenis int, Anda harus secara eksplisit melemparkan nint nilai untuk int mengakses elemen dalam koleksi atau array. Contohnya:

public List<string> Names = new List<string>();
...

public string GetName(nint index) {
    return Names[(int)index];
}

Ini adalah perilaku yang diharapkan, karena transmisi dari int ke nint hilang pada 64 bit, konversi implisit tidak dilakukan.

Mengonversi DateTime ke NSDate

Saat menggunakan API Terpadu, konversi implisit ke DateTimeNSDate nilai tidak lagi dilakukan. Nilai-nilai ini harus dikonversi secara eksplisit dari satu jenis ke jenis lainnya. Metode ekstensi berikut dapat digunakan untuk mengotomatiskan proses ini:

public static DateTime NSDateToDateTime(this NSDate date)
{
    // NSDate has a wider range than DateTime, so clip
    // the converted date to DateTime.Min|MaxValue.
    double secs = date.SecondsSinceReferenceDate;
    if (secs < -63113904000)
        return DateTime.MinValue;
    if (secs > 252423993599)
        return DateTime.MaxValue;
    return (DateTime) date;
}

public static NSDate DateTimeToNSDate(this DateTime date)
{
    if (date.Kind == DateTimeKind.Unspecified)
        date = DateTime.SpecifyKind (date, /* DateTimeKind.Local or DateTimeKind.Utc, this depends on each app */)
    return (NSDate) date;
}

API dan Kesalahan Ketik yang tidak digunakan lagi

Di dalam API klasik Xamarin.iOS (monotouch.dll) [Obsolete] atribut digunakan dengan dua cara berbeda:

API iOS yang tidak digunakan lagi: Ini adalah ketika Apple mengisyaratkan kepada Anda untuk berhenti menggunakan API karena digantikan oleh yang lebih baru. API Klasik masih baik-baik saja dan sering diperlukan (jika Anda mendukung versi iOS yang lebih lama). API tersebut [Obsolete] (dan atributnya) disertakan ke dalam rakitan Xamarin.iOS baru.
API yang salah Beberapa API memiliki kesalahan ketik pada namanya.

Untuk rakitan asli (monotouch.dll dan XamMac.dll) kami menyimpan kode lama yang tersedia untuk kompatibilitas tetapi telah dihapus dari rakitan API Terpadu (Xamarin.iOS.dll dan Xamarin.Mac)

NSObject subclasses .ctor(IntPtr)

Setiap NSObject subkelas memiliki konstruktor yang menerima IntPtr. Ini adalah bagaimana kita dapat membuat instans terkelola baru dari handel ObjC asli.

Dalam klasik ini adalah public konstruktor. Namun mudah untuk menyalahgunakan fitur ini dalam kode pengguna, misalnya membuat beberapa instans terkelola untuk satu instans ObjC atau membuat instans terkelola yang tidak akan memiliki status terkelola yang diharapkan (untuk subkelas).

Untuk menghindari masalah IntPtr semacam itu, konstruktor sekarang protected berada dalam API terpadu , untuk digunakan hanya untuk subkelas. Ini akan memastikan API yang benar/aman digunakan untuk membuat instans terkelola dari handel, yaitu.

var label = Runtime.GetNSObject<UILabel> (handle);

API ini akan mengembalikan instans terkelola yang ada (jika sudah ada) atau akan membuat yang baru (jika diperlukan). Ini sudah tersedia di API klasik dan terpadu.

Perhatikan bahwa .ctor(NSObjectFlag) sekarang juga protected tetapi yang ini jarang digunakan di luar subkelas.

NSAction Diganti dengan Tindakan

Dengan API Terpadu, NSAction telah dihapus demi standar .NET Action. Ini adalah peningkatan besar karena Action merupakan jenis .NET umum, sedangkan NSAction khusus untuk Xamarin.iOS. Keduanya melakukan hal yang sama persis, tetapi mereka berbeda dan jenis yang tidak kompatibel dan menghasilkan lebih banyak kode harus ditulis untuk mencapai hasil yang sama.

Misalnya, jika aplikasi Xamarin Anda yang ada menyertakan kode berikut:

UITapGestureRecognizer singleTap = new UITapGestureRecognizer (new NSAction (delegate() {
    ShowDropDownAnimated (tblDataView);
}));

Sekarang dapat diganti dengan lambda sederhana:

UITapGestureRecognizer singleTap = new UITapGestureRecognizer (() => ShowDropDownAnimated(tblDataView));

Sebelumnya itu akan menjadi kesalahan kompilator karena Action tidak dapat ditetapkan ke NSAction, tetapi karena UITapGestureRecognizer sekarang mengambil Action alih-alih NSAction valid di API Terpadu.

Delegasi kustom diganti dengan Tindakan<T>

Dalam terpadu beberapa delegasi .net sederhana (misalnya satu parameter) diganti dengan Action<T>. Mis.

public delegate void NSNotificationHandler (NSNotification notification);

sekarang dapat digunakan sebagai Action<NSNotification>. Ini mempromosikan penggunaan kembali kode dan mengurangi duplikasi kode di dalam Xamarin.iOS dan aplikasi Anda sendiri.

Bool> tugas<diganti dengan Task<Boolean,NSError>>

Dalam klasik ada beberapa API asinkron yang Task<bool>mengembalikan . Namun beberapa dari mereka di mana digunakan ketika merupakan NSError bagian dari tanda tangan, yaitu bool sudah true dan Anda harus menangkap pengecualian untuk mendapatkan NSError.

Karena beberapa kesalahan sangat umum dan nilai pengembalian tidak berguna pola ini diubah dalam terpadu untuk mengembalikan Task<Tuple<Boolean,NSError>>. Ini memungkinkan Anda untuk memeriksa keberhasilan dan kesalahan apa pun yang bisa terjadi selama panggilan asinkron.

NSString vs string

Dalam beberapa kasus, beberapa konstanta harus diubah dari string ke NSString, misalnya. UITableViewCell

Klasik

public virtual string ReuseIdentifier { get; }

Unified

public virtual NSString ReuseIdentifier { get; }

Secara umum kami lebih suka jenis .NET System.String . Namun, terlepas dari pedoman Apple, beberapa API asli membandingkan pointer konstanta (bukan string itu sendiri) dan ini hanya dapat berfungsi ketika kita mengekspos konstanta sebagai NSString.

Objective-C Protokol

MonoTouch asli tidak memiliki dukungan penuh untuk protokol ObjC dan beberapa API yang tidak optimal ditambahkan untuk mendukung skenario yang paling umum. Batasan ini tidak ada lagi tetapi, untuk kompatibilitas mundur, beberapa API disimpan di dalam monotouch.dll dan XamMac.dll.

Batasan ini telah dihapus dan dibersihkan pada API Terpadu. Sebagian besar perubahan akan terlihat seperti ini:

Klasik

public virtual AVAssetResourceLoaderDelegate Delegate { get; }

Unified

public virtual IAVAssetResourceLoaderDelegate Delegate { get; }

I Awalan berarti terpadu mengekspos antarmuka, bukan jenis tertentu, untuk protokol ObjC. Ini akan memudahkan kasus di mana Anda tidak ingin subkelas jenis spesifik yang disediakan Xamarin.iOS.

Ini juga memungkinkan beberapa API menjadi lebih tepat dan mudah digunakan, misalnya:

Klasik

public virtual void SelectionDidChange (NSObject uiTextInput);

Unified

public virtual void SelectionDidChange (IUITextInput uiTextInput);

API tersebut sekarang lebih mudah bagi kami, tanpa mengacu pada dokumentasi, dan penyelesaian kode IDE Anda akan memberi Anda saran yang lebih berguna berdasarkan protokol/antarmuka.

Protokol NSCoding

Pengikatan asli kami menyertakan .ctor(NSCoder) untuk setiap jenis - bahkan jika tidak mendukung NSCoding protokol. Satu Encode(NSCoder) metode hadir dalam NSObject untuk mengodekan objek. Tetapi metode ini hanya akan berfungsi jika instans sesuai dengan protokol NSCoding.

Pada API Terpadu, kami telah memperbaikinya. Rakitan baru hanya akan memiliki .ctor(NSCoder) jika jenisnya sesuai dengan NSCoding. Juga jenis tersebut sekarang memiliki Encode(NSCoder) metode yang sesuai dengan INSCoding antarmuka.

Dampak Rendah: Dalam kebanyakan kasus perubahan ini tidak akan memengaruhi aplikasi sebagai konstruktor lama, dihapus, tidak dapat digunakan.

Tips Lebih Lanjut

Perubahan tambahan yang perlu diperhatikan tercantum dalam tips untuk memperbarui aplikasi ke API Terpadu.

Bagikan melalui

Gambaran Umum API Terpadu

Memperbarui Aplikasi berbasis API Klasik

Tips untuk Memperbarui Kode ke API Terpadu

Pemisahan Pustaka

Perubahan Namespace

Default Runtime

Perubahan API

Memperbarui ke Terpadu

NuGet

Jalan menuju 64 Bit

Tipe Data Baru

Cara mendeteksi arsitektur aplikasi iOS

Array dan System.Collections.Generic

Mengonversi DateTime ke NSDate

API dan Kesalahan Ketik yang tidak digunakan lagi

NSObject subclasses .ctor(IntPtr)

NSAction Diganti dengan Tindakan

Delegasi kustom diganti dengan Tindakan<T>

Bool> tugas<diganti dengan Task<Boolean,NSError>>

NSString vs string

Objective-C Protokol

Protokol NSCoding

Tips Lebih Lanjut

Sumber Daya Tambahan:

Bagikan melalui

Gambaran Umum API Terpadu

Memperbarui Aplikasi berbasis API Klasik

Tips untuk Memperbarui Kode ke API Terpadu

Pemisahan Pustaka

Perubahan Namespace

Default Runtime

Perubahan API

Memperbarui ke Terpadu

NuGet

Jalan menuju 64 Bit

Tipe Data Baru

Cara mendeteksi arsitektur aplikasi iOS

Array dan System.Collections.Generic

Mengonversi DateTime ke NSDate

API dan Kesalahan Ketik yang tidak digunakan lagi

NSObject subclasses .ctor(IntPtr)

NSAction Diganti dengan Tindakan

Delegasi kustom diganti dengan Tindakan<T>

Bool> tugas<diganti dengan Task<Boolean,NSError>>

NSString vs string

Objective-C Protokol

Protokol NSCoding

Tips Lebih Lanjut

Link Terkait

Sumber Daya Tambahan: