Porting proyek Windows Phone Silverlight ke proyek UWP

Artikel
07/05/2024

Topik sebelumnya adalah Namespace layanan dan pemetaan kelas.

Anda memulai proses porting dengan membuat proyek Windows 10 baru di Visual Studio dan menyalin file Anda ke dalamnya.

Membuat proyek dan menyalin file ke dalamnya

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.
Di proyek aplikasi Windows Phone Silverlight 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.
Salin tampilan (misalnya, MainPage.xaml dan MainPage.xaml.cs) ke dalam simpul 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 Windows Phone Silverlight 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.
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.
Perbedaan dalam namespace layanan dan nama kelas akan menghasilkan banyak kesalahan build pada tahap ini. Misalnya, jika Anda membuka tampilan yang dihasilkan Visual Studio, Anda akan melihat bahwa tampilan tersebut berjenis Halaman, dan bukan PhoneApplicationPage. Ada banyak markup XAML dan perbedaan kode imperatif yang dibahas topik berikut dalam panduan porting ini secara terperinci. Tapi, Anda akan membuat kemajuan cepat hanya dengan mengikuti langkah-langkah umum ini: mengubah "clr-namespace" menjadi "menggunakan" dalam deklarasi awalan namespace Anda di markup XAML; gunakan topik Namespace dan pemetaan kelas dan perintah Temukan dan Ganti Visual Studio untuk membuat perubahan massal pada kode sumber Anda (misalnya, ganti "System.Windows" dengan "Windows.UI.Xaml"); dan di editor kode imperatif di Visual Studio gunakan perintah Atasi dan Atur Menggunakan pada menu konteks untuk perubahan yang lebih ditargetkan.

SDK Ekstensi

Sebagian besar API Platform Windows Universal (UWP) yang akan dipanggil aplikasi port Anda akan 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.

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 adalah memberikan file markup atau file ResourceDictionary (atau folder yang berisi file) nama khusus sehingga secara otomatis dimuat pada runtime hanya ketika aplikasi Anda berjalan pada keluarga perangkat tertentu. Teknik ini diilustrasikan dalam studi kasus Bookstore1 .
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 Phone Silverlight dan Windows 10, maka Anda mungkin 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 menambahkannya ke kontrol sumber. Jika Anda dapat memperhitungkan kode sumber imperatif Anda sehingga sebagian besar, jika tidak semua, file akan berfungsi di kedua platform, maka Anda tidak perlu memiliki dua salinannya. Anda dapat membungkus logika khusus platform apa pun dalam file di dalam arahan kompilasi kondisional jika memungkinkan, atau kondisi run-time jika perlu. Lihat bagian berikutnya di bawah ini, dan Direktif Praprosesor C#.
Untuk penggunaan kembali di tingkat biner, daripada tingkat kode sumber, ada Pustaka Kelas Portabel, yang mendukung subset API .NET yang tersedia di Windows Phone Silverlight serta subset untuk aplikasi Windows 10 (.NET Core). Rakitan Pustaka Kelas Portabel kompatibel dengan platform .NET ini dan banyak lagi. Gunakan Visual Studio untuk membuat proyek yang menargetkan Pustaka Kelas Portabel. Lihat Pengembangan Lintas Platform dengan Pustaka Kelas Portabel.

Kompilasi bersyar dan kode adaptif

Jika Anda ingin mendukung Windows Phone Silverlight dan Windows 10 dalam satu file kode maka Anda dapat melakukannya. Jika Anda melihat proyek Windows 10 di halaman properti proyek, Anda akan melihat bahwa proyek mendefinisikan WINDOWS_UAP sebagai simbol kompilasi bersyarah. Secara umum, Anda dapat menggunakan logika berikut untuk melakukan kompilasi bersyarah.

#if WINDOWS_UAP
    // Code that you want to compile into the Windows 10/11 app.
#else
    // Code that you want to compile into the Windows Phone Silverlight app.
#endif // WINDOWS_UAP

Jika Anda memiliki kode yang telah Anda bagikan antara aplikasi Windows Phone Silverlight dan aplikasi Windows Runtime 8.x, maka Anda mungkin sudah memiliki kode sumber dengan logika seperti ini:

#if NETFX_CORE
    // Code that you want to compile into the Windows Runtime 8.x app.
#else
    // Code that you want to compile into the Windows Phone Silverlight app.
#endif // NETFX_CORE

Jika demikian, dan jika Anda sekarang ingin mendukung Windows 10 selain itu, maka Anda juga dapat melakukannya.

#if WINDOWS_UAP
    // Code that you want to compile into the Windows 10/11 app.
#else
#if NETFX_CORE
    // Code that you want to compile into the Windows Runtime 8.x app.
#else
    // Code that you want to compile into the Windows Phone Silverlight app.
#endif // NETFX_CORE
#endif // WINDOWS_UAP

Anda mungkin telah menggunakan kompilasi kondisional untuk membatasi penanganan tombol kembali perangkat keras ke Windows Phone. 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.
    }

Anda mungkin telah menggunakan kompilasi kondisional untuk membatasi penanganan tombol kamera perangkat keras ke Windows Phone. 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 berikut berhati-hati hanya untuk menggunakan fitur yang ada, meskipun mencapainya dengan cara yang berbeda dari kompilasi bersyarah.

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

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.

Perlu diketahui cara mengedit manifes paket aplikasi, karena topik yang mengikuti pembicaraan tentang menggunakannya untuk 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 perubahan. Anda mungkin ingin memastikan bahwa elemen pm:PhoneIdentity dalam manifes aplikasi port cocok dengan apa yang ada dalam manifes aplikasi yang Anda porting (untuk detail lengkapnya, lihat topik pm:PhoneIdentity).

Lihat Referensi skema manifes paket untuk Windows 10.

Topik berikutnya adalah Pemecahan Masalah.

Bagikan melalui