Pengantar C++/WinRT

  • Artikel

 

 

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 mengoperasikan 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 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 WINDOWS Runtime API

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.

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 beban kerja pengembangan Platform Windows Universal. Dalam Detail> Penginstalan Platform Windows Universal pengembangan, periksa opsi alat Platform Windows Universal C++ (v14x) jika Anda belum melakukannya. Dan, di Windows Pengaturan> Privacy & security (Windows 10: Update & Security)> 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; memberikan pengalaman yang mirip dengan penelusuran kesalahan C#. Natvis otomatis untuk build debug. Untuk informasi 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 di Visual Studio.
  • Selain itu, ini memberi Anda visualisasi debug asli Visual Studio (natvis) dari jenis 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 menambahkan paket, Anda akan mendapatkan dukungan C++/WinRT MSBuild untuk proyek, termasuk memanggil alat.cppwinrt.exe

Penting

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) 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 Kesuaian: Ya (/permisif-), yang selanjutnya membatasi kode Anda agar sesuai standar.
  • Properti proyek lain yang perlu diperhatikan adalah C/C++>General>Treat Warnings As Errors. 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 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 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. File metadata Windows Runtime (.winmd) menyediakan cara kanonis untuk menjelaskan permukaan Windows Runtime API. Dengan mengarahkan cppwinrt.exe metadata, Anda dapat membuat pustaka untuk digunakan dengan kelas runtime apa pun yang diterapkan dalam komponen Windows Runtime pihak kedua atau ketiga, atau 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 jenis Anda dalam file IDL, dan dan midl.execppwinrt.exe membuat 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 alatcppwinrt.exe, atur melalui properti proyek, lihat readme paket NuGet Microsoft.Windows.CppWinRT.

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 Kosong (C++/WinRT)

Templat proyek untuk aplikasi Platform Windows Universal (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 buat proyek sekali untuk menghasilkan templat implementasi dalam Generated Filesdefinisi jenis , dan stub di Generated Files\sources. Kemudian gunakan definisi jenis stub tersebut untuk referensi guna mengimplementasikan kelas runtime lokal Anda. Lihat Memperhitungkan 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 Platform Windows Universal (UWP) yang tidak menggunakan XAML.

Sebaliknya, ia menggunakan header namespace layanan Windows C++/WinRT untuk namespace Windows.ApplicationModel.Core. Setelah membangun dan menjalankan, klik ruang 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)

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 konsumsi dari Platform Windows Universal (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. Buat proyek sekali untuk menghasilkan module.g.cppmodule.h.cpp, , templat implementasi dalam Generated Filesdefinisi jenis , dan stub di Generated Files\sources. Kemudian gunakan definisi jenis stub untuk referensi guna mengimplementasikan kelas runtime dalam komponen Anda. Lihat Memperhitungkan kelas runtime ke dalam file Midl (.idl).

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

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 yang <CppWinRTEnabled>true</CppWinRTEnabled> diatur dalam .vcxproj file.

<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 anda melakukannya, maka—karena dukungan build juga masih ada dalam versi ekstensi VSIX dalam rentang ini—proyek yang ditingkatkan mungkin atau mungkin tidak menginstal paket NuGet Microsoft.Windows.CppWinRT .

Untuk meningkatkan proyek Anda, ikuti instruksi di bagian sebelumnya dan pastikan bahwa proyek Anda telah menginstal paket NuGet Microsoft.Windows.CppWinRT .

Konfigurasi peningkatan tidak valid

Dengan versi terbaru ekstensi VSIX, tidak valid bagi proyek untuk memiliki <CppWinRTEnabled>true</CppWinRTEnabled> properti jika tidak juga menginstal paket NuGet Microsoft.Windows.CppWinRT . 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 berisi .vcxproj<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 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.

Sekali lagi untuk kompatibilitas, Windows SDK juga dilengkapi dengan alat ini cppwinrt.exe . Namun, kami sarankan Anda menginstal dan menggunakan versi terbaru , cppwinrt.exeyang disertakan dengan 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. Tetapi Anda cenderung tidak 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 lihat jika Anda mempelajari header namespace layanan Windows C++/WinRT dengan cerah. Contohnya adalah winrt::p aram::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 ini hanya pernah digunakan oleh proyeksi dalam kasus di mana mereka menambahkan sebagian besar nilai. Mereka sangat dioptimalkan dan tidak digunakan secara umum; jangan tergoda untuk menggunakannya sendiri. Anda juga tidak boleh menggunakan apa pun dari winrt::impl namespace layanan, karena itu adalah jenis implementasi, dan karenanya dapat berubah. Anda harus terus menggunakan jenis standar, atau jenis dari namespace winrt.

Lihat juga Meneruskan parameter ke dalam batas ABI.

API penting