Mulai menggunakan C++/WinRT

Important

Untuk informasi tentang menyiapkan Visual Studio untuk pengembangan C++/WinRT—termasuk menginstal dan menggunakan C++/WinRT Visual Studio Extension (VSIX) dan paket NuGet (yang bersama-sama menyediakan templat proyek dan dukungan build)—lihat dukungan Visual Studio untuk C++/WinRT.

Untuk mempercepat Anda menggunakan C++/WinRT, topik ini membahas contoh kode sederhana berdasarkan proyek aplikasi konsol Windows baru (C++/WinRT). Topik ini juga menunjukkan cara menambahkan dukungan C++/WinRT ke proyek aplikasi Windows Desktop.

Note

Meskipun kami menyarankan agar Anda mengembangkan dengan versi terbaru Visual Studio dan SDK Windows, jika Anda menggunakan Visual Studio 2017 (versi 15.8.0 atau yang lebih baru), dan menargetkan SDK Windows versi 10.0.17134.0 (Windows 10, versi 1803), maka proyek C++/WinRT yang baru dibuat mungkin gagal dikompilasi dengan kesalahan "kesalahan C3861: 'from_abi': pengidentifikasi tidak ditemukan", dan dengan kesalahan lain yang berasal dari base.h. Solusinya adalah menargetkan versi yang lebih baru (lebih sesuai) dari Windows SDK, atau mengatur properti proyek C/C++>Mode Kesuaian>: Tidak (juga, jika /permisif- muncul di properti proyek C/C++>Language>Command Line di bawah Opsi Tambahan, lalu hapus).

Panduan singkat C++/WinRT

Buat proyek Aplikasi Konsol Windows baru (C++/WinRT).

Edit pch.h dan main.cpp agar terlihat seperti ini.

// pch.h
#pragma once
#include <winrt/Windows.Foundation.Collections.h>
#include <winrt/Windows.Web.Syndication.h>
#include <iostream>

// main.cpp
#include "pch.h"

using namespace winrt;
using namespace Windows::Foundation;
using namespace Windows::Web::Syndication;

int main()
{
    winrt::init_apartment();

    Uri rssFeedUri{ L"https://blogs.windows.com/feed" };
    SyndicationClient syndicationClient;
    syndicationClient.SetRequestHeader(L"User-Agent", L"Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0)");
    SyndicationFeed syndicationFeed = syndicationClient.RetrieveFeedAsync(rssFeedUri).get();
    for (const SyndicationItem syndicationItem : syndicationFeed.Items())
    {
        winrt::hstring titleAsHstring = syndicationItem.Title().Text();
        
        // A workaround to remove the trademark symbol from the title string, because it causes issues in this case.
        std::wstring titleAsStdWstring{ titleAsHstring.c_str() };
        titleAsStdWstring.erase(remove(titleAsStdWstring.begin(), titleAsStdWstring.end(), L'™'), titleAsStdWstring.end());
        titleAsHstring = titleAsStdWstring;

        std::wcout << titleAsHstring.c_str() << std::endl;
    }
}

Mari kita ambil contoh kode pendek di atas sepotong demi sepotong, dan jelaskan apa yang terjadi di setiap bagian.

#include <winrt/Windows.Foundation.Collections.h>
#include <winrt/Windows.Web.Syndication.h>

Dengan pengaturan proyek default, header yang disertakan berasal dari SDK Windows, di dalam folder %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. Visual Studio menyertakan jalur tersebut dalam makro IncludePath-nya. Tetapi tidak ada dependensi ketat pada SDK Windows, karena proyek Anda (melalui cppwinrt.exe alat) menghasilkan header yang sama ke folder $(GeneratedFilesDir) proyek Anda. Mereka akan dimuat dari folder tersebut jika tidak dapat ditemukan di tempat lain, atau jika Anda mengubah pengaturan proyek Anda.

Header berisi API Windows yang diproyeksikan ke dalam C++/WinRT. Dengan kata lain, untuk setiap tipe Windows, C++/WinRT mendefinisikan padanan yang ramah C++ (disebut tipe terproyeksi). Jenis yang diproyeksikan memiliki nama yang sepenuhnya memenuhi syarat yang sama dengan jenis Windows, tetapi ditempatkan di namespace C++ winrt. Menempatkan ini termasuk dalam header yang telah dikommpilasikan sebelumnya mengurangi waktu build inkremental.

Important

Setiap kali Anda ingin menggunakan tipe dalam namespace Windows, Anda harus #include file header namespace Windows C++/WinRT yang sesuai, seperti yang ditunjukkan di atas. Header yang sesuai adalah header dengan nama yang sama dengan namespace tipe. Misalnya, untuk menggunakan proyeksi C++/WinRT untuk kelas runtime Windows::Foundation::Collections::P ropertySet, sertakan winrt/Windows.Foundation.Collections.h header.

Biasanya header proyeksi C++/WinRT secara otomatis menyertakan file header namespace terkait. Misalnya, winrt/Windows.Foundation.Collections.h termasuk winrt/Windows.Foundation.h. Tetapi Anda tidak boleh mengandalkan perilaku ini, karena ini adalah detail implementasi yang berubah dari waktu ke waktu. Anda harus secara eksplisit menyertakan header apa pun yang Anda butuhkan.

using namespace winrt;
using namespace Windows::Foundation;
using namespace Windows::Web::Syndication;

Direktif using namespace bersifat opsional, tetapi nyaman. Pola yang ditunjukkan di atas untuk arahan tersebut (memungkinkan pencarian nama yang tidak memenuhi syarat untuk apa pun di namespace winrt ) cocok untuk ketika Anda memulai proyek baru dan C++/WinRT adalah satu-satunya proyeksi bahasa yang Anda gunakan di dalam proyek tersebut. Jika, di sisi lain, Anda mencampur kode C++/WinRT dengan kode antarmuka biner aplikasi C++/CX dan/atau SDK (ABI) (Anda menggunakan porting, atau beroperasi dengan, satu atau kedua model tersebut), lalu lihat topik Interop antara C++/WinRT dan C++/CX, Pindah ke C++/WinRT dari C++/CX, dan Interop antara C++/WinRT dan ABI.

winrt::init_apartment();

Panggilan ke winrt::init_apartment menginisialisasi utas dalam Windows Runtime; secara bawaan, dalam apartemen multithread. Pemanggilan ini juga menginisialisasi COM.

Uri rssFeedUri{ L"https://blogs.windows.com/feed" };
SyndicationClient syndicationClient;

Alokasikan dua objek di stack: objek tersebut merepresentasikan URI blog Windows dan klien sindikasi. Kami membuat URI dengan literal wide string yang sederhana (lihat Penanganan string di C++/WinRT untuk mengetahui cara lain dalam menangani string).

SyndicationFeed syndicationFeed = syndicationClient.RetrieveFeedAsync(rssFeedUri).get();

SyndicationClient::RetrieveFeedAsync adalah contoh fungsi Windows Runtime asinkron. Contoh kode menerima objek operasi asinkron dari RetrieveFeedAsync, lalu memanggil get pada objek tersebut untuk memblokir utas pemanggil dan menunggu hasilnya (yang dalam hal ini berupa umpan sindikasi). Untuk informasi selengkapnya tentang konkurensi, dan untuk teknik non-pemblokiran, lihat Operasi konkurensi dan asinkron dengan C++/WinRT.

for (const SyndicationItem syndicationItem : syndicationFeed.Items()) { ... }

SyndicationFeed.Items merupakan rentang yang ditentukan oleh iterator yang dikembalikan oleh fungsi begin dan end (atau varian konstan, balik, dan balik-konstan). Karena itu, Anda dapat mengiterasi Items dengan pernyataan for berbasis rentang, atau dengan fungsi templat std::for_each. Setiap kali Anda melakukan iterasi atas koleksi Windows Runtime seperti ini, Anda harus #include <winrt/Windows.Foundation.Collections.h>.

winrt::hstring titleAsHstring = syndicationItem.Title().Text();

// Omitted: there's a little bit of extra work here to remove the trademark symbol from the title text.

std::wcout << titleAsHstring.c_str() << std::endl;

Mendapatkan teks judul umpan, sebagai objek winrt::hstring (detail selengkapnya dalam penanganan String di C++/WinRT). Hstring kemudian dihasilkan, melalui fungsi c_str, yang mencerminkan pola yang digunakan dengan string Pustaka Standar C++.

Seperti yang Anda lihat, C++/WinRT mendorong penggunaan ekspresi C++ modern yang bergaya kelas, seperti syndicationItem.Title().Text(). Ini adalah gaya pemrograman yang berbeda, dan lebih bersih dari pemrograman COM tradisional. Anda tidak perlu langsung menginisialisasi COM, atau bekerja dengan penunjuk COM.

Anda juga tidak perlu menangani kode pengembalian HRESULT. C++/WinRT mengonversi kesalahan HRESULT menjadi pengecualian seperti winrt::hresult-error untuk gaya pemrograman alami dan modern. Untuk informasi selengkapnya tentang penanganan kesalahan, dan contoh kode, lihat Penanganan kesalahan dengan C++/WinRT.

Mengubah proyek aplikasi Windows Desktop untuk menambahkan dukungan C++/WinRT

Beberapa proyek desktop (misalnya, templat WinUI 3 di Visual Studio) memiliki dukungan C++/WinRT bawaan.

Tetapi bagian ini menunjukkan kepada Anda bagaimana Anda dapat menambahkan dukungan C++/WinRT ke proyek aplikasi Windows Desktop apa pun yang mungkin Anda miliki. Jika Anda tidak memiliki proyek aplikasi Windows Desktop yang sudah ada, maka Anda dapat mengikuti langkah-langkah ini dengan terlebih dahulu membuatnya. Misalnya, buka Visual Studio dan buat proyek Visual C++>Windows Desktop>Windows Desktop Application.

Anda dapat secara opsional menginstal C++/WinRT Visual Studio Extension (VSIX) dan paket NuGet. Untuk detailnya, lihat dukungan Visual Studio untuk C++/WinRT.

Mengatur properti proyek

Buka properti proyek Versi Umum>Windows SDK, dan pilih Semua Konfigurasi dan Semua Platform. Pastikan versi SDK Windows diatur ke 10.0.17134.0 (Windows 10, versi 1803) atau lebih tinggi.

Konfirmasikan bahwa Anda tidak terpengaruh oleh Mengapa proyek baru saya tidak dikompilasi?.

Karena C++/WinRT menggunakan fitur dari standar C++17, atur properti proyek C/C++>Language>C++ Language Standard ke ISO C++17 Standard (/std:c++17).

Header yang telah dikommpilasikan sebelumnya

Templat proyek default membuat header yang telah dikommpilasikan sebelumnya untuk Anda, bernama framework.h, atau stdafx.h. Ganti nama itu menjadi pch.h. Jika Anda memiliki stdafx.cpp file, maka ganti namanya menjadi pch.cpp. Atur properti proyek C/C++>Header Prakomputasi>Header Prakomputasi menjadi Buat (/Yc), dan File Header Prakomputasi menjadi pch.h.

Temukan dan ganti semua #include "framework.h" (atau #include "stdafx.h") dengan #include "pch.h".

Dalam pch.h, sertakan winrt/base.h.

// pch.h
...
#include <winrt/base.h>

Menghubungkan

Proyeksi bahasa C++/WinRT bergantung pada fungsi Windows Runtime gratis (non-anggota) tertentu, dan titik masuk, yang memerlukan penautan ke pustaka payung WindowsApp.lib. Bagian ini menjelaskan tiga cara untuk memuaskan linker.

Opsi pertama adalah menambahkan ke proyek Visual Studio Anda semua properti dan target C++/WinRT MSBuild. Untuk melakukannya, instal paket NuGet Microsoft.Windows.CppWinRT di proyek Anda. Buka project 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.

Anda juga dapat menggunakan pengaturan tautan proyek untuk menautkan WindowsApp.libsecara eksplisit . Atau, Anda dapat melakukannya dalam kode sumber (di pch.h, misalnya) seperti ini.

#pragma comment(lib, "windowsapp")

Anda sekarang dapat mengkompilasi dan menautkan, dan menambahkan kode C++/WinRT ke proyek Anda (misalnya, kode yang mirip dengan yang ditunjukkan di bagian mulai cepat A C++/WinRT , di atas).

Tiga skenario utama untuk C++/WinRT

Saat Anda menggunakan dan terbiasa dengan C++/WinRT, dan bekerja melalui sisa dokumentasi di sini, Anda mungkin akan melihat bahwa ada tiga skenario utama, seperti yang dijelaskan di bagian berikut.

Menggunakan API dan tipe Windows

Dengan kata lain, menggunakan, atau memanggil API. Misalnya, melakukan panggilan API untuk berkomunikasi menggunakan Bluetooth; untuk melakukan streaming dan menyajikan video; untuk berintegrasi dengan shell Windows; dan sebagainya. C++/WinRT sepenuhnya dan tanpa kompromi mendukung kategori skenario ini. Untuk informasi selengkapnya, lihat Menggunakan API dengan C++/WinRT.

Penyusunan Windows API dan tipe

Dengan kata lain, menghasilkan API dan tipe. Misalnya, memproduksi jenis API yang dijelaskan di bagian di atas; atau API grafis; API penyimpanan dan sistem file; API jaringan, dan sebagainya. Untuk informasi selengkapnya, lihat API Penulis dengan C++/WinRT.

Membuat API dengan C++/WinRT sedikit lebih rumit daripada mengonsumsinya, karena Anda harus menggunakan IDL untuk mendefinisikan struktur API sebelum dapat mengimplementasikannya. Ada panduan langkah demi langkah untuk melakukannya di kontrol XAML; mengikat ke properti C++/WinRT.

Aplikasi XAML

Skenario ini adalah tentang membangun aplikasi dan kontrol pada kerangka kerja UI XAML. Bekerja dalam aplikasi XAML merupakan gabungan antara menggunakan dan membuat. Tetapi karena XAML adalah kerangka kerja UI yang dominan pada Windows hari ini, dan pengaruhnya terhadap Windows Runtime sebanding dengan itu, ia layak mendapatkan kategori skenarionya sendiri.

Ketahuilah bahwa XAML berfungsi paling baik dengan bahasa pemrograman yang menawarkan refleksi. Di C++/WinRT, Terkadang Anda harus melakukan sedikit pekerjaan ekstra untuk beroperasi dengan kerangka kerja XAML. Semua kasus tersebut tercakup dalam dokumentasi. Tempat yang baik untuk memulai adalah kontrol XAML; mengikat ke properti C++/WinRT dan kontrol kustom XAML (templat) dengan C++/WinRT.

Contoh aplikasi yang ditulis dalam C++/WinRT

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

API penting

  • Last updated on