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 Windows konsolprogramprojekt (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 Windows konsolprogramprojekt (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 typ, men den placeras i namnområdet C++ winrt. Att lägga dessa include-direktiv i din förkompilerade header-fil minskar tiderna för inkrementella byggen.

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

Direktiven using namespace ä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:n 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 åtgärdsobjekt från RetrieveFeedAsync och anropar get på objektet för att blockera den anropande tråden och vänta på resultatet (vilket är en syndikeringsfeed i det här fallet). 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 funktionerna begin och end (eller deras konstanta, omvända och konstant 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 över en Windows Runtime-samling av den här typen 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). Hstring matas sedan ut via funktionen c_str, vilket återspeglar det mönster som används med C++ Standard Library-strängar.

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>Windows Desktop Application-projekt.

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

Ange projektegenskaper

Gå till projektegenskapen Allmänt>Windows SDK-version och välj Alla konfigurationer och Alla plattformar. Kontrollera att Windows SDK-version ä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 inkluderar du winrt/base.h.

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

Länkning

Språkprojekteringen för C++/WinRT är beroende av vissa fria Windows Runtime-funktioner (fristående funktioner) och ingångspunkter som kräver länkning till paraplybiblioteket WindowsApp.lib. I det här avsnittet beskrivs tre sätt att uppfylla länkarens krav.

Det första alternativet är att lägga till alla egenskaper och mål för C++/WinRT MSBuild i ditt Visual Studio projekt. Det gör du genom att installera Microsoft.Windows. CppWinRT NuGet-paketet i projektet. Öppna project i Visual Studio, klicka på Project>Hantera NuGet-paket...>Bläddra, skriv eller klistra in Microsoft.Windows. CppWinRT i sökrutan, välj objektet i sökresultaten och klicka sedan på Installera för att installera paketet för den project.

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.

Anropa Windows-API:er och typer

Med andra ord använder eller anropar 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. Mer information finns i Använda API:er med C++/WinRT.

Redigera Windows API:er och typer

Med andra ord, producera API:er 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. Mer information finns i Skapa API:er 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-program

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 på Windows idag, och dess inflytande över Windows Runtime står i proportion till det, förtjänar det sin 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. Bind till en C++/WinRT-egenskap och anpassade XAML-kontroller (mallade) med C++/WinRT.

Exempelappar skrivna i C++/WinRT

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

Viktiga API:er

• Metoden SyndicationClient::RetrieveFeedAsync
• SyndicationFeed.Items-egenskap
• 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