Pemrograman dengan SDK ekstensi

Untuk memahami bagaimana Windows 10 memungkinkan aplikasi Platform Windows Universal (UWP) Anda untuk paling efektif menargetkan kelas perangkat yang berbeda, topik ini menjelaskan konsep berikut.

• Rangkaian perangkat
• SDK Ekstensi
• Kontrak API

Kami juga menunjukkan cara menggunakannya dalam pemrograman Anda.

Video—Pengantar UWP dan keluarga perangkat

Keluarga perangkat, dan keluarga perangkat target aplikasi Anda

Keluarga perangkat mengidentifikasi API, karakteristik sistem, dan perilaku yang dapat Anda harapkan di seluruh kelas perangkat.

Keluarga perangkat adalah fondasi sistem operasi (OS). Misalnya, PC dan tablet menjalankan OS edisi desktop, dan itu didasarkan pada keluarga perangkat Desktop. Perangkat IoT menjalankan OS edisi IoT, yang didasarkan pada keluarga perangkat IoT.

Setiap keluarga perangkat anak menambahkan API-nya sendiri ke API yang diwarisinya dari keluarga perangkat Universal. Penyatuan API yang dihasilkan dalam keluarga perangkat anak dijamin hadir dalam OS yang didasarkan pada keluarga perangkat tersebut, dan oleh karena itu pada setiap perangkat yang menjalankan OS tersebut.

Keputusan tentang keluarga perangkat (atau keluarga) mana yang akan ditargetkan aplikasi Anda adalah milik Anda untuk dibuat. Dan keputusan tersebut berdampak pada aplikasi Anda dengan cara-cara penting ini. Ini menentukan

• keluarga perangkat yang ditawarkan aplikasi Anda untuk diinstal dari Microsoft Store (dan akibatnya faktor formulir yang perlu Anda pertimbangkan saat merancang UI aplikasi), dan
• set API tertentu yang dapat Anda mengandalkan hadir di perangkat yang menjalankan aplikasi Anda (perangkat host).

Dengan mengandalkan hadir, kami berarti Anda dapat memanggil API tersebut tanpa terlebih dahulu perlu menguji untuk melihat apakah api tersebut ada di perangkat host. Keluarga perangkat yang Anda targetkan memberikan jaminan tersebut (jaminan yang berbeda untuk keluarga perangkat yang berbeda).

Mengonfigurasi keluarga perangkat target Anda

Dalam file sumber manifes paket aplikasi Anda ( Package.appxmanifest file ), elemen TargetDeviceFamily memiliki atribut Name . Nilai atribut tersebut adalah nama keluarga perangkat yang ditargetkan aplikasi Anda. Nilai berikut ini valid.

• Windows.Desktop
• Windows.Holographic
• Windows.IoT
• Windows.Mobile
• Windows.Team
• Windows.Universal
• Windows.Xbox

Secara default, aplikasi UWP Anda menargetkan keluarga perangkat Universal (yaitu, Microsoft Visual Studio menentukan Windows.Universal untuk TargetDeviceFamily). Dan itu berarti bahwa aplikasi Anda dapat diinstal di semua perangkat Windows 10, dan Anda dapat mengandalkan serangkaian API inti besar yang ada di perangkat host. Aplikasi seperti itu harus memiliki UI yang sangat adaptif, dan kemampuan input yang komprehensif, karena dapat berjalan pada berbagai perangkat. Lihat Pratinjau UI Anda pada ukuran layar yang berbeda nanti dalam topik ini.

Jika Anda ingin membatasi keluarga perangkat yang ditawarkan aplikasi Anda untuk diinstal dari Microsoft Store, maka Anda dapat memilih untuk menargetkan keluarga perangkat yang berbeda—misalnya, keluarga perangkat Desktop (Windows.Desktop), atau keluarga perangkat IoT (Windows.IoT). Tentu saja, akan ada lebih sedikit perangkat yang dapat menghosting aplikasi Anda, tetapi Anda akan dapat mengandalkan serangkaian API yang lebih besar yang ada di perangkat tersebut (yang akan diatur dalam keluarga perangkat Universal, ditambah yang ditetapkan dalam keluarga perangkat target). Aplikasi seperti itu biasanya hanya perlu adaptif sedang; ini bisa agak khusus dalam UI dan kemampuan inputnya, karena hanya dapat berjalan pada jenis perangkat tertentu.

Mengonfigurasi versi keluarga perangkat target Anda

API ditambahkan ke Windows dari waktu ke waktu, sehingga dimensi lain untuk memilih keluarga perangkat memutuskan versi (atau versi) mana yang akan ditargetkan. Beberapa jenis proyek di Visual Studio memiliki halaman properti tempat Anda dapat mengonfigurasi versi platform target Anda. Tetapi untuk semua jenis proyek Anda dapat mengonfigurasi versi platform target Anda tepat dalam file proyek.

Berikut adalah contoh yang memperlihatkan properti yang relevan dalam file proyek.

<!-- MyProject.Xxxproj -->
<PropertyGroup Label="Globals">
    ...
    <WindowsTargetPlatformVersion>10.0.19041.0</WindowsTargetPlatformVersion>
    <WindowsTargetPlatformMinVersion>10.0.17134.0</WindowsTargetPlatformMinVersion>
    ...
</PropertyGroup>

Pada waktu build, nilai-nilai ini (bersama dengan nilai TargetDeviceFamily@Name dari Package.appxmanifest) disalin ke dalam AppxManifest.xml file yang dihasilkan di folder output proyek Anda. Berikut adalah contoh.

<!-- AppxManifest.xml -->
<Dependencies>
    <TargetDeviceFamily Name="Windows.Universal"
        MaxVersionTested="10.0.19041.0"
        MinVersion="10.0.17134.0" />
    ...
</Dependencies>

MaxVersionTested menentukan versi maksimum keluarga perangkat yang ditargetkan aplikasi yang telah Anda uji. Dan MinVersion menentukan versi minimum keluarga perangkat yang ditargetkan aplikasi Anda. Untuk detail selengkapnya, lihat TargetDeviceFamily.

Ekstensi SDK, dan cara mereferensikannya

Jika dalam proyek Visual Studio Anda, Anda mengubah target dari keluarga perangkat Universal ke beberapa keluarga perangkat lain, maka Anda perlu menambahkan referensi ke SDK ekstensi yang sesuai dengan keluarga perangkat tersebut. Itu membuat API dalam keluarga perangkat tersebut tersedia untuk proyek Anda.

Jika, misalnya, Anda menargetkan keluarga perangkat IoT, maka (dengan simpul proyek yang dipilih di Penjelajah Solusi) klikTambahkan ReferensiProyek>...>Windows> UniversalEkstensi, dan pilih versi Ekstensi Windows IoT yang sesuai untuk UWP. Misalnya, jika API IoT terbaru yang ingin Anda panggil diperkenalkan dalam versi 10.0.17134.0, pilih versi tersebut.

Dan ini adalah bagaimana referensi itu akan terlihat dalam file proyek Anda.

<ItemGroup>
    <SDKReference Include="WindowsIoT, Version=10.0.17134.0" />
</ItemGroup>

Nama dan nomor versi cocok dengan folder di lokasi SDK Anda yang terinstal. Misalnya, informasi di atas cocok dengan folder bernama

\Program Files (x86)\Windows Kits\10\Extension SDKs\WindowsIoT\10.0.17134.0

SDK ekstensi lainnya termasuk Ekstensi Desktop Windows untuk UWP, Ekstensi Windows Mobile untuk UWP, dan Ekstensi Tim Windows untuk UWP.

Jika Anda membiarkan aplikasi menargetkan keluarga perangkat Universal, maka Anda masih dapat menambahkan referensi ke satu atau beberapa SDK ekstensi. Referensi SDK ekstensi mana pun yang berisi API tambahan yang ingin Anda panggil. Ingat, Anda menargetkan keluarga perangkat Universal, jadi itu adalah satu-satunya API yang dapat Anda mengandalkan hadir. Untuk API dalam ekstensi SDK yang Anda referensikan, Anda harus menguji bahwa mereka ada di perangkat host pada waktu proses sebelum Anda memanggilnya (detail selengkapnya di bagian Menulis kode nanti dalam topik ini). Tentu saja, Anda tidak perlu melakukan pengujian tersebut untuk API dalam keluarga perangkat Universal. Ini adalah skenario terbaik dari kedua dunia yang kami sebutkan di bagian sebelumnya.

Dengan menggunakan SDK ekstensi, Anda dapat menargetkan API unik dari keluarga perangkat tertentu, dan dengan demikian mengakses kemampuan khusus mereka. Anda dapat melakukannya apakah Anda menargetkan keluarga perangkat yang sesuai atau tidak.

Kontrak API, dan cara mencarinya

API dalam keluarga perangkat dibagi menjadi beberapa grup yang dikenal sebagai kontrak API. Ketika versi baru dari keluarga perangkat dirilis, versi baru itu pada dasarnya hanya mewakili koleksi versi baru dari semua kontrak API yang termasuk dalam keluarga perangkat tersebut.

Misalnya, kontrak API bernama Windows.Foundation.UniversalApiContract berada pada versi 6.0 saat dikirim dengan versi 10.0.17134.0 dari keluarga perangkat Universal. Tetapi kontrak yang sama berada pada versi 10.0 ketika dikirim dengan versi 10.0.19041.0 dari keluarga perangkat yang sama.

Mencari kontrak API untuk API WinRT

Mari kita lihat bagaimana Anda dapat mencari nama kontrak API dan nomor versi untuk API Windows Runtime tertentu. Di bagian Menulis kode nanti dalam topik ini, Anda akan melihat mengapa dan bagaimana Anda dapat menggunakan informasi tersebut.

Sebagai contoh pertama, kita akan mengambil metode StorageFolder.TryGetChangeTracker . Di bagian persyaratan Windows 10 dari topik itu, kita dapat melihat bahwa StorageFolder.TryGetChangeTracker pertama kali diperkenalkan dengan versi 6.0 dari Windows.Foundation.UniversalApiContract.

Selanjutnya, mari kita lihat topik untuk metode StorageFolder.TryGetItemAsync . Tidak ada bagian persyaratan Windows 10 dalam topik tersebut. Sebagai gantinya, lihat topik untuk kelas StorageFolder itu sendiri. Bagian persyaratan Windows 10 di sana memiliki jawabannya. Karena topik StorageFolder.TryGetItemAsync tidak mengatakan hal yang berbeda, kita dapat menyimpulkan bahwa topik tersebut berbagi persyaratannya dengan kelas induknya. Jadi StorageFolder.TryGetItemAsync pertama kali diperkenalkan dengan versi 1.0 dari Windows.Foundation.UniversalApiContract.

Cara memilih keluarga perangkat yang akan ditargetkan

Berikut adalah beberapa pertimbangan untuk membantu Anda memutuskan keluarga perangkat mana yang akan ditargetkan. Untuk detail selengkapnya, lihat TargetDeviceFamily.

Memaksimalkan jangkauan aplikasi Anda

Untuk mencapai berbagai jenis perangkat maksimum dengan aplikasi Anda, dan akibatnya untuk menjalankannya di perangkat sebanyak mungkin, aplikasi Anda harus menargetkan keluarga perangkat Universal. Secara khusus, seperti yang telah kita lihat, Anda akan menargetkan berbagai versi keluarga perangkat Universal.

Membatasi aplikasi Anda ke satu jenis perangkat

Anda mungkin tidak ingin aplikasi berjalan pada berbagai faktor bentuk perangkat; mungkin khusus untuk PC desktop, atau untuk konsol Xbox. Dalam hal ini, Anda dapat memilih untuk menargetkan salah satu keluarga perangkat anak.

Membatasi aplikasi Anda ke subset semua perangkat yang mungkin

Alih-alih menargetkan keluarga perangkat Universal, atau menargetkan salah satu keluarga perangkat anak, Anda dapat menargetkan dua (atau lebih) keluarga perangkat anak. Menargetkan Desktop dan Seluler mungkin masuk akal untuk aplikasi Anda. Atau Desktop dan Tim. Atau Desktop, Seluler, dan Tim, dan sebagainya.

Mengecualikan dukungan untuk versi tertentu dari keluarga perangkat

Dalam kasus yang jarang terjadi, Anda mungkin ingin aplikasi Anda berjalan di mana saja kecuali pada perangkat dengan versi tertentu dari keluarga perangkat tertentu. Misalnya, aplikasi Anda menargetkan versi 10.0.x.0 dari keluarga perangkat universal. Saat versi sistem operasi berubah di masa mendatang—katakanlah ke 10.0.x.2—pada saat itu, Anda dapat menentukan bahwa aplikasi Anda berjalan di mana-mana kecuali versi 10.0.x.1 dari Xbox dengan menargetkan aplikasi Anda ke 10.0.x.0 dari Universal dan 10.0.x.2 dari Xbox. Aplikasi Anda kemudian tidak akan tersedia untuk kumpulan versi keluarga perangkat dalam Xbox 10.0.x.1 (inklusif) dan yang lebih lama.

Menulis kode

Sebagian besar kode Anda akan universal dalam arti bahwa kode tersebut akan berjalan dengan cara yang sama pada setiap perangkat. Tetapi untuk kode yang disesuaikan dengan keluarga perangkat tertentu, Anda akan memiliki opsi untuk menggunakan kode adaptif. Mari kita pertimbangkan kasus yang berbeda ini.

Memanggil API yang diimplementasikan oleh keluarga perangkat target Anda

Setiap kali Anda ingin memanggil API di aplikasi UWP, Anda akan ingin tahu apakah API diimplementasikan oleh keluarga perangkat yang ditargetkan oleh aplikasi Anda atau tidak. Visual Studio IntelliSense menampilkan API dalam keluarga perangkat Universal ditambah API yang tersedia untuk SDK ekstensi apa pun yang telah Anda referensikan.

Dokumentasi referensi Windows Runtime API memberi tahu Anda keluarga perangkat mana yang menjadi bagian dari API. Jika Anda mencari topik referensi API untuk WINDOWS Runtime API dan mencari bagian persyaratan Windows 10, maka Anda akan melihat apa keluarga perangkat yang menerapkan, dan versi keluarga perangkat tersebut tempat API pertama kali muncul. Jika tidak ada bagian persyaratan Windows 10, lihat kelas pemilik anggota, dan lihat info di bagian persyaratan Windows 10 di sana. Info itu juga akan berlaku untuk anggota.

Memanggil API yang tidak diimplementasikan oleh keluarga perangkat target Anda

Akan ada kasus ketika Anda ingin memanggil API di SDK ekstensi yang telah Anda referensikan, tetapi API tersebut bukan bagian dari keluarga perangkat yang Anda targetkan.

Misalnya, Anda mungkin menargetkan keluarga perangkat Universal, tetapi ada API desktop yang ingin Anda panggil setiap kali aplikasi Anda berjalan di perangkat desktop.

Atau aplikasi Anda mungkin mendukung versi awal keluarga perangkat, tetapi ada API yang ingin Anda panggil yang hanya tersedia dalam versi terbaru dari keluarga perangkat yang sama.

Dalam kasus seperti itu, Anda dapat memilih untuk menulis kode adaptif sehingga Anda dapat memanggil API tersebut dengan aman. Bagian berikutnya menunjukkan caranya.

Menulis kode adaptif dengan menggunakan ApiInformation

Ada dua langkah yang terlibat dalam menggunakan kode adaptif untuk memanggil API secara kondisional. Langkah pertama adalah membuat API tersedia untuk proyek Anda. Untuk melakukannya, tambahkan referensi ke SDK ekstensi yang mewakili keluarga perangkat yang memiliki API.

Langkah kedua adalah menggunakan kelas ApiInformation dalam kondisi dalam kode Anda untuk menguji keberadaan API yang ingin Anda panggil. Kondisi ini dievaluasi di mana pun dan kapan pun aplikasi Anda berjalan. Tetapi mengevaluasi hanya pada true perangkat tempat API ada dan oleh karena itu tersedia untuk dipanggil.

Jika Anda hanya ingin memanggil sejumlah kecil API, maka Anda dapat menggunakan metode ApiInformation.IsTypePresent seperti ini.

// Cache the value, instead of querying it multiple times.
bool isHardwareButtonsAPIPresent =
    Windows.Foundation.Metadata.ApiInformation.IsTypePresent("Windows.Phone.UI.Input.HardwareButtons");

if (isHardwareButtonsAPIPresent)
{
    Windows.Phone.UI.Input.HardwareButtons.CameraPressed += HardwareButtons_CameraPressed;
}

Dalam hal ini, ada keyakinan bahwa kehadiran kelas HardwareButtons menyiratkan keberadaan peristiwa CameraPressed , karena kelas dan anggota memiliki info persyaratan yang sama. Tetapi pada waktunya, anggota baru akan ditambahkan ke kelas yang sudah diperkenalkan, dan anggota tersebut nantinya akan diperkenalkan dalam nomor versi. Dalam kasus seperti itu, alih-alih menggunakan IsTypePresent, Anda dapat menguji keberadaan masing-masing anggota dengan menggunakan IsEventPresent, IsMethodPresent, IsPropertyPresent, dan metode serupa. Berikut adalah contoh.

bool isHardwareButtons_CameraPressedAPIPresent =
    Windows.Foundation.Metadata.ApiInformation.IsEventPresent
        ("Windows.Phone.UI.Input.HardwareButtons", "CameraPressed");

Seperti yang kita ketahui, kumpulan API dalam keluarga perangkat dipecah lebih lanjut menjadi subdivisi yang dikenal sebagai kontrak API. Anda dapat menggunakan metode ApiInformation.IsApiContractPresent untuk menguji keberadaan kontrak API. Ini adalah cara yang efisien untuk mengeksekusi satu kondisi untuk mengetahui keberadaan atau sejumlah besar API yang semuanya termasuk dalam versi kontrak API yang sama.

Untuk informasi tentang cara menentukan kontrak API yang pertama kali memperkenalkan API yang menarik, lihat bagian Mencari kontrak API untuk API WinRT sebelumnya dalam topik ini.

Setelah memiliki info tersebut, Anda dapat menyambungkannya ke kode adaptif Anda. Misalnya, jika nama kontrak API adalah Windows.Devices.Scanners.ScannerDeviceContract, dan nomor versi utama dan minornya masing-masing adalah 1 dan 0, maka kondisi Anda akan terlihat seperti contoh di bawah ini.

bool isWindows_Devices_Scanners_ScannerDeviceContract_1_0Present =
    Windows.Foundation.Metadata.ApiInformation.IsApiContractPresent
        ("Windows.Devices.Scanners.ScannerDeviceContract", 1, 0);

Pratinjau UI Anda pada ukuran layar yang berbeda

Kami menyarankan agar Anda memaksimalkan jangkauan aplikasi Anda. Tetapi bahkan jika Anda hanya menargetkan satu jenis faktor bentuk perangkat, kemungkinan masih ada berbagai ukuran layar yang dapat ditampilkan aplikasi Anda.

Saat Anda siap untuk melihat tampilan dan tata letak aplikasi pada ukuran layar tertentu, gunakan toolbar pratinjau perangkat di Visual Studio untuk mempratinjau UI Anda di perangkat seluler kecil atau sedang, di PC, atau di layar TV besar. Dengan demikian, jika Anda telah menggunakan fitur tata letak adaptif XAML (lihat Tata letak adaptif dengan status visual dan pemicu status), maka Anda juga dapat mengujinya.

Anda tidak perlu membuat keputusan terlebih dahulu tentang setiap jenis perangkat yang akan Anda dukung. Anda dapat menambahkan ukuran perangkat tambahan ke proyek Anda kapan saja.

Lihat juga

• SDK ekstensi keluarga perangkat dan kontrak API
• TargetDeviceFamily
• Apa itu aplikasi Platform Windows Universal (UWP)
• Aplikasi adaptif versi