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 API Windows Runtime menggunakan kompilator C++17 yang mematuhi standar apa pun. SDK Windows mencakup C++/WinRT; diperkenalkan dalam versi 10.0.17134.0 (Windows 10, versi 1803).

Petunjuk / Saran

Kapan memilih C++/WinRT: Gunakan C++/WinRT saat Anda perlu membuat aplikasi Windows di C++ — misalnya, ketika batasan performa tidak memerlukan pengumpul sampah, saat beroperasi dengan pustaka C++ yang ada, atau saat menulis komponen Windows Runtime. Jika proyek Anda tidak memiliki persyaratan ini, pertimbangkan C# dengan WinUI 3 untuk pengembangan yang lebih cepat dan keamanan memori bawaan.

C++/WinRT adalah pengganti yang direkomendasikan oleh Microsoft untuk proyeksi bahasa C++/CX serta Pustaka Templat C++ Windows Runtime (WRL). Daftar lengkap topik tentang C++/WinRT mencakup informasi tentang interoperabilitas dengan, dan mem-porting dari, C++/CX dan WRL.

Important

Beberapa bagian terpenting dari C++/WinRT yang perlu diperhatikan dijelaskan di bagian dukungan SDK untuk C++/WinRT dan dukungan 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 Model Objek Komponen (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 API Windows Runtime

Saat Anda menelusuri WINDOWS RUNTIME API, klik kotak Kombo Bahasa di kanan atas, dan pilih C++/WinRT untuk melihat blok sintaks API saat muncul dalam proyeksi bahasa C++/WinRT.

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

Untuk dukungan Visual Studio, Anda memerlukan Visual Studio 2022 atau yang lebih baru. Dari dalam alat penginstal Visual Studio, instal beban kerja pengembangan Platform Windows Universal. Di Detail Penginstalan>pengembangan Platform Windows Universal, centang opsi alat C++ (v14x) Platform Windows Universal jika Anda belum melakukannya. Dan, di pengaturan WindowsPrivasi & keamananUntuk pengembang, aktifkan opsi Mode pengembang.

Note

Visual Studio 2022 dan versi yang lebih baru disertai templat proyek dan item C++/WinRT bawaan, serta visualisasi penelusuran kesalahan native (natvis) untuk tipe terproyeksi C++/WinRT. Jika Anda menggunakan versi Visual Studio yang lebih lama, instal ekstensi C++/WinRT VSIX dari marketplace Visual Studio.

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 Microsoft.Windows. Paket CppWinRT NuGet. Paket NuGet Microsoft.Windows.CppWinRT menyediakan dukungan build C++/WinRT (properti dan target MSBuild), sehingga proyek Anda dapat dipindahkan antara mesin pengembangan dan agen build (yang hanya menginstal paket NuGet, bukan ekstensi VSIX).

Atau, Anda dapat mengonversi proyek yang ada dengan secara manual menginstal paket NuGet Microsoft.Windows.CppWinRT. Setelah menginstal (atau memperbarui ke) versi terbaru ekstensi VSIX, buka project yang ada di Visual Studio, klik Project>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 project tersebut. Setelah menambahkan paket, Anda akan mendapatkan dukungan C++/WinRT MSBuild untuk proyek tersebut, termasuk menjalankan alat cppwinrt.exe.

Important

Jika Anda memiliki proyek yang dibuat dengan (atau ditingkatkan untuk dikerjakan) versi ekstensi VSIX yang lebih lama dari 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) dalam 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 Kesuaian: Ya (/permisif-), yang selanjutnya membatasi kode Anda agar sesuai standar.
  • Properti proyek lain yang perlu diperhatikan adalah C/C++>Umum>Perlakukan Peringatan sebagai Kesalahan. Atur ini ke Ya(/WX) atau Tidak (/WX-) secukupnya. Terkadang, file sumber yang dihasilkan oleh cppwinrt.exe alat menghasilkan peringatan sampai Anda menambahkan implementasi Anda ke dalamnya.

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

Mulai versi 2.0, paket NuGet Microsoft.Windows.CppWinRT menyertakan alat cppwinrt.exe. Anda dapat mengarahkan alat cppwinrt.exe ke file metadata Windows Runtime (.winmd) untuk menghasilkan pustaka C++ standar berbasis file header yang menyajikan API yang dijelaskan dalam metadata agar dapat digunakan oleh kode C++/WinRT. Windows Runtime file metadata (.winmd) menyediakan cara kanonis untuk menjelaskan permukaan API Windows Runtime. Dengan mengarahkan cppwinrt.exe ke metadata, Anda dapat membuat pustaka yang dapat digunakan dengan kelas runtime apa pun yang diimplementasikan dalam komponen Windows Runtime milik pihak lain maupun pihak ketiga, atau yang diimplementasikan dalam aplikasi Anda sendiri. Untuk informasi selengkapnya, lihat Menggunakan API dengan 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 menjelaskan tipe Anda dalam file IDL, dan midl.exe dan cppwinrt.exe akan menghasilkan file kode sumber boilerplate implementasi untuk Anda. Anda dapat mengimplementasikan antarmuka dengan berasal dari kelas dasar C++/WinRT. Untuk informasi selengkapnya, lihat API Penulis dengan C++/WinRT.

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

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

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. Untuk aplikasi desktop WinUI 3, gunakan templat Aplikasi Kosong, Dipaketkan (WinUI 3 di Desktop) sebagai gantinya.

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, definisikan kelas runtime lokal apa pun yang ingin Anda rujuk di halaman XAML aplikasi Anda, lalu build proyek sekali untuk menghasilkan templat implementasi di Generated Files, dan definisi tipe stub di Generated Files\sources. Kemudian gunakan definisi jenis stub tersebut untuk referensi guna mengimplementasikan kelas runtime lokal Anda. Lihat Memisahkan 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. Tidak ada WinUI 3 yang setara dengan templat ini.

Sebagai gantinya, ini menggunakan header namespace Windows C++/WinRT untuk namespace Windows.ApplicationModel.Core. Setelah aplikasi dibangun dan dijalankan, klik area kosong untuk menambahkan persegi berwarna; lalu klik 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)

Template proyek untuk aplikasi klien C++/WinRT untuk Windows Desktop, yang menampilkan Windows Runtime Windows.Foundation.Uri dalam MessageBox Win32.

Komponen Windows Runtime (C++/WinRT)

Templat proyek untuk komponen; biasanya untuk digunakan di 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. Build proyek sekali untuk menghasilkan module.g.cpp, module.h.cpp, templat implementasi di Generated Files, dan definisi tipe stub di Generated Files\sources. Kemudian gunakan definisi jenis stub untuk referensi guna mengimplementasikan kelas runtime dalam komponen Anda. Lihat Memisahkan kelas runtime ke dalam file MIDL (.idl).

Gabungkan biner komponen Windows Runtime yang telah dibangun beserta .winmd-nya dengan aplikasi UWP yang menggunakannya.

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 sebelumnya. 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 diatur dalam file .vcxproj.

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

Anda dapat memutakhirkan proyek Anda dengan menginstal secara manual paket NuGet Microsoft.Windows.CppWinRT. Setelah menginstal (atau memutakhirkan ke) versi terbaru ekstensi VSIX, buka project Anda di Visual Studio, klik Project>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 project 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, termasuk kedua versi tersebut, paket NuGet Microsoft.Windows.CppWinRT secara otomatis diinstal ke dalam proyek oleh templat proyek. Anda mungkin juga telah meningkatkan proyek lama untuk menggunakan versi ekstensi VSIX dalam rentang ini. Jika demikian, maka—karena dukungan build juga masih tersedia dalam versi ekstensi VSIX di rentang ini—proyek yang Anda tingkatkan mungkin sudah memasang paket NuGet Microsoft.Windows.CppWinRT, atau mungkin juga belum.

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

Konfigurasi pemutakhiran tidak valid

Dengan versi terbaru ekstensi VSIX, sebuah proyek tidak valid jika memiliki properti <CppWinRTEnabled>true</CppWinRTEnabled> tetapi tidak memasang paket NuGet Microsoft.Windows.CppWinRT. Proyek dengan konfigurasi ini menghasilkan pesan kesalahan build, "C++/WinRT VSIX tidak lagi menyediakan dukungan build proyek. Harap 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 Anda berisi <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>, Anda dapat menghapusnya agar dapat melakukan build tanpa perlu memasang ekstensi VSIX C++/WinRT.

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 (API Windows Runtime di Windows namespace). Header tersebut berada di dalam folder %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. Pada SDK Windows versi 10.0.17763.0 (Windows 10, versi 1809), header ini dibuat untuk Anda di dalam folder $(GeneratedFilesDir) proyek Anda.

Sekali lagi untuk kompatibilitas, Windows SDK juga dilengkapi dengan alat inicppwinrt.exe. Namun, kami menyarankan agar Anda menginstal dan menggunakan versi terbaru dari cppwinrt.exe, yang disertakan dalam paket NuGet Microsoft.Windows.CppWinRT. 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 di beberapa titik. Namun, kemungkinan kecil Anda akan langsung menggunakan tipe 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++.

Warning

Ada juga tipe yang mungkin Anda temui jika Anda mempelajari dengan saksama header namespace Windows pada C++/WinRT. Salah satu contohnya adalah winrt::param::hstring, tetapi ada juga contoh koleksi. 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 dalam proyeksi ketika memberikan nilai paling besar. 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 tipe implementasi dan karena itu dapat berubah sewaktu-waktu. Anda harus tetap menggunakan jenis standar, atau jenis dari namespace winrt.

Lihat juga Meneruskan parameter ke dalam batas ABI.

API penting

  • Last updated on