Kom igång med C++/WinRT

För att få dig att komma igång med att använda C++/WinRT går det här avsnittet igenom ett enkelt kodexempel baserat på ett nytt Projekt för Windows-konsolprogram (C++/WinRT). Det här avsnittet visar också hur du lägger till C++/WinRT-stöd i ett Windows Desktop-programprojekt.

Snabbstart för C++/WinRT

Skapa ett nytt Projekt för Windows-konsolprogram (C++/WinRT).

Redigera pch.h och main.cpp för att se ut så här.

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

Vi tar det korta kodexemplet ovan bit för bit och förklarar vad som händer i varje del.

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

Med standardinställningarna för projekt kommer de inkluderade rubrikerna från Windows SDK i mappen %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. Visual Studio innehåller den sökvägen i sitt IncludePath-makro . Men det finns inget strikt beroende av Windows SDK eftersom projektet (via cppwinrt.exe verktyget) genererar samma huvuden i projektets $ (GeneratedFilesDir) -mapp. De läses in från mappen om de inte kan hittas någon annanstans eller om du ändrar dina projektinställningar.

Rubrikerna innehåller Windows-API:er som projiceras till C++/WinRT. Med andra ord definierar C++/WinRT för varje Windows-typ en C++-vänlig motsvarighet (kallas för den projicerade typen). En projekterad typ har samma fullständigt kvalificerade namn som Windows-typen, men den placeras i namnområdet C++ winrt . Genom att placera dessa filer i din förkompilerade huvudfil minskas inkrementella byggtider.

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

Dessa using namespace-direktiv är valfria, men praktiska. Mönstret som visas ovan för sådana direktiv (som tillåter okvalificerad namnsökning efter något i winrt-namnområdet ) är lämpligt när du påbörjar ett nytt projekt och C++/WinRT är den enda språkprojektion som du använder i projektet. Om du å andra sidan blandar C++/WinRT-kod med C++/CX - och/eller SDK-kod för binärt gränssnitt (ABI) (du antingen porterar från, eller samverkar med, en eller båda av dessa modeller), se sedan ämnena Interop mellan C++/WinRT och C++/CX, Flytta till C++/WinRT från C++/CX och Interop mellan C++/WinRT och ABI.

winrt::init_apartment();

Anropet till winrt::init_apartment initierar tråden i Windows Runtime. som standard i en flertrådad lägenhet. Anropet initierar också COM.

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

Stackallokera två objekt: de representerar URI för Windows-bloggen och en syndikeringsklient. Vi skapar URI:n med en enkel strängliteral (se Stränghantering i C++/WinRT för fler sätt att arbeta med strängar).

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

SyndicationClient::RetrieveFeedAsync är ett exempel på en asynkron Windows Runtime-funktion. Kodexemplet tar emot ett asynkront operationsobjekt från RetrieveFeedAsyncoch anropar get på det objektet för att blockera den anropande tråden och vänta på resultatet (vilket i det här fallet är ett syndikationsflöde). Mer information om samtidighet och icke-blockerande tekniker finns i Samtidighet och asynkrona åtgärder med C++/WinRT.

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

SyndicationFeed.Items är ett intervall som definieras av iteratorerna som returneras från begin och end funktionerna (eller deras konstanta, omvända och konstanta omvända varianter). Därför kan du räkna upp objekt med antingen en intervallbaserad for instruktion eller med mallfunktionen std::for_each . När du itererar genom en Windows Runtime-samling som denna måste du #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;

Hämtar feedens rubriktext som ett winrt::hstring-objekt (mer information i Stränghantering i C++/WinRT). Den hstring skrivs sedan ut via funktionen c_str, vilket återspeglar det mönster som används med strängar i C++ Standardbiblioteket.

Som du ser uppmuntrar C++/WinRT moderna och klassliknande C++-uttryck som syndicationItem.Title().Text(). Det här är en annan och renare programmeringsstil än traditionell COM-programmering. Du behöver inte initiera COM direkt eller arbeta med COM-pekare.

Du behöver inte heller hantera HRESULT-returkoder. C++/WinRT konverterar HRESULT-fel till undantag som winrt::hresult-error för en naturlig och modern programmeringsstil. Mer information om felhantering och kodexempel finns i Felhantering med C++/WinRT.

Ändra ett Windows Desktop-programprojekt för att lägga till stöd för C++/WinRT

Vissa skrivbordsprojekt (till exempel WinUI 3-mallarna i Visual Studio) har inbyggd C++/WinRT-support.

Men det här avsnittet visar hur du kan lägga till C++/WinRT-stöd till alla Windows Desktop-programprojekt som du kan ha. Om du inte har ett befintligt Windows Desktop-programprojekt kan du följa dessa steg genom att först skapa ett. Öppna till exempel Visual Studio och skapa ett Visual C++>Windows Desktop>.

Du kan också installera C++/WinRT Visual Studio-tillägget (VSIX) och NuGet-paketet. Mer information finns i Visual Studio-stöd för C++/WinRT.

Ange projektegenskaper

Gå till projektegenskapen Allmän>Windows SDK-version och välj Alla konfigurationer och Alla plattformar. Kontrollera att Windows SDK-versionen är inställd på 10.0.17134.0 (Windows 10, version 1803) eller senare.

Bekräfta att du inte påverkas av Varför kompileras inte mitt nya projekt?.

Eftersom C++/WinRT använder funktioner från C++17-standarden anger du projektegenskapen C/C++>Language>C++ Language Standard till ISO C++17 Standard (/std:c++17).

Den förkompilerade rubriken

Standardprojektmallen skapar en fördefinierad rubrik åt dig med namnet antingen framework.h, eller stdafx.h. Byt namn på det till pch.h. Om du har en stdafx.cpp fil byter du namn på den till pch.cpp. Ange projektegenskapen C/C++>Förkompilerade sidhuvuden>förkompilerat huvud till Skapa (/Yc) och Förkompilerad rubrikfil till pch.h.

Hitta och ersätt alla #include "framework.h" (eller #include "stdafx.h") med #include "pch.h".

I pch.h, inkludera winrt/base.h.

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

Länkning

C++/WinRT-språkprojektionen beror på vissa fristående Windows Runtime-funktioner (icke-medlemsfunktioner) och startpunkter som kräver länkning till WindowsApp.lib- paraplybibliotek. I det här avsnittet beskrivs tre sätt att uppfylla länkkraven.

Det första alternativet är att lägga till alla egenskaper och mål för C++/WinRT MSBuild i Visual Studio-projektet. Det gör du genom att installera NuGet-paketet Microsoft.Windows.CppWinRT i projektet. Öppna projektet i Visual Studio, klicka på Project>Manage NuGet Packages...>Browse, type or paste Microsoft.Windows.CppWinRT i sökrutan, välj objektet i sökresultatet och klicka sedan på Installera för att installera paketet för projektet.

Du kan också använda projektlänkinställningar för att explicit länka WindowsApp.lib. Eller så kan du göra det i källkoden (i pch.h, till exempel) så här.

#pragma comment(lib, "windowsapp")

Nu kan du kompilera och länka och lägga till C++/WinRT-kod i projektet (till exempel kod som liknar den som visas i snabbstartsavsnittet A C++/WinRT ovan).

De tre huvudscenarierna för C++/WinRT

När du använder och bekantar dig med C++/WinRT och går igenom resten av dokumentationen här kommer du förmodligen att märka att det finns tre huvudscenarier, enligt beskrivningen i följande avsnitt.

Använda Windows-API:er och -typer

Med andra ord använda, eller anropa API:er. Till exempel att göra API-anrop för att kommunicera med Bluetooth; att strömma och presentera video; för att integrera med Windows-gränssnittet; och så vidare. C++/WinRT stöder fullständigt och kompromisslöst den här scenariokategorin. För mer information, se Använd API:er med C++/WinRT.

Redigera Windows-API:er och -typer

Med andra ord som producerar APIer och typer. Du kan till exempel skapa de typer av API:er som beskrivs i avsnittet ovan. eller grafik-API:erna; API:er för lagrings- och filsystem. nätverks-API:er och så vidare. För mer information, se Author APIs med C++/WinRT.

Redigering av API:er med C++/WinRT är lite mer involverat än att använda dem, eftersom du måste använda IDL för att definiera formen på API:et innan du kan implementera det. Det finns en genomgång av att göra det i XAML-kontroller; binda till en C++/WinRT-egenskap.

XAML-applikationer

Det här scenariot handlar om att skapa program och kontroller i XAML UI-ramverket. Att arbeta i ett XAML-program är en kombination av användning och redigering. Men eftersom XAML är det dominerande användargränssnittsramverket i Windows idag, och dess inflytande över Windows Runtime står i proportion till det, förtjänar det en egen kategori av scenario.

Tänk på att XAML fungerar bäst med programmeringsspråk som ger reflektion. I C++/WinRT måste du ibland göra lite extra arbete för att samverka med XAML-ramverket. Alla dessa fall beskrivs i dokumentationen. Bra ställen att börja på är XAML-kontroller, att binda till en C++/WinRT-egenskap och anpassade XAML-kontroller med mall med C++/WinRT.

Exempelappar skrivna i C++/WinRT

Se Var hittar jag C++/WinRT-exempelappar?.

Viktiga API:er

• SyndicationClient::RetrieveFeedAsync-metoden
• SyndicationFeed.Items-egenskapen
• winrt::hstring struct
• winrt::hresult-error struct

Relaterade ämnen

• C++/CX
• Felhantering med C++/WinRT
• Interop mellan C++/WinRT och C++/CX
• Interop mellan C++/WinRT och ABI
• Flytta till C++/WinRT från C++/CX
• Stränghantering i C++/WinRT