Porting ke Platform Windows Universal (C++)

Artikel
10/12/2023

Dalam topik ini, Anda dapat menemukan informasi tentang cara memindahkan kode C++ yang ada ke platform aplikasi Windows, Platform Windows Universal. Apa yang dimaksud dengan istilah universal adalah bahwa kode Anda dapat berjalan pada salah satu perangkat yang menjalankan Windows 10 atau yang lebih baru. Anda membuat satu proyek dan satu antarmuka pengguna berbasis XAML yang berfungsi dengan baik pada perangkat apa pun yang menjalankan Windows 10 atau yang lebih baru. Anda dapat menggunakan fitur tata letak dinamis di XAML untuk memungkinkan UI aplikasi beradaptasi dengan ukuran tampilan yang berbeda.

Dokumentasi Windows Dev Center berisi panduan untuk memindahkan aplikasi Windows 8.1 ke Platform Windows Universal. Lihat Berpindah dari Windows Runtime 8 ke UWP. Meskipun panduan ini sebagian besar berfokus pada kode C#, sebagian besar panduan berlaku untuk C++. Prosedur berikut berisi informasi yang lebih rinci. Lihat juga Memindahkan dari aplikasi desktop ke UWP.

Topik ini berisi prosedur berikut untuk kode porting ke UWP.

Memindahkan Aplikasi Bursa Windows 8.1 ke UWP
Memindahkan Komponen Runtime Windows 8.1 ke UWP

Jika Anda memiliki desktop klasik Win32 DLL dan Anda ingin memanggilnya dari aplikasi UWP, Anda juga dapat melakukannya. Dengan menggunakan prosedur tersebut, Anda dapat membuat lapisan antarmuka pengguna UWP untuk aplikasi C++ desktop Windows klasik yang ada, atau kode C++ standar lintas platform Anda. Lihat Cara: Menggunakan Kode C++ yang Ada di Aplikasi Platform Windows Universal.

Memindahkan Aplikasi Bursa Windows 8.1 ke UWP

Jika Anda memiliki Aplikasi Bursa Windows 8.1, Anda dapat menggunakan prosedur ini untuk membuatnya berfungsi di UWP dan perangkat apa pun yang menjalankan Windows 10 atau yang lebih baru. Ada baiknya untuk terlebih dahulu membangun proyek dengan Visual Studio 2019 sebagai proyek Windows 8.1, untuk terlebih dahulu menghilangkan masalah apa pun yang muncul dari perubahan di kompiler dan pustaka. Setelah Anda melakukannya, ada dua cara untuk mengonversi ini ke proyek Windows UWP. Cara term mudah (seperti yang dijelaskan dalam prosedur berikut) adalah dengan membuat proyek Universal Windows, dan menyalin kode yang ada ke dalamnya. Jika Anda menggunakan proyek Universal untuk desktop Windows 8.1 dan Windows 8.1 Telepon, proyek Anda akan dimulai dengan dua tata letak yang berbeda di XAML tetapi diakhpuni dengan satu tata letak dinamis yang menyesuaikan dengan ukuran tampilan.

Untuk memindahkan Aplikasi Bursa Windows 8.1 ke UWP

Jika Anda belum melakukannya, buka proyek Aplikasi Windows 8.1 Anda di Visual Studio 2017, dan ikuti instruksi untuk meningkatkan file proyek.

Anda harus telah menginstal Alat Windows 8.1 di penyiapan Visual Studio . Jika Anda tidak menginstal alat tersebut, mulai penyiapan Visual Studio dari jendela Program dan Fitur, pilih Visual Studio 2017, dan di jendela penyiapan, pilih Ubah. Temukan Alat Windows 8.1, pastikan alat tersebut dipilih, dan pilih OK.
Buka jendela Properti Proyek, dan di bawah C++>General, atur Platform Toolset ke v141, toolset untuk Visual Studio 2017.
Bangun proyek sebagai proyek Windows 8.1, dan atasi kesalahan build apa pun. Kesalahan apa pun pada tahap ini mungkin disebabkan oleh perubahan yang merusak dalam alat dan pustaka build. Lihat Riwayat perubahan Visual C++ 2003 - 2015 untuk penjelasan terperinci tentang perubahan yang mungkin memengaruhi kode Anda.

Setelah proyek Anda dibangun dengan bersih, Anda siap untuk port untuk Platform Windows Universal.
Buat proyek Aplikasi Windows Universal baru menggunakan templat Kosong. Anda mungkin ingin memberinya nama yang sama dengan proyek yang ada, meskipun untuk melakukan itu proyek harus berada di direktori yang berbeda.
Tutup solusi, lalu gunakan Windows Explorer atau baris perintah, salin file kode (dengan ekstensi .cpp, .h, dan .xaml) dari proyek Windows 8.1 Anda ke folder yang sama dengan file proyek (.vcxproj) untuk proyek yang Anda buat di langkah 1. Jangan salin file Package.appxmanifest, dan jika Anda memiliki kode terpisah untuk desktop dan telepon Windows 8.1, pilih salah satunya ke port terlebih dahulu (Anda harus melakukan beberapa pekerjaan nanti untuk beradaptasi dengan yang lain). Pastikan untuk menyalin dan subfolder dan kontennya. Jika diminta, pilih untuk mengganti file apa pun dengan nama duplikat.
Buka kembali solusi, dan pilih Tambahkan>Item yang Ada dari menu pintasan untuk simpul proyek. Pilih semua file yang Anda salin, kecuali yang sudah menjadi bagian dari proyek.

Periksa subfolder apa pun dan pastikan untuk menambahkan file di dalamnya juga.
Jika Anda tidak menggunakan nama proyek yang sama dengan proyek lama Anda, buka file Package.appxmanifest dan perbarui Entry Point untuk mencerminkan nama namespace layanan untuk App kelas tersebut.

Bidang Titik Entri dalam file Package.appxmanifest berisi nama cakupan untuk App kelas , yang mencakup namespace yang berisi App kelas . Saat Anda membuat proyek Universal Windows, namespace diatur ke nama proyek. Jika ini berbeda dari apa yang ada di file yang Anda salin dari proyek lama, Anda harus memperbarui satu atau yang lain agar cocok.
Bangun proyek, dan atasi kesalahan build apa pun karena perubahan yang melanggar antara berbagai versi Windows SDK.
Jalankan proyek di Desktop Lokal. Verifikasi bahwa tidak ada kesalahan penyebaran, dan tata letak aplikasi terlihat masuk akal dan berfungsi dengan benar di desktop.
Jika Anda memiliki file kode terpisah dan .xaml untuk perangkat lain, seperti Windows Telepon 8.1, periksa kode ini dan identifikasi di mana perbedaannya dengan perangkat standar. Jika perbedaan hanya ada di tata letak, Anda mungkin dapat menggunakan Visual State Manager di xaml untuk menyesuaikan tampilan tergantung pada ukuran layar. Untuk perbedaan lain, Anda dapat menggunakan bagian kondisi dalam kode Anda menggunakan pernyataan #if berikut.
```
#if WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_PC_APP)
#if WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_PHONE_APP)
#if WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP)
#if WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP)
```
Pernyataan ini masing-masing berlaku untuk aplikasi UWP, aplikasi Windows Telepon Store, keduanya, atau tidak (hanya desktop Win32 klasik). Makro ini hanya tersedia di Windows SDK 8.1 dan yang lebih baru, jadi jika kode Anda perlu dikompilasi dengan versi Windows SDK yang lebih lama atau untuk platform lain selain Windows, maka Anda juga harus mempertimbangkan kasus bahwa tidak ada yang ditentukan.
Jalankan dan debug aplikasi di emulator atau perangkat fisik, untuk setiap jenis perangkat yang didukung aplikasi Anda. Untuk menjalankan emulator, Anda perlu menjalankan Visual Studio di komputer fisik, bukan komputer virtual.

Memindahkan Komponen Runtime Windows 8.1 ke UWP

Jika Anda memiliki DLL atau Komponen Runtime Windows yang sudah berfungsi dengan aplikasi Windows 8.1 Store, Anda dapat menggunakan prosedur ini untuk membuat komponen atau DLL bekerja dengan UWP di Windows. Prosedur dasarnya adalah membuat proyek baru dan menyalin kode Anda ke dalamnya.

Untuk mem-port Komponen Runtime Windows 8.1 ke UWP

Dalam dialog Proyek Baru di Visual Studio 2017, temukan simpul Windows Universal. Jika Anda tidak melihat simpul ini, instal Windows SDK terlebih dahulu. Pilih templat Komponen Runtime Windows, beri nama untuk komponen Anda, dan pilih tombol OK. Nama komponen akan digunakan sebagai nama namespace, sehingga Anda mungkin ingin menggunakan nama yang sama dengan namespace proyek lama Anda. Ini mengharuskan Anda membuat proyek di folder yang berbeda dari yang lama. Jika Anda memilih nama yang berbeda, Anda dapat memperbarui nama namespace dalam file kode yang dihasilkan.
Tutup proyek.
Salin semua file kode (.cpp, .h, .xaml, dll.) dari komponen Windows 8.1 Anda ke dalam proyek yang baru dibuat. Jangan salin file Package.appxmanifest.
Bangun, dan atasi kesalahan apa pun karena perubahan yang melanggar antara versi Windows SDK yang berbeda.

Pemecahan Masalah

Anda mungkin mengalami berbagai kesalahan selama proses porting kode ke UWP. Berikut adalah beberapa kemungkinan masalah yang mungkin Anda temui.

Masalah Konfigurasi Proyek

Anda mungkin menerima kesalahan:

could not find assembly 'platform.winmd': please specify the assembly search path using /AI or by setting the LIBPATH environment variable

Jika ini terjadi, proyek tidak dibangun sebagai proyek Windows Universal. Periksa file proyek dan pastikan file tersebut memiliki elemen XML yang benar yang mengidentifikasi proyek sebagai Proyek Universal Windows. Elemen berikut harus ada (nomor versi platform target mungkin berbeda):

<AppContainerApplication>true</AppContainerApplication>
<ApplicationType>Windows Store</ApplicationType>
<WindowsTargetPlatformVersion>10.0.10156.0</WindowsTargetPlatformVersion>
<WindowsTargetPlatformMinVersion>10.0.10156.0</WindowsTargetPlatformMinVersion>
<ApplicationTypeRevision>10.0</ApplicationTypeRevision>

Jika Anda membuat proyek UWP baru menggunakan Visual Studio, Anda tidak akan melihat kesalahan ini.