Pengantar C ++/WinRT

  • Artikel
  • 10 menit untuk membaca

 

 

C ++/WinRT adalah proyeksi bahasa C ++17 modern yang sepenuhnya standar untuk API Windows Runtime (WinRT), diimplementasikan sebagai pustaka berbasis file header, dan dirancang untuk memberi Anda akses kelas satu ke API Windows modern. Dengan C ++/WinRT, Anda dapat menulis dan mengkonsumsi API Runtime Windows menggunakan kompiler C ++17 yang sesuai dengan standar. SDK Windows mencakup C ++/WinRT; diperkenalkan di versi 10.0.17134.0 (Windows 10, versi 1803).

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

Penting

Beberapa bagian terpenting dari C ++/WinRT yang harus 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

runtime Windows didasarkan pada API Component Object 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 API Runtime Windows

Saat Anda menjelajah api Runtime Windows, 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, Visual Studio 2019, atau Visual Studio 2017 (setidaknya versi 15.6; kami sarankan setidaknya 15.7). Dari dalam Penginstal Visual Studio, instal beban kerja pengembangan Universal Windows Platform. Dalam pengembangan Platform>Windows Detail InstalasiUniversal, periksa opsi alat Universal Windows Platform C ++ (v14x), jika Anda belum melakukannya. Dan, di Windows Pengaturan>Update & SecurityUntuk>pengembang, pilih opsi mode Pengembang daripada opsi aplikasi Sideload.

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

Visual Studio tahun 2022 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 yang diproyeksikan C ++/ WinRT; memberikan pengalaman yang mirip dengan debugging C #. Natvis otomatis untuk build debug. Untuk info selengkapnya, lihat Visual Studio visualisasi debug asli 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 dalam Visual Studio.
  • Selain itu, ini memberi Anda visualisasi debug asli Visual Studio (natvis) dari jenis yang diproyeksikan 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 Microsoft.Windows. Paket CppWinRT NuGet. Microsoft.Windows. Paket CppWinRT NuGet 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 sudah ada dengan menginstal Microsoft.Windows secara manual. Paket CppWinRT NuGet. Setelah menginstal (atau memperbarui ke) versi terbaru ekstensi VSIX, buka proyek yang ada di Visual Studio, klik Project>Menmenyeat NuGet Paket...>Telusuri, ketik, atau tempelkan Microsoft.Windows. CppWinRT di kotak pencarian, pilih item di hasil pencarian, lalu klik Instal untuk menginstal paket untuk proyek tersebut. Setelah menambahkan paket, Anda akan mendapatkan dukungan C ++/WinRT MSBuild untuk proyek tersebut, termasuk menggunakan alat tersebut cppwinrt.exe .

Penting

Jika Anda memiliki proyek yang dibuat dengan (atau ditingkatkan untuk dikerjakan) versi ekstensi VSIX lebih awal dari 1.0.190128.4, lihat Versi ekstensi VSIX yang lebih lama. Bagian itu 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++>LanguageC>++ Standar BahasaISO>C++17 (/std:c++17) di Visual Studio.
  • Ini juga menambahkan opsi kompiler /bigobj .
  • Ini menambahkan opsi kompiler /await untuk mengaktifkan co_await.
  • Ini menginstruksikan kompiler XAML untuk memancarkan codegen C ++/WinRT.
  • Anda mungkin juga ingin mengatur mode Kesesuaian: Ya (/permisif-), yang selanjutnya membatasi kode Anda agar sesuai dengan standar.
  • Properti proyek lain yang harus diperhatikan adalah C / C + +>GeneralTreat>Warnings As Errors. Atur ini ke Ya (/WX) atau Tidak (/WX-) secukupnya. Terkadang, file sumber yang dihasilkan oleh alat menghasilkan cppwinrt.exe peringatan hingga Anda menambahkan implementasi ke dalamnya.

Dengan sistem Anda diatur 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, Microsoft.Windows. Paket CppWinRT NuGet menyertakan alat inicppwinrt.exe. Anda dapat mengarahkan alat pada cppwinrt.exe file metadata Windows Runtime (.winmd) untuk menghasilkan pustaka C++ standar berbasis file header yang memproyeksikan API yang dijelaskan dalam metadata untuk dikonsumsi dari kode C++/WinRT. Windows File metadata Runtime (.winmd) menyediakan cara kanonis untuk menggambarkan permukaan API Runtime Windows. Dengan menunjuk cppwinrt.exe metadata, Anda dapat membuat pustaka untuk digunakan dengan kelas runtime apa pun yang diimplementasikan dalam komponen Runtime Windows pihak kedua atau ketiga, atau diimplementasikan dalam aplikasi Anda sendiri. Untuk info selengkapnya, lihat Konsumsi API dengan C++/WinRT.

Dengan C ++/WinRT, Anda juga dapat menerapkan kelas runtime Anda sendiri menggunakan C ++standar, tanpa menggunakan pemrograman bergaya COM. Untuk kelas runtime, Anda cukup menjelaskan jenis Anda dalam file IDL, dan midl.exe dan cppwinrt.exe menghasilkan file kode sumber boilerplate implementasi untuk Anda. Anda dapat menerapkan antarmuka dengan berasal dari kelas dasar C ++/WinRT. Untuk info selengkapnya, lihat API Penulis dengan C++/WinRT.

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

Anda dapat mengidentifikasi proyek yang menggunakan dukungan C++/WinRT MSBuild dengan kehadiran Microsoft.Windows. Paket CppWinRT NuGet yang dipasang di dalam proyek.

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

Aplikasi Kosong (C++/WinRT)

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

Visual Studio menyediakan dukungan kompiler XAML untuk menghasilkan implementasi dan rintisan 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 rujuk di halaman XAML aplikasi Anda, lalu buat proyek sekali untuk menghasilkan templat implementasi dalam Generated Files, dan definisi jenis rintisan di Generated Files\sources. Kemudian gunakan definisi tipe rintisan tersebut untuk referensi untuk mengimplementasikan kelas runtime lokal Anda. Lihat Mengfaktorkan 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 dari jendela Properti untuk menambahkan penangan peristiwa dalam proyek C ++/WinRT. Anda juga dapat menambahkan penangan peristiwa ke kode Anda secara manual—lihat Menangani peristiwa dengan menggunakan delegasi di C++/WinRT untuk info lebih lanjut.

Aplikasi Inti (C++/WinRT)

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

Sebagai gantinya, ia menggunakan header C ++/WinRT Windows namespace untuk Windows. Namespace ApplicationModel.Core. Setelah membangun dan berjalan, klik pada ruang kosong untuk menambahkan kotak berwarna; lalu klik kotak 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 Desktop Windows, yang menampilkan Windows Runtime Windows. Foundation.Uri di dalam Kotak Pesan Win32.

Komponen Runtime Windows (C++/WinRT)

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

Template ini menunjukkan midl.exe>cppwinrt.exe toolchain, di mana metadata runtime Windows (.winmd) dihasilkan dari IDL, dan kemudian implementasi dan rintisan header dihasilkan dari metadata Runtime Windows.

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.cpptemplate implementasi dalam Generated Files, dan definisi jenis rintisan di Generated Files\sources. Kemudian gunakan definisi jenis rintisan tersebut untuk referensi untuk menerapkan kelas runtime di komponen Anda. Lihat Mengfaktorkan kelas runtime ke dalam file Midl (.idl).

Bundel biner komponen runtime Windows bawaan .winmd dan dengan aplikasi UWP yang memakannya.

Versi ekstensi VSIX yang lebih lama

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

Dalam hal versi SDK dan Visual Studio Windows yang didukung, dan konfigurasi Visual Studio, info di Visual Studio dukungan 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 lebih awal dari 1.0.181002.2, maka dukungan build C++/WinRT dibangun ke dalam versi ekstensi VSIX tersebut. Proyek Anda memiliki properti yang <CppWinRTEnabled>true</CppWinRTEnabled> diatur dalam .vcxproj file.

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

Anda dapat meningkatkan proyek dengan menginstal Microsoft.Windows secara manual. Paket CppWinRT NuGet. Setelah menginstal (atau memutakhirkan ke) versi terbaru ekstensi VSIX, buka proyek Anda di Visual Studio, klik Project>Menmenyeat Paket NuGet...>Telusuri, ketik, atau tempelkan 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 Microsoft.Windows. Paket CppWinRT NuGet diinstal di proyek secara otomatis oleh templat proyek. Anda mungkin juga telah meningkatkan proyek yang lebih lama untuk menggunakan versi ekstensi VSIX dalam rentang ini. Jika Anda melakukannya, maka—karena dukungan build juga masih ada dalam versi ekstensi VSIX dalam rentang ini—proyek anda yang ditingkatkan mungkin atau mungkin tidak memiliki Microsoft.Windows. Paket CppWinRT NuGet diinstal.

Untuk meningkatkan proyek Anda, ikuti petunjuk di bagian sebelumnya dan pastikan bahwa proyek Anda memiliki Microsoft.Windows. Paket CppWinRT NuGet diinstal.

Konfigurasi pemutakhiran tidak valid

Dengan versi terbaru dari ekstensi VSIX, tidak valid bagi proyek untuk memiliki <CppWinRTEnabled>true</CppWinRTEnabled> properti jika tidak juga memiliki Microsoft.Windows. Paket CppWinRT NuGet diinstal. Sebuah proyek dengan konfigurasi ini menghasilkan pesan kesalahan build, "C ++/WinRT VSIX tidak lagi menyediakan dukungan build proyek. Silakan tambahkan referensi proyek ke Microsoft. Windows. Paket CppWinRT Nuget."

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

<CppWinRTEnabled> Karena elemen sekarang sudah usang, Anda dapat mengedit , dan menghapus elemen secara .vcxprojopsional. Ini tidak sepenuhnya diperlukan, tetapi itu adalah pilihan.

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

Dukungan SDK untuk C++/WinRT

Meskipun sekarang hadir hanya untuk alasan kompatibilitas, pada versi 10.0.17134.0 (Windows 10, versi 1803), SDK Windows berisi pustaka C ++ standar berbasis file header untuk mengkonsumsi API Windows pihak pertama (api runtime Windows di ruang nama Windows). 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, SDK Windows juga dilengkapi dengan alat inicppwinrt.exe. Namun, kami sarankan Anda menginstal dan menggunakan versi cppwinrt.exeterbaru , yang disertakan dengan Microsoft.Windows. Paket CppWinRT NuGet. Paket itu, dan cppwinrt.exe, dijelaskan pada bagian di atas.

Jenis kustom dalam proyeksi C++/WinRT

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

winrt::com_array adalah jenis lain yang mungkin Anda gunakan di beberapa titik. Tetapi Anda cenderung tidak langsung menggunakan jenis seperti winrt: : array_view. Atau Anda dapat memilih untuk tidak menggunakannya sehingga Anda tidak akan memiliki kode untuk diubah jika dan ketika jenis yang setara muncul di Perpustakaan Standar C ++.

Peringatan

Ada juga jenis yang mungkin Anda lihat jika Anda mempelajari dengan cermat header C ++/ WinRT Windows namespace. Contohnya adalah winrt::p aram::hstring, tetapi ada contoh koleksi juga. Ini ada semata-mata untuk mengoptimalkan pengikatan parameter input, dan mereka menghasilkan peningkatan kinerja yang besar dan membuat sebagian besar pola panggilan "hanya berfungsi" untuk jenis dan kontainer C ++ standar terkait. Jenis ini hanya pernah digunakan oleh proyeksi dalam kasus di mana mereka menambah nilai paling banyak. Mereka sangat dioptimalkan dan mereka bukan untuk penggunaan umum; Jangan tergoda untuk menggunakannya sendiri. Anda juga tidak boleh menggunakan apa pun dari winrt::impl namespace, karena itu adalah jenis implementasi, dan karena itu dapat berubah. Anda harus terus menggunakan jenis standar, atau jenis dari namespace winrt.

Lihat juga Melewati parameter ke batas ABI.

API Penting