Bagikan melalui

Pengantar C++/WinRT

 

 

C++/WinRT adalah proyeksi bahasa C++17 modern yang sepenuhnya standar untuk API Windows Runtime (WinRT), yang diimplementasikan sebagai pustaka berbasis file header, dan dirancang untuk memberi Anda akses kelas satu ke Windows API modern. Dengan C++/WinRT, Anda dapat menulis dan menggunakan WINDOWS Runtime API menggunakan pengkompilasi C++17 yang mematuhi standar apa pun. Windows SDK mencakup C++/WinRT; ini diperkenalkan dalam versi 10.0.17134.0 (Windows 10, versi 1803).

C++/WinRT adalah pengganti microsoft yang direkomendasikan untuk proyeksi bahasa C++/CX , dan Windows Runtime C++ Template Library (WRL). Daftar lengkap topik tentang C++/WinRT mencakup info tentang berinteraksi dengan, dan porting dari, C++/CX dan WRL.

Penting

Beberapa bagian terpenting dari C++/WinRT yang harus diperhatikan dijelaskan di bagian dukungan SDK untuk dukungan C++/WinRT dan Visual Studio untuk C++/WinRT, XAML, ekstensi VSIX, dan paket NuGet.

Lihat juga Di mana saya dapat menemukan aplikasi sampel C++/WinRT?.

Proyeksi bahasa

Windows Runtime didasarkan pada API Komponen Objek Model (COM), dan dirancang untuk diakses melalui proyeksi bahasa . Proyeksi menyembunyikan detail COM, dan memberikan pengalaman pemrograman yang lebih alami untuk bahasa tertentu.

Proyeksi bahasa C++/WinRT dalam konten referensi WINDOWS Runtime API

Saat Anda menelusuri Windows Runtime APIs, klik kotak kombo Bahasa di kanan atas, dan pilih C++/WinRT untuk melihat blok sintaks API saat muncul dalam proyeksi bahasa C++/WinRT.

Dukungan Visual Studio untuk C++/WinRT, XAML, ekstensi VSIX, dan paket NuGet

Untuk dukungan Visual Studio, Anda memerlukan Visual Studio 2022, atau Visual Studio 2019, atau Visual Studio 2017 (setidaknya versi 15.6; kami merekomendasikan setidaknya 15.7). Dari dalam Alat Penginstal Visual Studio, instal pengembangan Universal Windows Platform beban kerja. Dalam Detail Penginstalan>pengembangan Universal Windows Platform, periksa C++ (v14x) Universal Windows Platform opsi jika Anda belum melakukannya. Dan, di Pengaturan> WindowsPrivasi & keamanan (Windows 10: Pembaruan & Keamanan) >Untuk pengembang, aktifkan opsi Mode pengembang (Windows 10: bukan opsi aplikasi Sideload).

Meskipun kami menyarankan agar Anda mengembangkan dengan versi terbaru Visual Studio dan Windows SDK, jika Anda menggunakan versi C++/WinRT yang dikirim dengan Windows SDK sebelum 10.0.17763.0 (Windows 10, versi 1809), kemudian, untuk menggunakan header namespace Windows yang disebutkan di atas, Anda memerlukan versi target Windows SDK minimum dalam proyek Anda 10.0.17134.0 (Windows 10, versi 1803).

Visual Studio 2022 dikirim dengan proyek C++/WinRT dan templat item bawaan, sehingga Anda dapat segera memulai pengembangan C++/WinRT. Ini juga dilengkapi dengan visualisasi debug asli Visual Studio (natvis) dari jenis proyeksi C++/WinRT; menawarkan pengalaman serupa dengan debugging C#. Otomatis Natvis untuk pembangunan debug. Untuk informasi selengkapnya, lihat visualisasi debug asli Visual Studio untuk C++/WinRT.

Untuk versi Visual Studio yang lebih lama, Anda harus mengunduh dan menginstal versi terbaru C++/WinRT Visual Studio Extension (VSIX) dari Visual Studio Marketplace.

  • Ekstensi VSIX memberi Anda proyek C++/WinRT dan templat item di Visual Studio.
  • Selain itu, ini menyediakan visualisasi debug asli Visual Studio (natvis) untuk tipe proyeksi C++/WinRT.

Templat proyek Visual Studio untuk C++/WinRT dijelaskan di bagian di bawah ini. Saat Anda membuat proyek C++/WinRT baru dengan versi terbaru ekstensi VSIX yang diinstal, proyek C++/WinRT baru secara otomatis menginstal paket NuGet Microsoft.Windows.CppWinRT. Paket NuGet Microsoft.Windows.CppWinRT menyediakan dukungan build C++/WinRT (properti dan target MSBuild), membuat proyek Anda portabel antara mesin pengembangan dan agen build (di mana hanya paket NuGet, dan bukan ekstensi VSIX, yang diinstal).

Atau, Anda dapat mengonversi proyek yang ada dengan menginstal paket NuGet Microsoft.Windows.CppWinRT secara manual. Setelah menginstal (atau memperbarui ke) versi terbaru ekstensi VSIX, buka proyek yang ada di Visual Studio, klik Proyek>Kelola Paket NuGet...>Telusuri, ketik, atau tempel Microsoft.Windows.CppWinRT di kotak pencarian, pilih item di hasil pencarian, lalu klik Instal untuk menginstal paket untuk proyek tersebut. Setelah Anda menambahkan paket, Anda akan mendapatkan dukungan MSBuild untuk C++/WinRT pada proyek Anda, termasuk memanggil tool cppwinrt.exe.

Penting

Jika Anda memiliki proyek yang dibuat dengan (atau ditingkatkan agar dapat digunakan) versi ekstensi VSIX sebelum 1.0.190128.4, lihat Versi ekstensi VSIX sebelumnya. Bagian tersebut berisi info penting tentang konfigurasi proyek Anda, yang perlu Anda ketahui untuk meningkatkannya untuk menggunakan versi terbaru ekstensi VSIX.

  • Karena C++/WinRT menggunakan fitur dari standar C++17, paket NuGet menetapkan properti proyek C/C++>Language>C++ Language Standard>ISO C++17 Standard (/std:c++17) di Visual Studio.
  • Ini juga menambahkan opsi kompilator /bigobj.
  • Ini menambahkan opsi kompilator /await untuk mengaktifkan co_await.
  • Ini menginstruksikan pengkompilasi XAML untuk memancarkan codegen C++/WinRT.
  • Anda mungkin juga ingin mengatur mode Kesesuaian: Ya (/permissive-), yang selanjutnya membatasi kode Anda agar sesuai standar.
  • Properti proyek lain yang perlu diperhatikan adalah C/C++>General>Perlakukan Peringatan Sebagai Kesalahan. Atur ini ke Ya(/WX) atau Tidak (/WX-) sesuai selera. Terkadang, file sumber yang dihasilkan oleh cppwinrt.exe alat menghasilkan peringatan sampai Anda menambahkan implementasi Anda ke dalamnya.

Dengan sistem yang disiapkan seperti yang dijelaskan di atas, Anda akan dapat membuat dan membangun, atau membuka, proyek C++/WinRT di Visual Studio, dan menyebarkannya.

Pada versi 2.0, paket NuGet Microsoft.Windows.CppWinRT menyertakan alat ini cppwinrt.exe . Anda dapat mengarahkan alat cppwinrt.exe pada metadata Windows Runtime (file.winmd) untuk menghasilkan pustaka C++ standar berbasis berkas header yang digunakan oleh proyek untuk mengakses API yang dijelaskan dalam metadata untuk digunakan dari kode C++/WinRT. File metadata Windows Runtime (.winmd) menyediakan cara kanonis untuk menjelaskan permukaan Windows Runtime API. Dengan menunjuk cppwinrt.exe ke metadata, Anda dapat membuat pustaka untuk digunakan dengan kelas runtime apa pun yang diterapkan dalam komponen Windows Runtime pihak kedua atau pihak ketiga, atau diimplementasikan dalam aplikasi Anda sendiri. Untuk informasi selengkapnya, lihat Mengonsumsi API menggunakan C++/WinRT.

Dengan C++/WinRT, Anda juga dapat menerapkan kelas runtime Anda sendiri menggunakan C++standar, tanpa menggunakan pemrograman gaya COM. Untuk kelas runtime, Anda cukup menggambarkan tipe Anda dalam file IDL, dan midl.exe serta cppwinrt.exe akan menggenerasikan file kode sumber boilerplate implementasi untuk Anda. Anda dapat juga mengimplementasikan antarmuka dengan cara alternatif, yaitu berasal dari kelas dasar C++/WinRT. Untuk informasi selengkapnya, lihat Author APIs dengan C++/WinRT.

Untuk daftar opsi penyesuaian untuk alat cppwinrt.exe, yang diatur melalui properti proyek, silakan lihat paket NuGet Microsoft.Windows.CppWinRT dan readme.

Anda dapat mengidentifikasi proyek yang menggunakan dukungan C++/WinRT MSBuild dengan adanya paket NuGet Microsoft.Windows.CppWinRT yang diinstal dalam proyek.

Berikut adalah templat proyek Visual Studio yang disediakan oleh ekstensi VSIX.

Aplikasi Blank (C++/WinRT)

Templat proyek untuk aplikasi Universal Windows Platform (UWP) yang memiliki antarmuka pengguna XAML.

Visual Studio menyediakan dukungan kompilator XAML untuk menghasilkan implementasi dan stub header dari file Interface Definition Language (IDL) (.idl) yang berada di belakang setiap file markup XAML. Dalam file IDL, tentukan kelas runtime lokal apa pun yang ingin Anda referensikan di halaman XAML aplikasi Anda, lalu bangun proyek sekali untuk menghasilkan templat implementasi di Generated Files, dan stub definisi jenis di Generated Files\sources. Kemudian gunakan definisi jenis stub tersebut untuk referensi guna mengimplementasikan kelas runtime lokal Anda. Lihat bagian "Memfaktorkan kelas runtime ke dalam file MIDL (.idl)" .

Dukungan permukaan desain XAML di Visual Studio untuk C++/WinRT mendekati paritas dengan C#. Di Visual Studio, Anda dapat menggunakan tab Peristiwa di jendela Properti untuk menambahkan penanganan aktivitas dalam proyek C++/WinRT. Anda juga dapat menambahkan penanganan aktivitas ke kode Anda secara manual—lihat Menangani peristiwa dengan menggunakan delegasi di C++/WinRT untuk informasi selengkapnya.

Aplikasi Inti (C++/WinRT)

Templat proyek untuk aplikasi Universal Windows Platform (UWP) yang tidak menggunakan XAML.

Sebaliknya, ia menggunakan header ruang nama Windows C++/WinRT untuk ruang nama Windows.ApplicationModel.Core. Setelah selesai membangun dan menjalankan program, klik pada ruang kosong untuk menambahkan persegi berwarna; kemudian, klik pada persegi berwarna untuk menyeretnya.

Aplikasi Konsol Windows (C++/WinRT)

Templat proyek untuk aplikasi klien C++/WinRT untuk Windows Desktop, dengan antarmuka pengguna konsol.

Aplikasi Desktop Windows (C++/WinRT)

Templat proyek untuk aplikasi klien C++/WinRT untuk Windows Desktop, yang menampilkan Windows Runtime Windows.Foundation.Uri di dalam Kotak Pesan Win32.

Komponen Runtime Windows (C++/WinRT)

Templat proyek untuk komponen; biasanya untuk penggunaan dari Universal Windows Platform (UWP).

Templat ini menunjukkan midl.exe>cppwinrt.exe toolchain, di mana metadata Windows Runtime (.winmd) dihasilkan dari IDL, lalu implementasi dan stub header dihasilkan dari metadata Windows Runtime.

Dalam file IDL, tentukan kelas runtime di komponen Anda, antarmuka defaultnya, dan antarmuka lain yang mereka terapkan. Bangun proyek sekali untuk menghasilkan module.g.cpp, module.h.cpp, templat implementasi dalam Generated Files, dan definisi jenis stub di Generated Files\sources. Kemudian gunakan definisi jenis stub untuk referensi guna mengimplementasikan kelas runtime dalam komponen Anda. Lihat bagian "Memfaktorkan kelas runtime ke dalam file MIDL (.idl)" .

Bundelkan biner komponen Windows Runtime bawaan dan .winmd dengan aplikasi UWP yang mengonsumsinya.

Versi ekstensi VSIX yang lebih lama

Kami menyarankan agar Anda menginstal (atau memperbarui ke) versi terbaru ekstensi VSIX. Ini dikonfigurasi untuk memperbarui dirinya sendiri secara default. Jika Anda melakukannya, dan Anda memiliki proyek yang dibuat dengan versi ekstensi VSIX yang lebih lama dari 1.0.190128.4, bagian ini berisi info penting tentang meningkatkan proyek tersebut agar berfungsi dengan versi baru. Jika Anda tidak memperbarui, maka Anda masih akan menemukan info di bagian ini berguna.

Dalam hal versi Windows SDK dan Visual Studio yang didukung, dan konfigurasi Visual Studio, info dalam dukungan Visual Studio untuk C++/WinRT, XAML, ekstensi VSIX, dan bagian paket NuGet di atas berlaku untuk versi ekstensi VSIX yang lebih lama. Info di bawah ini menjelaskan perbedaan penting mengenai perilaku dan konfigurasi proyek yang dibuat dengan (atau ditingkatkan untuk bekerja dengan) versi sebelumnya.

Dibuat lebih awal dari 1.0.181002.2

Jika proyek Anda dibuat dengan versi ekstensi VSIX yang lebih lama dari 1.0.181002.2, maka dukungan build C++/WinRT dibangun ke dalam versi ekstensi VSIX tersebut. Proyek Anda memiliki properti <CppWinRTEnabled>true</CppWinRTEnabled> yang ditetapkan pada file .vcxproj.

<Project ...>
    <PropertyGroup Label="Globals">
        <CppWinRTEnabled>true</CppWinRTEnabled>
...

Anda dapat meningkatkan proyek anda dengan menginstal paket NuGet Microsoft.Windows.CppWinRT secara manual. Setelah menginstal (atau memutakhirkan ke) versi terbaru ekstensi VSIX, buka proyek Anda di Visual Studio, klik Proyek>Kelola Paket NuGet...>Telusuri, ketik, atau tempel Microsoft.Windows.CppWinRT di kotak pencarian, pilih item di hasil pencarian, lalu klik Instal untuk menginstal paket untuk proyek Anda.

Dibuat dengan (atau ditingkatkan ke) antara 1.0.181002.2 dan 1.0.190128.3

Jika proyek Anda dibuat dengan versi ekstensi VSIX antara 1.0.181002.2 dan 1.0.190128.3, inklusif, maka paket NuGet Microsoft.Windows.CppWinRT diinstal dalam proyek secara otomatis oleh templat proyek. Anda mungkin juga telah meningkatkan proyek lama untuk menggunakan versi ekstensi VSIX dalam rentang ini. Jika demikian—karena dukungan build juga masih ada dalam versi ekstensi VSIX dalam rentang ini—proyek yang ditingkatkan mungkin memiliki paket Microsoft.Windows.CppWinRT NuGet yang terinstal, atau mungkin tidak.

Untuk meningkatkan proyek Anda, ikuti instruksi di bagian sebelumnya dan pastikan proyek Anda memiliki paket Microsoft.Windows.CppWinRT NuGet yang terinstal .

Konfigurasi peningkatan tidak valid

Dengan versi terbaru ekstensi VSIX, proyek tidak dapat memiliki properti <CppWinRTEnabled>true</CppWinRTEnabled> jika tidak juga memiliki paket NuGet Microsoft.Windows.CppWinRT yang terpasang. Proyek dengan konfigurasi ini menghasilkan pesan kesalahan build, "C++/WinRT VSIX tidak lagi menyediakan dukungan build proyek. Tambahkan referensi proyek ke paket Nuget Microsoft.Windows.CppWinRT."

Seperti disebutkan di atas, proyek C++/WinRT sekarang perlu menginstal paket NuGet di dalamnya.

<CppWinRTEnabled> Karena elemen sekarang usang, Anda dapat secara opsional mengedit .vcxproj, dan menghapus elemen . Ini tidak benar-benar diperlukan, tetapi itu adalah pilihan.

Selain itu, jika .vcxproj berisi <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>, maka Anda dapat menghapusnya sehingga Anda dapat memberi build tanpa memerlukan ekstensi C++/WinRT VSIX untuk diinstal.

Dukungan SDK untuk C++/WinRT

Meskipun sekarang hanya ada karena alasan kompatibilitas, pada versi 10.0.17134.0 (Windows 10, versi 1803), Windows SDK berisi pustaka C++ standar berbasis file header untuk menggunakan API Windows pihak pertama (WINDOWS Runtime API di namespace Windows). Header tersebut berada di dalam folder %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. Pada Windows SDK versi 10.0.17763.0 (Windows 10, versi 1809), header ini dibuat untuk Anda di dalam folder $(GeneratedFilesDir) proyek Anda.

Demi kompatibilitas, Windows SDK juga dilengkapi dengan alat cppwinrt.exe. Namun, kami sarankan Anda menginstal dan menggunakan versi terbaru cppwinrt.exe, yang disertakan dengan paket Microsoft.Windows.CppWinRT NuGet. Paket itu, dan cppwinrt.exe, dijelaskan dalam bagian di atas.

Jenis kustom dalam proyeksi C++/WinRT

Dalam pemrograman C++/WinRT, Anda dapat menggunakan fitur bahasa C++ standar dan jenis data C++ Standar dan C++/WinRT—termasuk beberapa jenis data Pustaka Standar C++. Tetapi Anda juga akan mengetahui beberapa jenis data kustom dalam proyeksi, dan Anda dapat memilih untuk menggunakannya. Misalnya, kami menggunakan winrt::hstring dalam contoh kode mulai cepat di Mulai menggunakan C++/WinRT.

winrt::com_array adalah jenis lain yang mungkin Anda gunakan pada suatu saat. Namun, Anda lebih kecil kemungkinannya untuk langsung menggunakan jenis seperti winrt::array_view. Atau Anda dapat memilih untuk tidak menggunakannya sehingga Anda tidak akan memiliki kode apa pun untuk diubah jika dan ketika jenis yang setara muncul di Pustaka Standar C++.

Peringatan

Ada juga jenis yang mungkin Anda temui jika Anda mempelajari header namespace Windows C++/WinRT dengan saksama. Contohnya adalah winrt::param::hstring, tetapi ada contoh koleksi juga. Ini hanya ada untuk mengoptimalkan pengikatan parameter input, dan menghasilkan peningkatan performa besar dan membuat sebagian besar pola panggilan "hanya berfungsi" untuk jenis dan kontainer C++ standar terkait. Jenis-jenis ini hanya digunakan oleh proyeksi dalam kasus di mana mereka memberikan nilai tertinggi. Mereka sangat dioptimalkan dan tidak digunakan secara umum; jangan tergoda untuk menggunakannya sendiri. Anda juga tidak boleh menggunakan apa pun dari namespace winrt::impl, karena itu adalah jenis implementasi dan sehingga dapat berubah. Anda harus terus menggunakan jenis standar, atau jenis dari namespace layanan winrt.

Lihat juga Meneruskan parameter ke batas ABI.

API penting

  • Last updated on