Introduktion till C++/WinRT

2025-06-10

C++/WinRT är en helt standardmodern C++17-språkprojektion för Windows Runtime-API:er (WinRT), implementerat som ett huvudfilbaserat bibliotek och utformat för att ge dig förstklassig åtkomst till det moderna Windows-API:et. Med C++/WinRT kan du skapa och använda Windows Runtime-API:er med valfri standardkompatibel C++17-kompilator. Windows SDK innehåller C++/WinRT; den introducerades i version 10.0.17134.0 (Windows 10, version 1803).

C++/WinRT är Microsofts rekommenderade ersättning för språkprojektionen C++/CX och Windows Runtime C++ Template Library (WRL). Den fullständiga listan över ämnen om C++/WinRT innehåller information om både samverkan med och portning från C++/CX och WRL.

Viktigt!

Några av de viktigaste delarna av C++/WinRT som du bör känna till beskrivs i avsnitten SDK-stöd för C++/WinRT- och Visual Studio-stöd för C++/WinRT, XAML, VSIX-tillägget och NuGet-paketet.

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

Språkprojektioner

Windows Runtime baseras på API:er för komponentobjektmodell (COM) och har utformats för att nås via språkprojektioner. En projektion döljer COM-informationen och ger en mer naturlig programmeringsupplevelse för ett visst språk.

Språkprojektionen C++/WinRT i referensinnehållet för Windows Runtime API

När du bläddrar Windows Runtime API:er, klickar du på kombinationsboxen Language i det övre högra hörnet och väljer C++/WinRT för att visa API-syntaxblock som de ser ut i C++/WinRT-språkprojektionen.

Visual Studio-stöd för C++/WinRT, XAML, VSIX-tillägget och NuGet-paketet

För Visual Studio-stöd behöver du Visual Studio 2022, Visual Studio 2019 eller Visual Studio 2017 (minst version 15.6; vi rekommenderar minst 15,7). Från Visual Studio Installer installerar du arbetsbelastningen Universal Windows Platform-utveckling. I Installationsinformation>Utveckling av Universell Windows-plattformkontrollerar du C++ (v14x) Universal Windows Platform-verktyg alternativ om du inte redan har gjort det. Och i Windows-inställningar>Sekretess och säkerhet (Windows 10: Uppdatering och säkerhet) >För utvecklare aktiverar du alternativet Utvecklarläge (Windows 10: inte alternativet För separat inläsning av appar ).

Vi rekommenderar att du utvecklar med de senaste versionerna av Visual Studio och Windows SDK. Om du använder en version av C++/WinRT som levererades med Windows SDK före version 10.0.17763.0 (Windows 10, version 1809), måste du ange en minsta målversion för Windows SDK i projektet, vilken ska vara 10.0.17134.0 (Windows 10, version 1803), för att kunna använda de ovan nämnda Windows-namespace-huvudfilerna.

Visual Studio 2022 levereras med C++/WinRT-projekt och objektmallar som är inbyggda, så att du kan komma igång med C++/WinRT-utveckling direkt. Den levereras också med Visual Studios inbyggda felsökningsvisualisering (natvis) av C++/WinRT-projekterade typer, och ger en upplevelse som liknar C#-felsökning. Natvis är automatiskt för felsökningsversioner. För mer information, se inbyggd felsökningsvisualisering i Visual Studio för C++/WinRT.

För äldre versioner av Visual Studio vill du ladda ned och installera den senaste versionen av C++/WinRT Visual Studio Extension (VSIX) från Visual Studio Marketplace.

VSIX-tillägget ger dig C++/WinRT-projekt- och objektmallar i Visual Studio.
Dessutom ger det dig Visual Studio inbyggd felsökningsvisualisering (natvis) av C++/WinRT-projicerade typer.

Visual Studio-projektmallarna för C++/WinRT beskrivs i avsnitten nedan. När du skapar ett nytt C++/WinRT-projekt med den senaste versionen av VSIX-tillägget installerat installerar det nya C++/WinRT-projektet automatiskt Microsoft.Windows.CppWinRT NuGet-paketet. NuGet-paketet Microsoft.Windows.CppWinRT tillhandahåller C++/WinRT-byggstöd (MSBuild-egenskaper och mål), vilket gör projektet portabelt mellan en utvecklingsdator och en byggagent (där endast NuGet-paketet och inte VSIX-tillägget är installerat).

Du kan också konvertera ett befintligt projekt genom att installera Microsoft.Windows.CppWinRT- NuGet-paketet manuellt. När du har installerat (eller uppdaterat till) den senaste versionen av VSIX-tillägget öppnar du det befintliga projektet i Visual Studio, klickar på Project>Manage NuGet Packages...>Browse, type or paste Microsoft.Windows.CppWinRT i sökrutan, väljer objektet i sökresultaten och klickar sedan på Installera för att installera paketet för projektet. När du har lagt till paketet får du stöd för C++/WinRT MSBuild för projektet, inklusive att anropa verktyget cppwinrt.exe.

Viktigt!

Om du har projekt som har skapats med (eller uppgraderats för att fungera med) en version av VSIX-tillägget tidigare än 1.0.190128.4 kan du läsa Tidigare versioner av VSIX-tillägget. Det avsnittet innehåller viktig information om konfigurationen av dina projekt, som du behöver veta för att uppgradera dem för att använda den senaste versionen av VSIX-tillägget.

Eftersom C++/WinRT använder funktioner från C++17-standarden anger NuGet-paketet projektegenskapen C/C++>Language>C++ Language Standard>ISO C++17 Standard (/std:c++17) i Visual Studio.
Den lägger också till /bigobj kompilatoralternativ.
Det lägger till /await-kompilatoralternativet för att aktivera co_await.
Den instruerar XAML-kompilatorn att generera C++/WinRT-kodgen.
Du kanske också vill ange Efterlevnadsläge: Ja (/tillåtande-), vilket ytterligare begränsar koden till att vara standardkompatibel.
En annan projektegenskap att känna till är C/C++>Allmänt>Behandla varningar som fel. Ställ in på Ja(/WX) eller Nej (/WX-) efter smak. Ibland genererar källfiler som genereras av verktyget cppwinrt.exe varningar tills du lägger till implementeringen i dem.

Med systemet konfigurerat enligt beskrivningen ovan kan du skapa och skapa, eller öppna, ett C++/WinRT-projekt i Visual Studio och distribuera det.

Från och med version 2.0 innehåller Microsoft.Windows.CppWinRT- NuGet-paketet cppwinrt.exe-verktyget. Du kan peka cppwinrt.exe-verktyget på en Windows Runtime-metadatafil (.winmd) för att generera ett huvudfilbaserat C++-standardbibliotek som projekt API:erna som beskrivs i metadata för förbrukning från C++/WinRT-kod. Windows Runtime-metadata (.winmd) -filer ger ett kanoniskt sätt att beskriva en Windows Runtime API-yta. Genom att peka cppwinrt.exe på metadata kan du generera ett bibliotek för användning med valfri körningsklass som implementeras i en Windows Runtime-komponent från andra eller tredje part eller implementeras i ditt eget program. För mer information, se Använd API:er med C++/WinRT.

Med C++/WinRT kan du även implementera dina egna körningsklasser med hjälp av standard C++, utan att använda PROGRAMMERING i COM-stil. För en körningsklass beskriver du bara dina typer i en IDL-fil, och midl.exe och cppwinrt.exe genererar standardimplementeringskällkodsfiler åt dig. Du kan också bara implementera gränssnitt genom att härleda från en C++/WinRT-basklass. För mer information, se Author APIs med C++/WinRT.

En lista över anpassningsalternativ för verktyget , som ställs in via projektets egenskaper, finns i readmei Microsoft.Windows.CppWinRT NuGet-paketet .

Du kan identifiera ett projekt som använder stöd för C++/WinRT MSBuild genom att det finns Microsoft.Windows.CppWinRT- NuGet-paketet installerat i projektet.

Här är Visual Studio-projektmallarna som tillhandahålls av VSIX-tillägget.

Standardapplikation (C++/WinRT)

En projektmall för en UWP-app (Universal Windows Platform) som har ett XAML-användargränssnitt.

Visual Studio har stöd för XAML-kompilatorn för att generera implementering och rubrikstubbar från IDL-filen (Interface Definition Language) (.idl) som finns bakom varje XAML-markeringsfil. I en IDL-fil definierar du alla lokala körningsklasser som du vill referera till på appens XAML-sidor och skapar sedan projektet en gång för att generera implementeringsmallar i Generated Filesoch stub-typdefinitioner i Generated Files\sources. Använd sedan dessa stub-typdefinitioner som referens för att implementera dina lokala runtime-klasser. Se faktorisera körningsklasser i MIDL-filer (.idl).

Stöd för XAML-designytan i Visual Studio för C++/WinRT är nära paritet med C#. I Visual Studio kan du använda fliken Händelser i fönstret Egenskaper för att lägga till händelsehanterare i ett C++/WinRT-projekt. Du kan också lägga till händelsehanterare i koden manuellt– se Hantera händelser med hjälp av ombud i C++/WinRT- för mer information.

Core App (C++/WinRT)

En projektmall för en UWP-app (Universal Windows Platform) som inte använder XAML.

I stället används namnområdesrubriken C++/WinRT Windows för namnområdet Windows.ApplicationModel.Core. När du har byggt och kört, klicka på ett tomt utrymme för att lägga till en färgad fyrkant, och klicka sedan på en färgad fyrkant för att dra den.

Windows-konsolprogram (C++/WinRT)

En projektmall för ett C++/WinRT-klientprogram för Windows Desktop med ett användargränssnitt för konsolen.

Windows Desktop-applikation (C++/WinRT)

En projektmall för en C++/WinRT-klientapplikation för Windows Desktop, som visar en Windows Runtime Windows.Foundation.Uri inuti en Win32 MessageBox.

Windows Runtime-komponent (C++/WinRT)

En projektmall för en komponent. vanligtvis för förbrukning från en universell Windows-plattform (UWP).

Den här mallen visar den midl.exe>cppwinrt.exe verktygskedjan, där Windows Runtime-metadata (.winmd) genereras från IDL och sedan genereras implementering och rubrikstubbar från Windows Runtime-metadata.

I en IDL-fil definierar du körningsklasserna i komponenten, deras standardgränssnitt och andra gränssnitt som de implementerar. Skapa projektet en gång för att generera module.g.cpp, module.h.cpp, implementeringsmallar i Generated Filesoch stub-typdefinitioner i Generated Files\sources. Använd sedan dessa stub-typdefinitioner som referens för att implementera körningsklasserna i komponenten. Se faktorisera körningsklasser i MIDL-filer (.idl).

Sammanställ den byggda binärfilen av Windows Runtime-komponenten och dess .winmd tillsammans med UWP-appen som använder dem.

Tidigare versioner av VSIX-tillägget

Vi rekommenderar att du installerar (eller uppdaterar till) den senaste versionen av VSIX-tillägget. Den är konfigurerad för att uppdatera sig själv som standard. Om du gör det, och du har projekt som har skapats med en version av VSIX-tillägget tidigare än 1.0.190128.4, innehåller det här avsnittet viktig information om hur du uppgraderar projekten så att de fungerar med den nya versionen. Om du inte uppdaterar kommer informationen i det här avsnittet fortfarande att vara användbar.

När det gäller Windows SDK- och Visual Studio-versioner som stöds och Visual Studio-konfiguration gäller informationen i Visual Studio-stöd för C++/WinRT, XAML, VSIX-tillägget och NuGet-paketet ovan för tidigare versioner av VSIX-tillägget. Informationen nedan beskriver viktiga skillnader när det gäller beteendet och konfigurationen av projekt som skapats med (eller uppgraderats för att fungera med) tidigare versioner.

Skapades tidigare än 1.0.181002.2

Om projektet har skapats med en version av VSIX-tillägget tidigare än 1.0.181002.2, har C++/WinRT-byggstöd byggts in i den versionen av VSIX-tillägget. I projektet har egenskapen <CppWinRTEnabled>true</CppWinRTEnabled> angetts i filen .vcxproj.

<Project ...>
    <PropertyGroup Label="Globals">
        <CppWinRTEnabled>true</CppWinRTEnabled>
...

Du kan uppgradera projektet genom att installera Microsoft.Windows.CppWinRT- NuGet-paketet manuellt. När du har installerat (eller uppgraderat till) den senaste versionen av VSIX-tillägget öppnar du projektet i Visual Studio, klickar på Project>Manage NuGet Packages...>Browse, type or paste Microsoft.Windows.CppWinRT i sökrutan, väljer objektet i sökresultaten och klickar sedan på Installera för att installera paketet för projektet.

Skapades med (eller uppgraderades till) mellan 1.0.181002.2 och 1.0.190128.3

Om projektet skapades med en version av VSIX-tillägget mellan 1.0.181002.2 och 1.0.190128.3, inklusive, installerades Microsoft.Windows.CppWinRT- NuGet-paketet automatiskt i projektet av projektmallen. Du kan också ha uppgraderat ett äldre projekt för att använda en version av VSIX-tillägget i det här intervallet. Om du gjorde det kan det hända att ditt uppgraderade projekt kanske inte har Microsoft.Windows.CppWinRT- NuGet-paketet installerat, eftersom versionsstöd också fortfarande fanns i versioner av VSIX-tillägget i det här intervallet.

Om du vill uppgradera projektet följer du anvisningarna i föregående avsnitt och ser till att projektet har Microsoft.Windows.CppWinRT- NuGet-paketet installerat.

Ogiltiga uppgraderingskonfigurationer

Med den senaste versionen av VSIX-tillägget är det inte giltigt för ett projekt att ha egenskapen <CppWinRTEnabled>true</CppWinRTEnabled> om den inte också har Microsoft.Windows.CppWinRT- NuGet-paketet installerat. Ett projekt med den här konfigurationen skapar build-felmeddelandet "C++/WinRT VSIX tillhandahåller inte längre stöd för projektbygge. Lägg till en projektreferens till Nuget-paketet Microsoft.Windows.CppWinRT."

Som nämnts ovan måste nu ett C++/WinRT-projekt ha NuGet-paketet installerat i det.

Eftersom <CppWinRTEnabled>-elementet nu är föråldrat kan du redigera .vcxprojoch ta bort elementet. Det är inte absolut nödvändigt, men det är ett alternativ.

Om din .vcxproj innehåller <RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>kan du också ta bort den så att du kan skapa den utan att kräva att C++/WinRT VSIX-tillägget installeras.

SDK-stöd för C++/WinRT

Även om den nu endast finns av kompatibilitetsskäl, från och med version 10.0.17134.0 (Windows 10, version 1803), innehåller Windows SDK ett huvudfilbaserat C++-standardbibliotek för användning av windows-API:er från första part (Windows Runtime-API:er i Windows-namnområden). Dessa rubriker finns i mappen %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. Från och med Windows SDK version 10.0.17763.0 (Windows 10, version 1809) genereras dessa rubriker åt dig i projektets $(GeneratedFilesDir) mapp.

Återigen för kompatibilitet levereras Windows SDK också med verktyget cppwinrt.exe. Vi rekommenderar dock att du i stället installerar och använder den senaste versionen av cppwinrt.exe, som ingår i Microsoft.Windows.CppWinRT- NuGet-paketet. Paketet och cppwinrt.exebeskrivs i avsnitten ovan.

Anpassade typer i C++/WinRT-projektionen

I C++/WinRT-programmeringen kan du använda C++-standardspråkfunktioner och C++-standarddatatyper och C++/WinRT-– inklusive vissa C++-standardbiblioteksdatatyper. Men du kommer också att bli medveten om vissa anpassade datatyper i projektionen och du kan välja att använda dem. Vi använder till exempel winrt::hstring i snabbstartskodexemplet i Kom igång med C++/WinRT.

winrt::com_array är en annan typ som du förmodligen kommer att använda någon gång. Men du är mindre benägen att direkt använda en typ såsom winrt::array_view. Eller så kan du välja att inte använda den så att du inte har någon kod att ändra om och när en motsvarande typ visas i C++-standardbiblioteket.

Varning

Det finns också typer som du kan se om du noggrant studerar C++/WinRT Windows-namnområdesrubrikerna. Ett exempel är winrt::param::hstring, men det finns även samlingsexempel. Dessa finns enbart för att optimera bindningen av indataparametrar, och de ger stora prestandaförbättringar och gör att de flesta anropsmönster "bara fungerar" för relaterade C++-standardtyper och containrar. Dessa typer används endast av projektionen i de fall där de tillför mest värde. De är mycket optimerade och de är inte för allmän användning. var inte frestad att använda dem själv. Du bör inte heller använda något från winrt::impl namnrymd eftersom det är implementeringstyper och därför kan komma att ändras. Du bör fortsätta att använda standardtyper eller typer från winrt-namnområde.

Se även Skicka parametrar till ABI-gränsen.

Dela via