Introduktion till C++/WinRT

 

 

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. Det introducerades i version 10.0.17134.0 (Windows 10 version 1803).

C++/WinRT är Microsoft rekommenderade ersättning för C++/CX-språkprojektionen och Windows Runtime C++-mallbiblioteket (WRL). Den fullständiga listan med ä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 i 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 är utformade 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å kombinationsrutan Språk uppe till höger och väljer C++/WinRT för att visa API-syntaxblock som de visas i språkprojektionen C++/WinRT.

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

För Visual Studio support behöver du Visual Studio 2022 eller Visual Studio 2019 eller Visual Studio 2017 (minst version 15.6; vi rekommenderar minst 15.7). Installera arbetsbelastningen utveckling för Universell Windows-plattform i Visual Studio Installer. I Installationsdetaljer>Universell Windows-plattform-utveckling markerar du alternativet C++ (v14x) Universell Windows-plattform-verktyg 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 Sidläs appar).

Vi rekommenderar att du utvecklar med de senaste versionerna av Visual Studio och Windows SDK, men om du använder en version av C++/WinRT som levererades med Windows SDK före 10.0.17763.0 (Windows 10, version 1809) behöver du sedan använda Windows namnområden som nämns ovan Windows SDK-målversion i projektet 10.0.17134.0 (Windows 10 version 1803).

Visual Studio 2022 levereras med inbyggda C++/WinRT-projekt- och objektmallar så att du kan komma igång med C++/WinRT-utveckling direkt. Den levereras också med Visual Studio intern felsökningsvisualisering (natvis) av C++/WinRT-beräknade typer. Det ger en upplevelse som liknar C#-felsökning. Natvis är automatiskt för felsökningsversioner. Mer information finns i Visual Studio intern felsökningsvisualisering för C++/WinRT.

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

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

De 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-paket. Microsoft.Windows. CppWinRT NuGet-paketet 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).

Alternativt kan du konvertera ett befintligt projekt genom att manuellt installera NuGet-paketet Microsoft.Windows.CppWinRT. När du har installerat (eller uppdaterat till) den senaste versionen av VSIX-tillägget öppnar du den befintliga project i Visual Studio och klickar 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. När du har lagt till paketet får du stöd för C++/WinRT MSBuild för projektet, inklusive att cppwinrt.exe anropa verktyget.

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 kompilatoralternativet /bigobj .
  • Det lägger till kompilatoralternativet /await 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 cppwinrt.exe verktyget 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 Microsoft.Windows. CppWinRT NuGet-paketet innehåller verktygetcppwinrt.exe. Du kan låta verktyget cppwinrt.exe peka på en Windows Runtime-metadatafil (.winmd) för att generera ett headerfilsbaserat C++-standardbibliotek som exponerar de API:er som beskrivs i metadatafilen för användning från C++/WinRT-kod. Windows Runtime metadatafiler (.winmd) ger ett kanoniskt sätt att beskriva en Windows Runtime API-yta. Genom att peka cppwinrt.exe mot metadata kan du generera ett bibliotek som kan användas med valfri runtimeklass som implementeras i en Windows Runtime-komponent från en annan part eller tredje part, eller i din egen applikation. Mer information finns i Använda 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 COM-programmering. För en runtimeklass beskriver du helt enkelt dina typer i en IDL-fil, och midl.exe och cppwinrt.exe genererar standardkällkodsfilerna för implementeringen åt dig. Du kan också bara implementera gränssnitt genom att härleda från en C++/WinRT-basklass. Mer information finns i Skapa API:er med C++/WinRT.

I filen readme för NuGet-paketet Microsoft.Windows.CppWinRT finns en lista över anpassningsalternativ för verktyget cppwinrt.exe, som ställs in via projektegenskaper.

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 de Visual Studio projektmallar som tillhandahålls av VSIX-tillägget.

Standardapp (C++/WinRT)

En projektmall för en Universal Windows Platform (UWP) app som har ett XAML-användargränssnitt. För WinUI 3-skrivbordsappar använder du mallen Tom app, Paketerad (WinUI 3 i Desktop) i stället.

Visual Studio tillhandahåller XAML-kompilatorstöd 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 körningsklasser. Se Att dela upp 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 – mer information finns i Hantera händelser med hjälp av ombud i C++/WinRT .

Core App (C++/WinRT)

En projektmall för en Universal Windows Platform (UWP) app som inte använder XAML. Det finns ingen WinUI 3-motsvarighet till den här mallen.

I stället används namnområdeshuvudfilen för C++/WinRT Windows för namnrymden Windows.ApplicationModel.Core. När du har byggt och kört klickar du på ett tomt område för att lägga till en färgad fyrkant; klicka sedan på en färgad fyrkant för att dra runt den.

Windows-konsolprogram (C++/WinRT)

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

Windows Desktop-applikation (C++/WinRT)

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

Windows Runtime-komponent (C++/WinRT)

En projektmall för en komponent. vanligtvis för förbrukning från en Universal Windows Platform (UWP).

Den här mallen midl.exe>cppwinrt.exe visar 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 Bryta ut körningsklasser till MIDL-filer (.idl).

Paketera binärfilen för den kompilerade Windows Runtime-komponenten och dess .winmd 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 och Visual Studio konfiguration, gäller informationen i Visual Studio stöd för C++/WinRT, XAML, VSIX-tillägget och NuGet-paketavsnittet 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. Projektet har egenskapen <CppWinRTEnabled>true</CppWinRTEnabled> angiven 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 project i Visual Studio och klickar 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 din project.

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 från 1.0.181002.2 till och med 1.0.190128.3 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 ditt uppgraderade projekt – eftersom byggstöd fortfarande fanns kvar i versioner av VSIX-tillägget inom det här intervallet – ha Microsoft.Windows.CppWinRT-NuGet-paketet installerat eller inte.

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 <CppWinRTEnabled>true</CppWinRTEnabled> egenskapen 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 Microsoft.Windows. CppWinRT Nuget-paket."

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

Eftersom elementet <CppWinRTEnabled> nu är föråldrat kan du om du vill redigera ditt .vcxproj och 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 VSIX-tillägget C++/WinRT installeras.

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

Även om det nu endast finns kvar av kompatibilitetsskäl innehåller Windows SDK, sedan version 10.0.17134.0 (Windows 10, version 1803), ett huvudfilsbaserat C++-standardbibliotek för att använda Windows egna API:er (Windows Runtime-API:er i Windows-namnrymder). 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 med cppwinrt.exe verktyget. 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-paket. Paketet och cppwinrt.exe, beskrivs i avsnitten ovan.

Anpassade typer i C++/WinRT-projektionen

I C++/WinRT-programmeringen kan du använda standardfunktioner för C++-språk och Standard C++-datatyper 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 det är mindre troligt att du direkt använder en typ 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ådesrubriker. Ett exempel är winrt::p aram::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 namnområdet, 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ådet.

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

Viktiga API:er

  • Last updated on