Bagikan melalui

Porting proyek Windows Runtime 8.x ke proyek UWP

  • Artikel

Anda memiliki dua opsi saat memulai proses porting. Salah satunya adalah mengedit salinan file proyek yang ada, termasuk manifes paket aplikasi (untuk opsi itu, lihat info tentang memperbarui file proyek Anda di Memigrasikan aplikasi ke Platform Windows Universal (UWP)). Opsi lainnya adalah membuat proyek Windows 10 baru di Visual Studio dan menyalin file Anda ke dalamnya. Bagian pertama dalam topik ini menjelaskan opsi kedua tersebut, tetapi topik lainnya memiliki info tambahan yang berlaku untuk kedua opsi. Anda juga dapat memilih untuk menyimpan proyek Windows 10 baru Anda dalam solusi yang sama dengan proyek yang ada dan berbagi file kode sumber menggunakan proyek bersama. Atau, Anda dapat menyimpan proyek baru dalam solusinya sendiri dan berbagi file kode sumber menggunakan fitur file tertaut di Visual Studio.

Membuat proyek dan menyalin file ke dalamnya

Langkah-langkah ini berfokus pada opsi untuk membuat proyek Windows 10 baru di Visual Studio dan menyalin file Anda ke dalamnya. Beberapa spesifikasi seputar berapa banyak proyek yang Anda buat, dan file mana yang Anda salin, akan tergantung pada faktor dan keputusan yang dijelaskan di Jika Anda memiliki aplikasi Universal 8.1 dan bagian yang mengikutinya. Langkah-langkah ini mengasumsikan kasus paling sederhana.

  1. Luncurkan Microsoft Visual Studio 2015 dan buat proyek Aplikasi Kosong (Windows Universal) baru. Untuk informasi selengkapnya, lihat Jumpstart aplikasi Windows Runtime 8.x Anda menggunakan templat (C#, C++, Visual Basic). Proyek baru Anda membuat paket aplikasi (file appx) yang akan berjalan di semua keluarga perangkat.
  2. Dalam proyek aplikasi Universal 8.1 Anda, identifikasi semua file kode sumber dan file aset visual yang ingin Anda gunakan kembali. Menggunakan File Explorer, menyalin model data, melihat model, aset visual, Kamus Sumber Daya, struktur folder, dan apa pun yang ingin Anda gunakan kembali, ke proyek baru Anda. Salin atau buat sub-folder pada disk seperlunya.
  3. Salin tampilan (misalnya, MainPage.xaml dan MainPage.xaml.cs) ke dalam proyek baru juga. Sekali lagi, buat sub-folder baru seperlunya, dan hapus tampilan yang ada dari proyek. Tetapi, sebelum Anda menulis berlebihan atau menghapus tampilan yang dihasilkan Visual Studio, simpan salinan karena mungkin berguna untuk merujuknya nanti. Fase pertama porting aplikasi Universal 8.1 berfokus pada membuatnya terlihat baik dan bekerja dengan baik pada satu keluarga perangkat. Nantinya, Anda akan mengalihkan perhatian untuk memastikan tampilan beradaptasi dengan baik dengan semua faktor bentuk, dan secara opsional untuk menambahkan kode adaptif apa pun untuk mendapatkan hasil maksimal dari keluarga perangkat tertentu.
  4. Di Penjelajah Solusi, pastikan Tampilkan Semua File diaktifkan. Pilih file yang Anda salin, klik kanan, dan klik Sertakan Dalam Proyek. Ini akan secara otomatis menyertakan folder yang berisinya. Anda kemudian dapat mengalihkan Tampilkan Semua File nonaktif jika mau. Alur kerja alternatif, jika mau, adalah menggunakan perintah Tambahkan Item yang Ada, setelah membuat sub-folder yang diperlukan di Visual Studio Penjelajah Solusi. Periksa kembali apakah aset visual Anda memiliki Tindakan Build yang diatur ke Konten dan Salin ke Direktori Output diatur ke Jangan salin.
  5. Anda kemungkinan akan melihat beberapa kesalahan build pada tahap ini. Tetapi, jika Anda tahu apa yang perlu Anda ubah, maka Anda dapat menggunakan perintah Temukan dan Ganti Visual Studio untuk membuat perubahan massal pada kode sumber Anda; dan di editor kode imperatif di Visual Studio, gunakan perintah Atasi dan Atur Penggunaan pada menu konteks untuk perubahan yang lebih ditargetkan.

Memaksimalkan markup dan penggunaan kembali kode

Anda akan menemukan bahwa pemfaktoran ulang sedikit, dan/atau menambahkan kode adaptif (yang dijelaskan di bawah), akan memungkinkan Anda memaksimalkan markup dan kode yang berfungsi di semua keluarga perangkat. Berikut adalah detail selengkapnya.

  • File yang umum untuk semua keluarga perangkat tidak memerlukan pertimbangan khusus. File-file tersebut akan digunakan oleh aplikasi pada semua keluarga perangkat yang dijalankannya. Ini termasuk file markup XAML, file kode sumber imperatif, dan file aset.
  • Aplikasi Anda dapat mendeteksi keluarga perangkat yang dijalankan dan menavigasi ke tampilan yang telah dirancang khusus untuk keluarga perangkat tersebut. Untuk detail selengkapnya, lihat Mendeteksi platform tempat aplikasi Anda berjalan.
  • Teknik serupa yang mungkin berguna jika tidak ada alternatif yang memberikan file markup atau file ResourceDictionary (atau folder yang berisi file) nama khusus sehingga secara otomatis dimuat pada runtime hanya saat aplikasi Anda berjalan pada keluarga perangkat tertentu. Teknik ini diilustrasikan dalam studi kasus Bookstore1 .
  • Anda harus dapat menghapus banyak arahan kompilasi bersyar di kode sumber aplikasi Universal 8.1 Anda jika Anda hanya perlu mendukung Windows 10. Lihat Kompilasi bersyarah dan kode adaptif dalam topik ini.
  • Untuk menggunakan fitur yang tidak tersedia di semua keluarga perangkat (misalnya, printer, pemindai, atau tombol kamera), Anda dapat menulis kode adaptif. Lihat contoh ketiga dalam Kompilasi bersyarkat dan kode adaptif dalam topik ini.
  • Jika Anda ingin mendukung Windows 8.1, Windows Phone 8.1, dan Windows 10, maka Anda dapat menyimpan tiga proyek dalam solusi yang sama dan berbagi kode dengan proyek Bersama. Atau, Anda dapat berbagi file kode sumber antar proyek. Berikut caranya: di Visual Studio, klik kanan proyek di Penjelajah Solusi, pilih Tambahkan Item yang Ada, pilih file yang akan dibagikan, lalu klik Tambahkan Sebagai Tautan. Simpan file kode sumber Anda di folder umum pada sistem file tempat proyek yang menautkannya dapat melihatnya. Dan jangan lupa untuk menambahkannya ke kontrol sumber.
  • Untuk penggunaan kembali di tingkat biner, daripada tingkat kode sumber, lihat Membuat komponen Windows Runtime di C# dan Visual Basic. Ada juga Pustaka Kelas Portabel, yang mendukung subset API .NET yang tersedia di .NET Framework untuk aplikasi Windows 8.1, Windows Phone 8.1, dan Windows 10 (.NET Core), dan .NET Framework lengkap. Rakitan Pustaka Kelas Portabel kompatibel dengan semua platform ini. Gunakan Visual Studio untuk membuat proyek yang menargetkan Pustaka Kelas Portabel. Lihat Pengembangan Lintas Platform dengan Pustaka Kelas Portabel.

SDK Ekstensi

Sebagian besar API Windows Runtime aplikasi Universal 8.1 Anda sudah melakukan panggilan diimplementasikan dalam set API yang dikenal sebagai keluarga perangkat universal. Namun, beberapa diimplementasikan dalam SDK ekstensi, dan Visual Studio hanya mengenali API yang diimplementasikan oleh keluarga perangkat target aplikasi Anda atau oleh SDK ekstensi apa pun yang telah Anda referensikan.

Jika Anda mendapatkan kesalahan kompilasi tentang namespace layanan atau jenis atau anggota yang tidak dapat ditemukan, kemungkinan ini menjadi penyebabnya. Buka topik API dalam dokumentasi referensi API dan navigasikan ke bagian Persyaratan: yang akan memberi tahu Anda apa itu keluarga perangkat yang menerapkan. Jika itu bukan keluarga perangkat target Anda, maka untuk membuat API tersedia untuk proyek Anda, Anda akan memerlukan referensi ke SDK ekstensi untuk keluarga perangkat tersebut.

Klik Proyek>Tambahkan Referensi>Windows Universal>Extensions dan pilih ekstensi SDK yang sesuai. Misalnya, jika API yang ingin Anda panggil hanya tersedia dalam keluarga perangkat seluler, dan api tersebut diperkenalkan dalam versi 10.0.x.y, lalu pilih Ekstensi Windows Mobile untuk UWP.

Itu akan menambahkan referensi berikut ke file proyek Anda:

<ItemGroup>
    <SDKReference Include="WindowsMobile, Version=10.0.x.y">
        <Name>Windows Mobile Extensions for the UWP</Name>
    </SDKReference>
</ItemGroup>

Nama dan nomor versi cocok dengan folder di lokasi SDK yang diinstal. Misalnya, informasi di atas cocok dengan nama folder ini:

\Program Files (x86)\Windows Kits\10\Extension SDKs\WindowsMobile\10.0.x.y

Kecuali aplikasi Anda menargetkan keluarga perangkat yang mengimplementasikan API, Anda harus menggunakan kelas ApiInformation untuk menguji keberadaan API sebelum Anda menyebutnya (ini disebut kode adaptif). Kondisi ini kemudian akan dievaluasi di mana pun aplikasi Anda berjalan, tetapi hanya akan mengevaluasi ke true pada perangkat tempat API ada dan oleh karena itu tersedia untuk dipanggil. Hanya gunakan SDK ekstensi dan kode adaptif setelah pertama kali memeriksa apakah ADA API universal. Beberapa contoh diberikan di bagian di bawah ini.

Selain itu, lihat Manifes paket aplikasi.

Kompilasi bersyar dan kode adaptif

Jika Anda menggunakan kompilasi kondisional (dengan direktif praprosesor C#) sehingga file kode Anda berfungsi pada Windows 8.1 dan Windows Phone 8.1, maka Anda sekarang dapat meninjau kompilasi kondisional tersebut mengingat pekerjaan konvergensi yang dilakukan di Windows 10. Konvergensi berarti bahwa, di aplikasi Windows 10 Anda, beberapa kondisi dapat dihapus sama sekali. Yang lain berubah menjadi pemeriksaan run-time, seperti yang ditunjukkan dalam contoh di bawah ini.

Catatan Jika Anda ingin mendukung Windows 8.1, Windows Phone 8.1, dan Windows 10 dalam satu file kode, maka Anda juga dapat melakukannya. Jika Anda melihat proyek Windows 10 di halaman properti proyek, Anda akan melihat bahwa proyek mendefinisikan WINDOWS_UAP sebagai simbol kompilasi bersyarah. Jadi, Anda dapat menggunakannya dalam kombinasi dengan WINDOWS_APP dan WINDOWS_PHONE_APP. Contoh-contoh ini menunjukkan kasus yang lebih sederhana untuk menghapus kompilasi bersyarat dari aplikasi Universal 8.1 dan mengganti kode yang setara untuk aplikasi Windows 10.

Contoh pertama ini menunjukkan pola penggunaan untuk API PickSingleFileAsync (yang hanya berlaku untuk Windows 8.1) dan Api PickSingleFileAndContinue (yang hanya berlaku untuk Windows Phone 8.1).

#if WINDOWS_APP
    // Use Windows.Storage.Pickers.FileOpenPicker.PickSingleFileAsync
#else
    // Use Windows.Storage.Pickers.FileOpenPicker.PickSingleFileAndContinue
#endif // WINDOWS_APP

Windows 10 berkonversi pada Api PickSingleFileAsync , sehingga kode Anda disederhanakan untuk ini:

    // Use Windows.Storage.Pickers.FileOpenPicker.PickSingleFileAsync

Dalam contoh ini, kami menangani tombol kembali perangkat keras—tetapi hanya di Windows Phone.

#if WINDOWS_PHONE_APP
        Windows.Phone.UI.Input.HardwareButtons.BackPressed += this.HardwareButtons_BackPressed;
#endif // WINDOWS_PHONE_APP

...

#if WINDOWS_PHONE_APP
    void HardwareButtons_BackPressed(object sender, Windows.Phone.UI.Input.BackPressedEventArgs e)
    {
        // Handle the event.
    }
#endif // WINDOWS_PHONE_APP

Di Windows 10, peristiwa tombol kembali adalah konsep universal. Tombol kembali yang diterapkan dalam perangkat keras atau dalam perangkat lunak semuanya akan meningkatkan peristiwa BackRequested , jadi itulah yang harus ditangani.

    Windows.UI.Core.SystemNavigationManager.GetForCurrentView().BackRequested +=
        this.ViewModelLocator_BackRequested;

...

private void ViewModelLocator_BackRequested(object sender, Windows.UI.Core.BackRequestedEventArgs e)
{
    // Handle the event.
}

Contoh akhir ini mirip dengan yang sebelumnya. Di sini, kami menangani tombol kamera perangkat keras—tetapi sekali lagi, hanya dalam kode yang dikompilasi ke dalam paket aplikasi Windows Phone.

#if WINDOWS_PHONE_APP
    Windows.Phone.UI.Input.HardwareButtons.CameraPressed += this.HardwareButtons_CameraPressed;
#endif // WINDOWS_PHONE_APP

...

#if WINDOWS_PHONE_APP
void HardwareButtons_CameraPressed(object sender, Windows.Phone.UI.Input.CameraEventArgs e)
{
    // Handle the event.
}
#endif // WINDOWS_PHONE_APP

Di Windows 10, tombol kamera perangkat keras adalah konsep khusus untuk keluarga perangkat seluler. Karena satu paket aplikasi akan berjalan di semua perangkat, kami mengubah kondisi waktu kompilasi menjadi kondisi run-time menggunakan apa yang dikenal sebagai kode adaptif. Untuk melakukannya, kami menggunakan kelas ApiInformation untuk mengkueri pada run-time untuk kehadiran kelas HardwareButtons. HardwareButtons didefinisikan dalam SDK ekstensi seluler, jadi kita harus menambahkan referensi ke SDK tersebut ke proyek kita agar kode ini dapat dikompilasi. Namun, perhatikan bahwa handler hanya akan dijalankan pada perangkat yang mengimplementasikan jenis yang ditentukan dalam SDK ekstensi seluler, dan itulah keluarga perangkat seluler. Jadi, kode ini secara moral setara dengan kode Universal 8.1 karena berhati-hati hanya untuk menggunakan fitur yang ada, meskipun mencapainya dengan cara yang berbeda.

    // Note: Cache the value instead of querying it more than once.
    bool isHardwareButtonsAPIPresent = Windows.Foundation.Metadata.ApiInformation.IsTypePresent
        ("Windows.Phone.UI.Input.HardwareButtons");

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

    ...

private void HardwareButtons_CameraPressed(object sender, Windows.Phone.UI.Input.CameraEventArgs e)
{
    // Handle the event.
}

Selain itu, lihat Mendeteksi platform tempat aplikasi Anda berjalan.

Manifes paket aplikasi

Topik Apa yang diubah di Windows 10 mencantumkan perubahan pada referensi skema manifes paket untuk Windows 10, termasuk elemen yang telah ditambahkan, dihapus, dan diubah. Untuk informasi referensi tentang semua elemen, atribut, dan jenis dalam skema, lihat Hierarki Elemen. Jika Anda memindahkan aplikasi Windows Phone Store, atau jika aplikasi Anda adalah pembaruan untuk aplikasi dari Windows Phone Store, pastikan bahwa elemen mp:PhoneIdentity cocok dengan apa yang ada di manifes aplikasi aplikasi Anda sebelumnya (gunakan GUID yang sama yang ditetapkan ke aplikasi oleh Store). Ini akan memastikan bahwa pengguna aplikasi Anda yang meningkatkan ke Windows 10 atau Windows 11 akan menerima aplikasi baru Anda sebagai pembaruan, bukan duplikat. Lihat topik referensi mp:PhoneIdentity untuk detail selengkapnya.

Pengaturan dalam proyek Anda (termasuk referensi SDK ekstensi apa pun) menentukan area permukaan API yang dapat dipanggil aplikasi Anda. Namun, manifes paket aplikasi Anda adalah apa yang menentukan kumpulan perangkat aktual tempat pelanggan Anda dapat menginstal aplikasi Anda dari Toko. Untuk informasi selengkapnya, lihat contoh di TargetDeviceFamily.

Anda dapat mengedit manifes paket aplikasi untuk mengatur berbagai deklarasi, kemampuan, dan pengaturan lain yang dibutuhkan beberapa fitur. Anda dapat menggunakan editor manifes paket aplikasi Visual Studio untuk mengeditnya. Jika Penjelajah Solusi tidak ditampilkan, pilih dari menu Tampilan. Klik ganda Package.appxmanifest. Ini membuka jendela editor manifes. Pilih tab yang sesuai untuk membuat perubahan lalu simpan.

Topik berikutnya adalah Pemecahan Masalah.