Inleiding tot C++/WinRT

C++/WinRT is een volledig standaard moderne C++17-taalprojectie voor Windows Runtime-API's (WinRT), geïmplementeerd als een bibliotheek op basis van header-bestanden en ontworpen om u toegang te bieden tot de moderne Windows-API. Met C++/WinRT kunt u Windows Runtime API's ontwerpen en gebruiken met behulp van een C++17-compiler die compatibel is met standaarden. De Windows SDK bevat C++/WinRT; deze is geïntroduceerd in versie 10.0.17134.0 (Windows 10 versie 1803).

C++/WinRT is Microsoft aanbevolen vervanging voor de C++/CX-taalprojectie en de Windows Runtime C++-sjabloonbibliotheek (WRL). De volledige lijst met onderwerpen over C++/WinRT bevat informatie over zowel samenwerken met als overzetten van C++/CX en WRL.

Zie ook Waar vind ik C++/WinRT-voorbeeld-apps?

Taalprojecties

De Windows Runtime is gebaseerd op COM-API's (Component Object Model) en is ontworpen voor toegang via taalprojecties. Een projectie verbergt de COM-details en biedt een natuurlijkere programmeerervaring voor een bepaalde taal.

De C++/WinRT-taalprojectie in de Windows Runtime API-referentie-inhoud

Wanneer u door Windows Runtime API's bladert, klikt u op de keuzelijst met invoervak Taal in de rechterbovenhoek en selecteert u C++/WinRT om API-syntaxisblokken weer te geven zoals deze worden weergegeven in de C++/WinRT-taalprojectie.

Visual Studio ondersteuning voor C++/WinRT, XAML, de VSIX-extensie en het NuGet-pakket

Voor Visual Studio ondersteuning hebt u Visual Studio 2022 of Visual Studio 2019 of Visual Studio 2017 nodig (minimaal versie 15.6; we raden ten minste 15.7 aan). Installeer in het programma Visual Studio Installer de workload Universeel Windows-platform development. Controleer in Installatiedetails>Universeel Windows-platform ontwikkeling de optie(s) voor C++ (v14x) Universeel Windows-platform hulpprogramma's als u dit nog niet hebt gedaan. En in Windows Instellingen>privacy en beveiliging (Windows 10: Bijwerken en bijwerken Beveiliging) >Schakel voor ontwikkelaars de optie Ontwikkelaarsmodus in (Windows 10: niet de optie Sideload-apps).

Hoewel we aanraden om te ontwikkelen met de nieuwste versies van Visual Studio en de Windows SDK, hebt u, als u een versie van C++/WinRT gebruikt die is meegeleverd met de Windows SDK van vóór 10.0.17763.0 (Windows 10, versie 1809), een minimale Windows SDK-doelversie van 10.0.17134.0 (Windows 10, versie 1803) in uw project nodig om de headers voor de hierboven genoemde Windows-naamruimten te kunnen gebruiken.

Visual Studio 2022 wordt geleverd met C++/WinRT-project- en itemsjablonen die zijn ingebouwd, zodat u meteen aan de slag kunt met C++/WinRT-ontwikkeling. Het wordt ook geleverd met Visual Studio systeemeigen foutopsporingsvisualisatie (natvis) van C++/WinRT-projecttypen; biedt een ervaring die vergelijkbaar is met C#-foutopsporing. Natvis wordt automatisch toegepast voor debug-builds. Zie Visual Studio systeemeigen foutopsporingsvisualisatie voor C++/WinRT voor meer informatie.

Voor oudere versies van Visual Studio wilt u de nieuwste versie van de extensie C++/WinRT Visual Studio (VSIX) downloaden en installeren vanuit de Visual Studio Marketplace.

• De VSIX-extensie biedt u C++/WinRT-project- en itemsjablonen in Visual Studio.
• Daarnaast biedt het u Visual Studio systeemeigen foutopsporingsvisualisatie (natvis) van C++/WinRT-projecttypen.

De Visual Studio projectsjablonen voor C++/WinRT worden beschreven in de onderstaande secties. Wanneer u een nieuw C++/WinRT-project maakt waarop de nieuwste versie van de VSIX-extensie is geïnstalleerd, installeert het nieuwe C++/WinRT-project automatisch de Microsoft.Windows. CppWinRT NuGet-pakket. De Microsoft.Windows. CppWinRT NuGet-pakket biedt C++/WinRT-buildondersteuning (MSBuild-eigenschappen en -doelen), waardoor uw project draagbaar is tussen een ontwikkelcomputer en een buildagent (waarop alleen het NuGet-pakket en niet de VSIX-extensie is geïnstalleerd).

U kunt ook een bestaand project converteren door het NuGet-pakket Microsoft.Windows.CppWinRT handmatig te installeren. Nadat u de nieuwste versie van de VSIX-extensie hebt geïnstalleerd (of daarnaar hebt bijgewerkt), opent u het bestaande project in Visual Studio, klikt u op Project>NuGet-pakketten beheren...>Bladeren, typt of plakt u Microsoft.Windows.CppWinRT in het zoekvak, selecteert u het item in de zoekresultaten en klikt u vervolgens op Installeren om het pakket voor dat project te installeren. Zodra u het pakket hebt toegevoegd, krijgt u C++/WinRT MSBuild-ondersteuning voor het project, inclusief het aanroepen van het cppwinrt.exe hulpprogramma.

• Omdat C++/WinRT gebruikmaakt van functies van de C++17-standaard, stelt het NuGet-pakket projecteigenschap C/C++>Language>C++ Language Standard>ISO C++17 Standard (/std:c++17) in Visual Studio in.
• Hiermee wordt ook de compileroptie /bigobj toegevoegd.
• Hiermee wordt de compileroptie /await toegevoegd om co_await in te schakelen.
• Hiermee wordt de XAML-compiler geïnstrueerd om C++/WinRT-codegen te verzenden.
• Mogelijk wilt u ook de conformheidsmodus instellen: Ja (/permissive-), waardoor uw code verder wordt beperkt tot standaarden die compatibel zijn.
• Een andere projecteigenschap waar u rekening mee moet houden, is C/C++>Algemeen>Waarschuwingen als fouten behandelen. Stel dit in op Ja (/WX) of Nee (/WX-) op smaak. Soms genereren bronbestanden die door het cppwinrt.exe hulpprogramma worden gegenereerd, waarschuwingen totdat u uw implementatie eraan toevoegt.

Als uw systeem is ingesteld zoals hierboven beschreven, kunt u een C++/WinRT-project maken en bouwen of openen in Visual Studio en implementeren.

Vanaf versie 2.0 omvat het NuGet-pakket Microsoft.Windows.CppWinRT het hulpprogramma cppwinrt.exe. U kunt het cppwinrt.exe hulpprogramma laten verwijzen naar een Windows Runtime metagegevensbestand (.winmd) om een standaard C++-bibliotheek op basis van headers te genereren die de API's projecteert die worden beschreven in de metagegevens voor gebruik vanuit C++/WinRT-code. Windows Runtime metagegevensbestanden (.winmd) bieden een canonieke manier om een Windows Runtime API-oppervlak te beschrijven. Door naar metagegevens te verwijzencppwinrt.exe, kunt u een bibliotheek genereren voor gebruik met elke runtimeklasse die is geïmplementeerd in een tweede of derde Windows Runtime-onderdeel, of geïmplementeerd in uw eigen toepassing. Zie API's gebruiken met C++/WinRT voor meer informatie.

Met C++/WinRT kunt u ook uw eigen runtimeklassen implementeren met behulp van standard C++, zonder gebruik te maken van COM-stijl programmeren. Voor een runtimeklasse beschrijft u alleen uw typen in een IDL-bestand en midl.execppwinrt.exe genereert u de standaard broncodebestanden voor de implementatie voor u. U kunt ook gewoon interfaces implementeren door te afgeleid van een C++/WinRT-basisklasse. Zie Author-API's met C++/WinRT voor meer informatie.

Zie de readme van het Microsoft.Windows.CppWinRT NuGet-pakket voor een lijst met aanpassingsopties voor het hulpprogramma cppwinrt.exe, die via projecteigenschappen worden ingesteld.

U kunt een project identificeren dat gebruikmaakt van de C++/WinRT MSBuild-ondersteuning door de aanwezigheid van de Microsoft.Windows. CppWinRT NuGet-pakket dat in het project is geïnstalleerd.

Hier volgen de Visual Studio projectsjablonen die worden geleverd door de VSIX-extensie.

Blanco app (C++/WinRT)

Een projectsjabloon voor een Universal Windows Platform (UWP)-app met een XAML-gebruikersinterface. Voor WinUI 3-bureaublad-apps gebruikt u in plaats daarvan de sjabloon Blank App, Packaged (WinUI 3 in Desktop).

Visual Studio biedt ondersteuning voor XAML-compiler voor het genereren van implementatie- en header-stubs van het IDL-bestand (Interface Definition Language).idl dat zich achter elk XAML-opmaakbestand bevindt. Definieer in een IDL-bestand alle lokale runtimeklassen waarnaar u wilt verwijzen op de XAML-pagina's van uw app en bouw vervolgens het project eenmaal om implementatiesjablonen te genereren in Generated Files, en stub-typedefinities in Generated Files\sources. Gebruik vervolgens deze stub-typedefinities voor referentie om uw lokale runtimeklassen te implementeren. Zie Runtime-klassen onderbrengen in Midl-bestanden (.idl).

De XAML-ontwerpoppervlakondersteuning in Visual Studio voor C++/WinRT ligt dicht bij pariteit met C#. In Visual Studio kunt u het tabblad Gebeurtenissen van het venster Eigenschappen gebruiken om gebeurtenis-handlers toe te voegen in een C++/WinRT-project. U kunt ook gebeurtenis-handlers handmatig toevoegen aan uw code. Zie Gebeurtenissen afhandelen met behulp van gemachtigden in C++/WinRT voor meer informatie.

Core App (C++/WinRT)

Een projectsjabloon voor een Universal Windows Platform (UWP)-app die geen XAML gebruikt. Er is geen WinUI 3-equivalent van deze sjabloon.

In plaats daarvan wordt de C++/WinRT-Windows naamruimteheader gebruikt voor de Windows. ApplicationModel.Core-naamruimte. Klik na het bouwen en uitvoeren op een lege ruimte om een gekleurd vierkant toe te voegen; klik vervolgens op een gekleurd vierkant om het te slepen.

Windows Console Toepassing (C++/WinRT)

Een projectsjabloon voor een C++/WinRT-clienttoepassing voor Windows Desktop, met een gebruikersinterface van de console.

Windows-bureaubladtoepassing (C++/WinRT)

Een projectsjabloon voor een C++/WinRT-clienttoepassing voor Windows Desktop, waarin een Windows Runtime Windows.Foundation.Uri wordt weergegeven in een Win32-MessageBox.

Windows Runtime-onderdeel (C++/WinRT)

Een projectsjabloon voor een onderdeel; meestal voor verbruik vanaf een Universal Windows Platform (UWP).

Deze sjabloon demonstreert de midl.exe>cppwinrt.exe hulpprogrammaketen, waarbij Windows Runtime metagegevens (.winmd) worden gegenereerd op basis van IDL en vervolgens implementatie- en header-stubs worden gegenereerd op basis van de Windows Runtime metagegevens.

Definieer in een IDL-bestand de runtimeklassen in uw onderdeel, de standaardinterface en eventuele andere interfaces die ze implementeren. Bouw het project een keer om module.g.cpp, module.h.cpp, implementatiesjablonen in Generated Files en stubtypedefinities in Generated Files\sources te genereren. Gebruik vervolgens de stub-typedefinities voor verwijzing om de runtimeklassen in uw onderdeel te implementeren. Zie Runtimeklassen onderbrengen in MIDL-bestanden (.idl).

Bundel het ingebouwde binaire Windows Runtime-onderdeel en het bijbehorende .winmd met de UWP-app die ze gebruikt.

Eerdere versies van de VSIX-extensie

U wordt aangeraden de nieuwste versie van de VSIX-extensie te installeren (of bij te werken naar). Deze is geconfigureerd om zichzelf standaard bij te werken. Als u dit doet en u projecten hebt die zijn gemaakt met een versie van de VSIX-extensie eerder dan 1.0.190128.4, bevat deze sectie belangrijke informatie over het upgraden van deze projecten om te werken met de nieuwe versie. Als u deze niet bijwerkt, vindt u de informatie in deze sectie nog steeds nuttig.

Wat de ondersteunde Windows SDK- en Visual Studio-versies en Visual Studio configuratie betreft, zijn de informatie in de Visual Studio ondersteuning voor C++/WinRT, XAML, de VSIX-extensie en de sectie NuGet-pakketten hierboven van toepassing op eerdere versies van de VSIX-extensie. In de onderstaande informatie worden belangrijke verschillen beschreven met betrekking tot het gedrag en de configuratie van projecten die zijn gemaakt met (of bijgewerkt om te werken met) eerdere versies.

Eerder gemaakt dan 1.0.181002.2

Als uw project is gemaakt met een versie van de VSIX-extensie ouder dan 1.0.181002.2, is C++/WinRT-buildondersteuning ingebouwd in die versie van de VSIX-extensie. Voor uw project is de <CppWinRTEnabled>true</CppWinRTEnabled> eigenschap ingesteld in het .vcxproj bestand.

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

U kunt uw project upgraden door handmatig het Microsoft.Windows.CppWinRT NuGet-pakket te installeren. Nadat u de nieuwste versie van de VSIX-extensie hebt geïnstalleerd (of ernaar hebt bijgewerkt), opent u uw project in Visual Studio, klikt u op Project>NuGet-pakketten beheren...>Bladeren, typt of plakt u Microsoft.Windows.CppWinRT in het zoekvak, selecteert u het item in de zoekresultaten en klikt u vervolgens op Installeren om het pakket voor uw project te installeren.

Gemaakt met (of bijgewerkt naar) tussen 1.0.181002.2 en 1.0.190128.3

Als uw project is gemaakt met een versie van de VSIX-extensie tussen 1.0.181002.2 en 1.0.190128.3, inclusief, dan de Microsoft.Windows. CppWinRT NuGet-pakket is automatisch in het project geïnstalleerd door de projectsjabloon. Mogelijk hebt u ook een upgrade van een ouder project uitgevoerd om een versie van de VSIX-extensie in dit bereik te gebruiken. Als u dat hebt gedaan, kan het zijn dat uw bijgewerkte project het NuGet-pakket Microsoft.Windows.CppWinRT wel of niet heeft geïnstalleerd, aangezien ondersteuning voor builds ook nog aanwezig was in versies van de VSIX-extensie binnen dit bereik.

Als u uw project wilt upgraden, volgt u de instructies in de vorige sectie en zorgt u ervoor dat uw project beschikt over de Microsoft.Windows. CppWinRT NuGet-pakket geïnstalleerd.

Ongeldige upgradeconfiguraties

Met de nieuwste versie van de VSIX-extensie mag een project de eigenschap <CppWinRTEnabled>true</CppWinRTEnabled> niet hebben als ook het NuGet-pakket Microsoft.Windows.CppWinRT niet is geïnstalleerd. Een project met deze configuratie produceert het buildfoutbericht: 'De C++/WinRT VSIX biedt geen ondersteuning meer voor projectbuilds. Voeg een projectreferentie toe aan de Microsoft.Windows. CppWinRT Nuget-pakket."

Zoals hierboven vermeld, moet in een C++/WinRT-project nu het NuGet-pakket zijn geïnstalleerd.

Omdat het <CppWinRTEnabled> element nu verouderd is, kunt u het .vcxprojelement desgewenst bewerken en het element verwijderen. Het is niet strikt noodzakelijk, maar het is een optie.

Als uw .vcxproj<RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles> bevat, kunt u dit verwijderen, zodat u kunt bouwen zonder dat de C++/WinRT VSIX-extensie geïnstalleerd hoeft te zijn.

SDK-ondersteuning voor C++/WinRT

Hoewel deze nu alleen nog om compatibiliteitsredenen aanwezig is, bevat de Windows SDK vanaf versie 10.0.17134.0 (Windows 10, versie 1803) een op headerbestanden gebaseerde standaard C++-bibliotheek voor het gebruik van Windows-API's van Microsoft zelf (Windows Runtime-API's in Windows-naamruimten). Deze headers bevinden zich in de map %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. Vanaf de Windows SDK-versie 10.0.17763.0 (Windows 10 versie 1809) worden deze headers voor u gegenereerd in de map $(GeneratedFilesDir) van uw project.

Voor compatibiliteit wordt de Windows SDK ook geleverd met het cppwinrt.exe hulpprogramma. We raden u echter aan in plaats daarvan de meest recente versie van cppwinrt.exe te installeren en te gebruiken, die is opgenomen in het Microsoft.Windows.CppWinRT NuGet-pakket. Dat pakket en cppwinrt.exe, worden beschreven in de bovenstaande secties.

Aangepaste typen in de C++/WinRT-projectie

In uw C++/WinRT-programmering kunt u standaard C++-taalfuncties en Standard C++-gegevenstypen en C++/WinRT gebruiken, waaronder enkele C++ Standaardbibliotheekgegevenstypen. Maar u zult ook op de hoogte worden van een aantal aangepaste gegevenstypen in de projectie en u kunt ervoor kiezen om ze te gebruiken. We gebruiken bijvoorbeeld winrt::hstring in het quickstartcodevoorbeeld in Aan de slag met C++/WinRT.

winrt::com_array is een ander type dat u waarschijnlijk op een bepaald moment zult gebruiken. Maar u zult minder snel een type zoals winrt::array_view gebruiken. U kunt er ook voor kiezen om deze niet te gebruiken, zodat u geen code hebt om te wijzigen als en wanneer een equivalent type wordt weergegeven in de C++-standaardbibliotheek.

Belangrijke API's

• winrt::hstring-struct
• winrt-naamruimte

Verwante onderwerpen

• C++/CX
• C++/WinRT Visual Studio-extensie (VSIX)
• Aan de slag met C++/WinRT
• Standaard C++ gegevenstypen en C++/WinRT
• Verwerking van tekenreeksen in C++/WinRT
• API's voor Windows Runtime