Bagikan melalui

Mulai menggunakan C++/WinRT

Penting

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 penggunaan C++/WinRT, topik ini membahas contoh kode sederhana berdasarkan project aplikasi konsol Windows (C++/WinRT) baru . Topik ini juga menunjukkan cara menambahkan dukungan C++/WinRT ke proyek aplikasi Windows Desktop.

Nota

Meskipun kami menyarankan agar Anda mengembangkan dengan versi terbaru Visual Studio dan Windows SDK, jika Anda menggunakan Visual Studio 2017 (versi 15.8.0 atau yang lebih baru), dan menargetkan Windows SDK versi 10.0.17134.0 (Windows 10, versi 1803), 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 Windows SDK yang lebih baru (lebih sesuai), atau atur properti proyek C/C++>Mode Kesesuaian>Bahasa: Tidak ada (juga, jika /permisif- muncul di properti proyek C/C++>Language>Command Line di bawah Opsi Tambahan, lalu hapus).

Panduan Cepat C++/WinRT

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

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 Windows SDK, di dalam folder %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. Visual Studio menyertakan jalur tersebut dalam makro IncludePath. Tetapi tidak ada dependensi ketat pada Windows SDK, karena proyek Anda (melalui alat ) menghasilkan header yang sama ke folder proyek Anda $(GeneratedFilesDir). 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 jenis Windows, C++/WinRT mendefinisikan setara yang mendukung C++ (yang disebut jenis proyeksi ). Jenis yang diproyeksikan memiliki nama yang sepenuhnya memenuhi syarat yang sama dengan jenis Windows, tetapi ditempatkan di C++ winrt namespace. Dengan memasukkan ini dalam header terdahulu yang telah dikompilasi, waktu build bertahap berkurang.

Penting

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

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;

Arahan 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 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 C++/CX dan/atau antarmuka biner aplikasi SDK (ABI) (Anda sedang memindahkan dari, atau berinteraksi dengan, satu atau kedua model tersebut), lalu mengacu pada 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 thread di Windows Runtime; secara bawaan, di apartemen multithreaded. Panggilan juga menginisialisasi COM.

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

Mengalokasikan dua objek di stack: yang mewakili URI blog Windows, dan klien sindikasi. Kami membangun uri dengan literal string lebar sederhana (lihat penanganan String di C++/WinRT untuk cara lain Anda dapat bekerja dengan string).

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

SyndicationClient::RetrieveFeedAsync adalah contoh fungsi Windows Runtime asinkron. Contoh kode menerima objek operasi asinkron dari RetrieveFeedAsync, dan memanggil get pada objek tersebut untuk memblokir thread yang melakukan panggilan dan menunggu hasilnya (yang merupakan feed sindikasi, dalam hal ini). Untuk informasi selengkapnya tentang keserentakan, dan untuk teknik non-pemblokiran, lihat Keserentakan dan operasi asinkron dengan C++/WinRT.

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

SyndicationFeed.Items adalah rentang, yang ditentukan oleh pengiterasi yang dikembalikan oleh fungsi mulai dan akhir (atau varian konstanta, terbalik, dan konstanta-terbalik). Karena itu, Anda dapat menghitung Item dengan pernyataan for berbasis rentang, atau dengan fungsi templat std::for_each. Setiap kali Anda melakukan iterasi melalui 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 dikeluarkan melalui fungsi c_str, yang mencerminkan pola yang digunakan dengan string dari Pustaka Standar C++.

Seperti yang Anda lihat, C++/WinRT mendorong penggunaan ekspresi C++ modern yang mirip dengan 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 informasi lebih lanjut, lihat dukungan Visual Studio untuk C++/WinRT.

Mengatur properti proyek

Buka properti proyek Umum>Versi Windows SDK, dan pilih Semua Konfigurasi dan Semua Platform. Pastikan Windows SDK Version diatur ke 10.0.17134.0 (Windows 10, versi 1803) atau yang 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 dikompilasi sebelumnya untuk Anda, bernama framework.h, atau stdafx.h. Ganti nama itu menjadi pch.h. Jika Anda memiliki file stdafx.cpp, ganti namanya menjadi pch.cpp. Atur properti proyek C/C++>Header Pra-kompilasi>Header Pra-kompilasi ke Buat (/Yc), dan File Header Pra-kompilasi ke pch.h.

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

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

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

Menghubungkan

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

Opsi pertama adalah menambahkan ke proyek Visual Studio Anda semua properti dan target C++/WinRT MSBuild. Untuk melakukan ini, instal paket NuGet Microsoft.Windows.CppWinRT ke dalam proyek Anda. Buka proyek di Visual Studio, klik Project>Kelola Paket NuGet...>Telusuri, ketik atau tempel Microsoft.Windows.CppWinRT di kotak pencarian, pilih item dalam hasil pencarian, lalu klik Instal untuk menginstal paket untuk proyek tersebut.

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

#pragma comment(lib, "windowsapp")

Anda sekarang dapat mengkompilasi dan menautkan, serta menambahkan kode C++/WinRT ke proyek Anda (misalnya, kode yang mirip dengan yang ditampilkan di bagian A C++/WinRT mulai cepat, 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.

Mengonsumsi API dan jenis-jenis Windows

Dengan kata lain, menggunakan API, atau memanggil. 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 Mengonsumsi API menggunakan C++/WinRT.

Penulisan API dan jenis Windows

Dengan kata lain, memproduksi API dan jenis. 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 Author APIs dengan C++/WinRT.

Penulisan API dengan C++/WinRT sedikit lebih rumit daripada mengonsumsinya, karena Anda perlu menggunakan IDL untuk menentukan struktur API sebelum Anda dapat mengimplementasikannya. Ada panduan untuk melakukannya dalam kontrol XAML ; ikat ke properti C++/WinRT.

Aplikasi XAML

Skenario ini adalah tentang membangun aplikasi dan kontrol pada kerangka kerja UI XAML. Bekerja dalam aplikasi XAML melibatkan kombinasi memanfaatkan dan mengembangkan. Tetapi karena XAML adalah kerangka kerja UI yang dominan pada Windows saat ini, dan pengaruhnya atas 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 bagus untuk memulai adalah kontrol XAML ; mengikat ke properti C++/WinRT dan kontrol kustom XAML yang di-template 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