Kode versi adaptif

Anda dapat berpikir tentang menulis kode adaptif mirip dengan bagaimana Anda berpikir tentang membuat antarmuka pengguna adaptif. Rancang kode dasar Anda untuk dijalankan pada versi OS terendah, lalu tambahkan fitur saat Anda mendeteksi bahwa aplikasi Anda berjalan pada versi yang lebih tinggi di mana fitur baru tersedia.

Untuk informasi dasar tentang ApiInformation, kontrak API, dan mengonfigurasi Visual Studio, lihat Aplikasi yang adaptif terhadap versi.

Prasyarat

  • Proyek SDK Aplikasi Windows (dikemas atau tidak dikemas). Lihat Mulai cepat: Membuat aplikasi WinUI 3 pertama Anda.
  • Pemahaman tentang sistem tipe Windows Runtime (WinRT), karena pemeriksaan ApiInformation hanya berlaku untuk tipe dalam namespace Windows.*.

Pemeriksaan runtime API

Gunakan kelas Windows.Foundation.Metadata.ApiInformation dalam suatu kondisi di kode Anda untuk memeriksa ketersediaan API yang ingin Anda panggil. Kondisi ini dievaluasi di mana pun aplikasi Anda dijalankan, tetapi hanya bernilai true pada perangkat yang menyediakan API dan dapat dipanggil.

Important

ApiInformation pemeriksaan hanya berfungsi untuk tipe Windows Runtime dalam namespace Windows.*. Mereka tidak mendeteksi jenis WinUI (Microsoft.UI.Xaml.*) karena jenis tersebut adalah bagian dari paket kerangka kerja SDK Aplikasi Windows, bukan OS, dan tidak terdaftar sebagai metadata WinRT yang ApiInformation dapat dikueri. #if direktif pra-prosesor tidak membantu di sini—mereka dievaluasi pada waktu kompilasi berdasarkan kerangka kerja target, bukan pada runtime berdasarkan versi OS atau SDK yang benar-benar dijalankan aplikasi. Untuk mengaktifkan fitur WinUI secara kondisional, periksa versi SDK Aplikasi Windows yang digunakan saat aplikasi Anda dibangun (lihat Aplikasi adaptif berbasis versi), atau bungkus pemanggilan tersebut dalam blok try/catch dan gunakan fallback jika gagal saat runtime.

Tip

Banyak pemeriksaan API runtime dapat memengaruhi performa aplikasi Anda. Lakukan pemeriksaan sekali dan cache hasilnya, lalu gunakan hasil yang di-cache di seluruh aplikasi Anda.

Opsi kode adaptif

Ada dua cara untuk membuat kode adaptif:

  • Kode aplikasi — Gunakan pemeriksaan API runtime dalam kode di belakang. Ini adalah pendekatan yang direkomendasikan untuk sebagian besar skenario.
  • Pemicu status — Gunakan pemicu status yang dapat diperluas yang mengaktifkan status visual berdasarkan keberadaan API. Gunakan pemicu status saat Anda memiliki perubahan pada properti sederhana atau enum antarversi OS yang terkait dengan status visual.

Contoh: Periksa nilai enum

Contoh ini menunjukkan cara memeriksa apakah nilai enum tertentu ada sebelum menggunakannya. Jika nilai tidak ada, kode akan kembali ke alternatif. EnergySaverStatusdan PowerManager merupakan jenis Windows Runtime asli di Windows.System.Power namespace, sehingga ApiInformation dapat mengkuerinya dengan benar.

if (ApiInformation.IsEnumNamedValuePresent(
    "Windows.System.Power.EnergySaverStatus", "On"))
{
    if (PowerManager.EnergySaverStatus == EnergySaverStatus.On)
    {
        // Reduce background work to save battery.
        ReduceBackgroundActivity();
    }
}
else
{
    // Energy Saver status isn't available on this OS version; skip the check.
}

void ReduceBackgroundActivity()
{
    // Pause non-essential timers, syncs, and animations here.
}

Important

Saat Anda menyimpan hasil pemeriksaan API, gunakan nilai cache tersebut secara konsisten di seluruh aplikasi Anda. Jangan ulangi pemeriksaan di beberapa tempat — periksa sekali, simpan hasilnya, dan referensikan di mana-mana.

Contoh: Periksa metode

Gunakan IsMethodPresent untuk memverifikasi bahwa metode tertentu tersedia sebelum memanggilnya:

DisplayRequest displayRequest = new DisplayRequest();

if (ApiInformation.IsMethodPresent(
    "Windows.System.Display.DisplayRequest", "RequestActive"))
{
    displayRequest.RequestActive();
}

Contoh: Periksa properti

Gunakan IsPropertyPresent untuk memverifikasi bahwa properti tertentu tersedia sebelum membacanya:

if (ApiInformation.IsPropertyPresent(
    "Windows.System.Power.PowerManager", "RemainingChargePercent"))
{
    int chargePercent = PowerManager.RemainingChargePercent;
}

Praktik terbaik

Praktik Guidance
Menggunakan string statis Saat memeriksa nama API dengan ApiInformation, gunakan string hard-coded alih-alih refleksi .NET untuk menghindari masalah pemuatan tipe saat runtime
Hasil cache Lakukan setiap pemeriksaan API sekali saat startup dan simpan hasilnya untuk digunakan kembali
Jaga agar versi minimum tetap rendah Atur Versi Minimum proyek Anda serendah praktis untuk menjangkau audiens terluas, dan gunakan kode adaptif untuk menyalakan fitur pada versi OS yang lebih baru
Uji pada versi minimum Selalu uji pada versi OS minimum yang didukung untuk memverifikasi bahwa jalur fallback berfungsi dengan benar

Konten terkait

  • Last updated on