A C++/WinRT használatának első lépései

A C++/WinRT használatának felgyorsításához ez a témakör egy új Windows konzolalkalmazási (C++/WinRT) projekten alapuló egyszerű kódpéldát mutat be. Ez a témakör azt is bemutatja, hogyan adhat hozzá C++/WinRT-támogatást egy Windows asztali alkalmazásprojekthez.

C++/WinRT gyorsútmutató

Hozzon létre egy új Windows konzolalkalmazási (C++/WinRT) projektet.

Szerkessze a(z) pch.h és main.cpp elemeket, hogy így nézzenek ki.

// 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;
    }
}

Vegyük a fenti rövid kód példáját darabonként, és ismertessük az egyes részeket.

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

Az alapértelmezett projektbeállításokkal a belefoglalt fejlécek a Windows SDK-ból származnak a mappában%WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. Visual Studio tartalmazza ezt az elérési utat az IncludePath makróban. A Windows SDK-tól azonban nincs szigorú függőség, mivel a projekt (az cppwinrt.exe eszköz segítségével) ugyanazokat a fejléceket hozza létre a projekt $(GeneratedFilesDir) mappájába. Ha máshol nem találhatók, vagy ha módosítja a projekt beállításait, akkor a rendszer betölti őket az adott mappából.

A fejlécek a C++/WinRT-re leképezett Windows API-kat tartalmazzák. Más szóval minden Windows típushoz a C++/WinRT egy C++-felhasználóbarát megfelelőt (az úgynevezett előrejelzett típust) határoz meg. Az előrejelzett típusnak ugyanaz a teljes neve, mint a Windows típusnak, de a C++ winrt névtérben van elhelyezve. Ha ezeket az elemeket az előre összeállított fejlécbe helyezi, azzal csökkenti a növekményes buildelési időt.

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

Az using namespace irányelvek nem kötelezőek, de kényelmesek. Az ilyen irányelvek fent látható mintája (amely lehetővé teszi a winrt névtérben lévő adatok nem minősített névkeresését) alkalmas új projekt megkezdésekor, és a C++/WinRT az egyetlen nyelvi előrejelzés, amelyet a projekten belül használ. Ha viszont a C++/WinRT-kódot C++/CX-szel és/vagy SDK-alkalmazásbináris felületi (ABI) kóddal vegyíti (vagyis ezen modellek egyikéből vagy mindkettőből telepít át, illetve ezek egyikével vagy mindkettőjével valósít meg együttműködést), akkor tekintse meg a következő témaköröket: Együttműködés a C++/WinRT és a C++/CX között, Áttérés a C++/CX-ről a C++/WinRT-re és Együttműködés a C++/WinRT és az ABI között.

winrt::init_apartment();

A winrt::init_apartment meghívása inicializálja a szálat a Windows-futtatókörnyezet környezetben; alapértelmezés szerint egy többszálú apartmanban. A hívás a COM-t is inicializálja.

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

Stack-allocate két objektum: ezek a Windows blog uri-ját és egy szindikációs ügyfelet jelölik. Az URI-t egy egyszerű széles karakterlánc-literállal hozzuk létre (a karakterláncok kezelésének további módjaiért lásd: Karakterláncok kezelése a C++/WinRT-ben).

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

SyndicationClient::RetrieveFeedAsync egy aszinkron Windows-futtatókörnyezet függvény példája. A példakód egy aszinkron műveleti objektumot kap a RetrieveFeedAsync metódustól, és meghívja az objektumon a get metódust, hogy blokkolja a hívó szálat, és megvárja az eredményt (ami ebben az esetben egy szindikációs csatorna). Az egyidejűségről és a nem blokkoló technikákról további információt a C++/WinRT egyidejűségi és aszinkron műveleteiben talál.

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

A SyndicationFeed.Items egy tartomány, amelyet a kezdő és záró függvényekből visszaadott iterátorok (vagy azok állandó, fordított és konstans-fordított változatai) határoznak meg. Emiatt tartományalapú utasítással vagy for sablonfüggvénnyel is számba vehet elemeket. Amikor egy ilyen Windows-futtatókörnyezet-gyűjteményen végigiterál, erre lesz szüksége: #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;

Lekéri a hírcsatorna címét winrt::hstring objektum formájában (további részletek: Sztringkezelés a C++/WinRT-ben). A hstring ezután a c_str függvényen keresztül jön ki, amely a C++ standard kódtár sztringjeihez használt mintát tükrözi.

Amint látható, a C++/WinRT a modern, osztályszerű C++-kifejezések, például a syndicationItem.Title().Text(), használatát ösztönzi. Ez a hagyományos COM-programozástól eltérő, és tisztább programozási stílus. Nem kell közvetlenül inicializálnia a COM-t, és nem kell a COM-mutatókkal dolgoznia.

A HRESULT visszatérési kódjait sem kell kezelnie. A C++/WinRT a HRESULT-hibákat olyan kivételekké alakítja, mint a winrt::hresult-error egy természetes és modern programozási stílus esetében. A hibakezelésről és a kódpéldákról további információt a C++/WinRT hibakezelése című témakörben talál.

Windows asztali alkalmazásprojekt módosítása C++/WinRT-támogatás hozzáadásához

Egyes asztali projektek (például a WinUI 3-sablonok Visual Studio) beépített C++/WinRT-támogatással rendelkeznek.

Ez a szakasz viszont bemutatja, hogyan adhat C++/WinRT-támogatást bármely Windows asztali alkalmazásprojektjéhez, amellyel éppen dolgozik. Ha nem rendelkezik meglévő Windows asztali alkalmazásprojekttel, akkor ezeket a lépéseket követve először létrehozhat egyet. Nyissa meg például Visual Studio, és hozzon létre egy Visual C++>Windows Desktop>Windows Asztali alkalmazás projektet.

Igény szerint telepítheti a C++/WinRT Visual Studio bővítményt (VSIX) és a NuGet-csomagot. További információ: Visual Studio C++/WinRT támogatása.

Projekttulajdonságok beállítása

Lépjen az Általános>Windows SDK-verzió projekttulajdonságra, és válassza az Összes konfiguráció és minden platform lehetőséget. Győződjön meg arról, hogy Windows SDK-verzió értéke 10.0.17134.0 (Windows 10, 1803-es verzió) vagy újabb.

Győződjön meg arról, hogy Önre nem vonatkozik a Miért nem fordul le az új projektem?.”

Mivel a C++/WinRT a C++17 szabvány funkcióit használja, állítsa a C/C++>Language>C++ Language Standard projekttulajdonságot ISO C++17 Standard (/std:c++17) értékre.

Az előre összeállított fejléc

Az alapértelmezett projektsablon létrehoz egy előre lefordított fejlécet, amelynek neve framework.h vagy stdafx.h. Nevezze át erre: pch.h. Ha van egy stdafx.cpp fájlja, nevezze át erre: pch.cpp. Állítsa a projekt tulajdonságát C/C++>Előre lefordított fejlécek>Előre lefordított fejléc értékét Létrehozás (/Yc) értékre, és az Előre lefordított fejlécfájl értékét pch.h értékre.

Keresse meg, és cserélje le az összes #include "framework.h" (vagy #include "stdafx.h") elemet erre: #include "pch.h".

A(z) pch.h elemben adja meg ezt: winrt/base.h.

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

Linking

A C++/WinRT nyelvi kivetítés bizonyos Windows-futtatókörnyezet ingyenes (nem tag) függvénytől és belépési pontoktól függ, amelyek a WindowsApp.lib esernyőtárhoz való csatolást igénylik. Ez a szakasz három módszert ismertet arra, hogyan lehet megfelelni a linker követelményeinek.

Az első lehetőség az, hogy hozzáadja Visual Studio projektjéhez az összes C++/WinRT MSBuild tulajdonságot és célt. Ehhez telepítse a Microsoft.Windows. CppWinRT NuGet-csomag a projektbe. Nyissa meg a projektet a Visual Studióban, kattintson a Project>Manage NuGet Packages...>Tallózás elemre, írja be vagy illessze be a Microsoft.Windows.CppWinRT szöveget a keresőmezőbe, jelölje ki az elemet a keresési eredmények között, majd kattintson a Telepítés gombra a csomag projekthez való telepítéséhez.

A projekthivatkozás beállításaival explicit módon is csatolhatja a hivatkozást WindowsApp.lib. Vagy a forráskódban is megteheti (például a pch.h esetében), így.

#pragma comment(lib, "windowsapp")

Most már lefordíthatja és csatolhatja, és hozzáadhat C++/WinRT-kódot a projekthez (például a fenti A C++/WinRT gyorsindítási szakaszban láthatóhoz hasonló kódot).

A C++/WinRT három fő forgatókönyve

A C++/WinRT használata és megismerése, valamint a dokumentáció további részeinek megismerése során valószínűleg észre fogja venni, hogy három fő forgatókönyv létezik, az alábbi szakaszokban leírtak szerint.

Windows API-k és -típusok használata

Más szóval api-k használata vagy meghívása . Például API-hívások indítása a Bluetooth használatával való kommunikációhoz; videó streamelése és bemutatása; integrálható a Windows felülettel; és így tovább. A C++/WinRT teljes mértékben és kompromisszumok nélkül támogatja ezt a forgatókönyvkategóriát. További információ: API-k felhasználása C++/WinRT használatával.

Windows API-k és -típusok készítése

Más szóval api-k és típusok előállítása . Például a fenti szakaszban leírt API-k előállítása; vagy a grafikus API-k; a tárolási és fájlrendszer API-k; a hálózati API-k és így tovább. További információ: Szerzői API-k C++/WinRT használatával.

Az API-k C++/WinRT használatával történő létrehozása kicsit nagyobb szerepet játszik a használatuknál, mivel a implementálás előtt az IDL használatával kell meghatároznia az API alakját. Erről itt található egy útmutató: XAML-vezérlők; kötés C++/WinRT-tulajdonsághoz.

XAML-alkalmazások

Ez a forgatókönyv az XAML felhasználói felületi keretrendszer alkalmazásainak és vezérlőinek kiépítéséről szól. Az XAML-alkalmazásokban végzett munka a használat és a létrehozás kombinációját tartalmazza. Mivel azonban az XAML ma a domináns felhasználói felületi keretrendszer Windows, és a Windows-futtatókörnyezet gyakorolt hatása ezzel arányos, megérdemli a saját forgatókönyv kategóriáját.

Vegye figyelembe, hogy az XAML akkor működik a legjobban, ha a programozási nyelv támogatja a reflexiót. A C++/WinRT-ben néha egy kis plusz munkát kell elvégeznie az XAML-keretrendszerrel való együttműködéshez. Az összes ilyen esetet a dokumentáció ismerteti. Jó kiindulópont az XAML-vezérlők; a C++/WinRT tulajdonsághoz való kötés és az XAML egyéni (sablonos) vezérlők a C++/WinRT használatával.

C++/WinRT-ben írt mintaalkalmazások

Lásd : Hol találom a C++/WinRT mintaalkalmazásokat?.

Fontos API-k

• SyndicationClient::RetrieveFeedAsync metódus
• SyndicationFeed.Items tulajdonság
• winrt::hstring struct
• winrt::hresult-error struct

Kapcsolódó témakörök

• C++/CX
• Hibakezelés a C++/WinRT használatával
• Együttműködés a C++/WinRT és a C++/CX között
• Együttműködés a C++/WinRT és az ABI között
• Ugrás a C++/WinRT fájlra a C++/CX fájlból
• Sztringkezelés a C++/WinRT-ben