Einführung in C++/WinRT

2025-06-10

C++/WinRT ist eine völlig standardmäßige moderne C++17-Sprachprojektion für Windows Runtime (WinRT)-APIs, die als headerdatei-basierte Bibliothek implementiert ist und konzipiert wurde, um Ihnen erstklassigen Zugriff auf die moderne Windows-API zu bieten. Mit C++/WinRT können Sie Windows-Runtime-APIs mit jedem standardkonformen C++17-Compiler erstellen und nutzen. Das Windows SDK enthält C++/WinRT; Es wurde in Version 10.0.17134.0 (Windows 10, Version 1803) eingeführt.

C++/WinRT ist Microsofts empfohlener Ersatz für die C++/CX- Sprachprojektion und die Windows-Runtime-C++-Vorlagenbibliothek (WRL). Die vollständige Liste der Themen zu C++/WinRT enthält Informationen über sowohl die Interoperabilität mit als auch Portierungen von C++/CX und WRL.

Von Bedeutung

Einige der wichtigsten Zu beachtenden Komponenten von C++/WinRT werden in den Abschnitten SDK-Unterstützung für C++/WinRT und Visual Studio-Unterstützung für C++/WinRT, XAML, die VSIX-Erweiterung und das NuGet-Paketbeschrieben.

Siehe auch Wo finde ich C++/WinRT-Beispiel-Apps?.

Sprachprognosen

Die Windows-Runtime basiert auf COM-APIs (Component Object Model) und ist darauf ausgelegt, über Sprachprojektionendarauf zuzugreifen. Eine Projektion blendet die COM-Details aus und bietet eine natürlichere Programmiererfahrung für eine bestimmte Sprache.

Die C++/WinRT-Sprachprojektion im Referenzinhalt der Windows-Runtime-API

Wenn Sie Windows-Runtime-APIsdurchsuchen, klicken Sie oben rechts auf das Kombinationsfeld Sprache, und wählen Sie C++/WinRT- aus, um API-Syntaxblöcke anzuzeigen, wie sie in der C++/WinRT-Sprachprojektion angezeigt werden.

Visual Studio-Unterstützung für C++/WinRT, XAML, die VSIX-Erweiterung und das NuGet-Paket

Für die Visual Studio-Unterstützung benötigen Sie Visual Studio 2022 oder Visual Studio 2019 oder Visual Studio 2017 (mindestens Version 15.6; wir empfehlen mindestens 15.7). Installieren Sie im Visual Studio Installer die Entwicklung Arbeitsauslastung für die universelle Windows-Plattform. Überprüfen Sie in Installationsdetails>Universal Windows Platform-Entwicklungdie C++-Tools (v14x) für die Universellen Windows-Plattform, falls Sie dies noch nicht getan haben. Und aktivieren Sie in Windows-Einstellungen>Datenschutz und Sicherheit (Windows 10: Update & Sicherheit) >Für Entwickler die Option "Entwicklermodus " (Windows 10: nicht die Option " Querladen von Apps ").

Es wird jedoch empfohlen, mit den neuesten Versionen von Visual Studio und dem Windows SDK zu entwickeln. Wenn Sie eine Version von C++/WinRT verwenden, die mit dem Windows SDK vor 10.0.17763.0 (Windows 10, Version 1809) ausgeliefert wurde, benötigen Sie zum Verwenden der oben genannten Windows-Namespaceheader eine Mindestversion des Windows SDK-Ziels in Ihrem Projekt von 10.0.17134.0 (Windows 10, Version 1803).

Visual Studio 2022 wird mit integrierten C++/WinRT-Projekt- und Elementvorlagen ausgeliefert, sodass Sie sofort mit der C++/WinRT-Entwicklung beginnen können. Es enthält auch eine native Debugvisualisierung (natvis) für C++/WinRT-projizierte Typen in Visual Studio, was eine Erfahrung bietet, die dem C#-Debuggen ähnelt. Natvis ist automatisch für Debug-Builds. Weitere Informationen finden Sie unter der nativen Debug-Visualisierung von Visual Studio für C++/WinRT.

Für ältere Versionen von Visual Studio sollten Sie die neueste Version der C++/WinRT Visual Studio Extension (VSIX) aus dem Visual Studio Marketplaceherunterladen und installieren.

Die VSIX-Erweiterung bietet Ihnen C++/WinRT-Projekt- und Elementvorlagen in Visual Studio.
Darüber hinaus erhalten Sie eine native Debugvisualisierung (Natvis) von projizierten C++/WinRT-Typen von Visual Studio.

Die Visual Studio-Projektvorlagen für C++/WinRT werden in den folgenden Abschnitten beschrieben. Wenn Sie ein neues C++/WinRT-Projekt mit der neuesten Version der installierten VSIX-Erweiterung erstellen, installiert das neue C++/WinRT-Projekt automatisch das Microsoft.Windows.CppWinRT NuGet-Paket. Das Microsoft.Windows.CppWinRT NuGet-Paket bietet Unterstützung für C++/WinRT-Builds (MSBuild-Eigenschaften und -Ziele), wodurch Ihr Projekt zwischen einem Entwicklungscomputer und einem Build-Agenten portierbar wird, auf denen nur das NuGet-Paket installiert ist und nicht die VSIX-Erweiterung.

Alternativ können Sie ein vorhandenes Projekt konvertieren, indem Sie das Microsoft.Windows.CppWinRT NuGet-Paket manuell installieren. Öffnen Sie nach der Installation (oder Aktualisierung auf) die neueste Version der VSIX-Erweiterung das vorhandene Projekt in Visual Studio, klicken Sie auf Projekt>NuGet-Pakete verwalten...>Durchsuchen Sie, geben Sie Microsoft.Windows.CppWinRT im Suchfeld ein, wählen Sie das Element in den Suchergebnissen aus, und klicken Sie dann auf Installieren, um das Paket für dieses Projekt zu installieren. Nachdem Sie das Paket hinzugefügt haben, erhalten Sie C++/WinRT MSBuild-Unterstützung für das Projekt, einschließlich des Aufrufens des cppwinrt.exe-Tools.

Von Bedeutung

Wenn Sie Projekte haben, die mit einer älteren Version der VSIX-Erweiterung als 1.0.190128.4 erstellt oder auf diese Version aktualisiert wurden, lesen Sie Frühere Versionen der VSIX-Erweiterung. Dieser Abschnitt enthält wichtige Informationen zur Konfiguration Ihrer Projekte, die Sie wissen müssen, um sie auf die neueste Version der VSIX-Erweiterung zu aktualisieren.

Da C++/WinRT Features aus dem C++17-Standard verwendet, legt das NuGet-Paket die Projekteigenschaft C/C++>Language>C++-Sprachstandard>ISO C++17 Standard (/std:c++17) in Visual Studio fest.
Außerdem wird die Compileroption /bigobj hinzugefügt.
Sie fügt die Option /await Compiler hinzu, um co_awaitzu aktivieren.
Es weist den XAML-Compiler an, C++/WinRT-Codegen zu erzeugen.
Möglicherweise möchten Sie auch den Konformitätsmodus auf Ja (/permissiv-)setzen, wodurch Ihr Code weiter standardskonform wird.
Eine weitere zu beachtende Projekteigenschaft ist C/C++>Allgemein>Warnungen als Fehler behandeln. Legen Sie dies nach Belieben auf Ja(/WX) oder Nein (/WX-) fest. Manchmal generieren Quelldateien, die vom cppwinrt.exe Tool generiert werden, Warnungen, bis Sie die Implementierung hinzufügen.

Nachdem Ihr System wie oben beschrieben eingerichtet wurde, können Sie ein C++/WinRT-Projekt in Visual Studio erstellen und bauen oder öffnen und anschließend bereitstellen.

Seit Version 2.0 enthält das Microsoft.Windows.CppWinRT NuGet-Paket das cppwinrt.exe Tool. Sie können das cppwinrt.exe Tool auf eine Windows-Runtime-Metadatendatei (.winmd) verweisen, um eine auf Headerdatei basierende C++-Standardbibliothek zu generieren, die Projekten den APIs, die in den Metadaten für die Nutzung aus C++/WinRT-Code beschrieben sind. Windows-Runtime-Metadaten (.winmd) bieten eine kanonische Methode zum Beschreiben einer Windows-Runtime-API-Oberfläche. Indem Sie cppwinrt.exe auf Metadaten verweisen, können Sie eine Bibliothek generieren, die mit jeder Laufzeitklasse verwendet werden kann, die in einer Windows-Runtime-Komponente von Zweit- oder Drittanbietern oder in Ihrer eigenen Anwendung implementiert ist. Weitere Informationen finden Sie unter Nutzen von APIs mit C++/WinRT.

Mit C++/WinRT können Sie auch ihre eigenen Laufzeitklassen mithilfe von Standard-C++ implementieren, ohne auf die PROGRAMMIERUNG im COM-Stil zurückgreifen zu müssen. Für eine Laufzeitklasse beschreiben Sie einfach Ihre Typen in einer IDL-Datei, und midl.exe und cppwinrt.exe generieren Ihre Quellcodedateien mit Implementierungsvorlagen für Sie. Alternativ können Sie Schnittstellen implementieren, indem Sie von einer C++/WinRT-Basisklasse ableiten. Weitere Informationen finden Sie unter Autoren-APIs mit C++/WinRT.

Eine Liste der Anpassungsoptionen für das cppwinrt.exe Tool, die über Projekteigenschaften festgelegt werden, finden Sie im Microsoft.Windows.CppWinRT NuGet-Paket Readme-.

Sie können ein Projekt, das die C++/WinRT MSBuild-Unterstützung nutzt, daran erkennen, dass das Microsoft.Windows.CppWinRT NuGet-Paket im Projekt installiert ist.

Hier sind die Visual Studio-Projektvorlagen, die von der VSIX-Erweiterung bereitgestellt werden.

Leere App (C++/WinRT)

Eine Projektvorlage für eine UWP-App (Universelle Windows-Plattform), die über eine XAML-Benutzeroberfläche verfügt.

Visual Studio bietet XAML-Compilerunterstützung zum Generieren von Implementierungs- und Header-Stubs aus der IDL-Datei (Interface Definition Language) (.idl), die sich hinter jeder XAML-Markupdatei befindet. Definieren Sie in einer IDL-Datei alle lokalen Laufzeitklassen, auf die Sie in den XAML-Seiten Ihrer App verweisen möchten, und erstellen Sie das Projekt dann einmal, um Implementierungsvorlagen in Generated Filesund Stub-Typdefinitionen in Generated Files\sourceszu generieren. Verwenden Sie dann diese Stubtypdefinitionen als Referenz, um Ihre lokalen Laufzeitklassen zu implementieren. Siehe Aufteilen von Laufzeitklassen in MIDL-Dateien (.idl).

Die Unterstützung der XAML-Entwurfsoberfläche in Visual Studio für C++/WinRT ist nahezu auf Augenhöhe mit C#. In Visual Studio können Sie die Registerkarte Ereignisse des Fensters Eigenschaften verwenden, um Ereignishandler in einem C++/WinRT-Projekt hinzuzufügen. Sie können Ihrem Code auch Ereignishandler manuell hinzufügen – weitere Informationen finden Sie unter Behandeln von Ereignissen mithilfe von Delegaten in C++/WinRT.

Core App (C++/WinRT)

Eine Projektvorlage für eine UWP-App (Universelle Windows-Plattform), die xaml nicht verwendet.

Stattdessen wird der C++/WinRT Windows-Namespace-Header für den Windows.ApplicationModel.Core-Namespace verwendet. Klicken Sie nach dem Erstellen und Ausführen auf eine freie Fläche, um ein farbiges Quadrat hinzuzufügen. Klicken Sie dann auf ein farbiges Quadrat, um es zu verschieben.

Windows-Konsolenanwendung (C++/WinRT)

Eine Projektvorlage für eine C++/WinRT-Clientanwendung für Windows Desktop mit einer Konsolenbenutzeroberfläche.

Windows-Desktopanwendung (C++/WinRT)

Eine Projektvorlage für eine C++/WinRT-Clientanwendung für Windows Desktop, die eine Windows Runtime Windows.Foundation.Uri innerhalb einer Win32 MessageBoxanzeigt.

Komponente für Windows-Runtime (C++/WinRT)

Eine Projektvorlage für eine Komponente, typischerweise zur Nutzung in einer Universal Windows Platform (UWP).

Diese Vorlage veranschaulicht die midl.exe>cppwinrt.exe Toolkette, in der Windows-Runtime-Metadaten (.winmd) aus IDL generiert werden, und anschließend werden Implementierungs- und Header-Stubs aus den Windows-Runtime-Metadaten generiert.

Definieren Sie in einer IDL-Datei die Laufzeitklassen in Ihrer Komponente, deren Standardschnittstelle und alle anderen Schnittstellen, die sie implementieren. Erstellen Sie das Projekt einmal, um module.g.cpp, module.h.cpp, Implementierungsvorlagen in Generated Filesund Stubtypdefinitionen in Generated Files\sourceszu generieren. Verwenden Sie dann die Stubtypdefinitionen als Referenz, um die Laufzeitklassen in Ihrer Komponente zu implementieren. Siehe Aufteilen von Laufzeitklassen in MIDL-Dateien (.idl).

Bündeln Sie die integrierte Windows-Runtime-Komponente binär und ihre .winmd mit der UWP-App, die sie verwendet.

Frühere Versionen der VSIX-Erweiterung

Es wird empfohlen, die neueste Version der VSIX-Erweiterungzu installieren (oder zu aktualisieren). Sie ist standardmäßig so konfiguriert, dass sie selbst aktualisiert wird. Wenn Sie dies tun, und Sie über Projekte verfügen, die mit einer Version der VSIX-Erweiterung vor 1.0.190128.4 erstellt wurden, enthält dieser Abschnitt wichtige Informationen zum Aktualisieren dieser Projekte für die Arbeit mit der neuen Version. Wenn Sie die Aktualisierung nicht ausführen, finden Sie weiterhin die Informationen in diesem Abschnitt hilfreich.

In Bezug auf die unterstützten Versionen des Windows SDK und von Visual Studio sowie die Konfiguration von Visual Studio gelten die Informationen im Abschnitt Visual Studio-Unterstützung für C++/WinRT, XAML, die VSIX-Erweiterung und das NuGet-Paket oben für frühere Versionen der VSIX-Erweiterung. In den folgenden Informationen werden wichtige Unterschiede im Hinblick auf das Verhalten und die Konfiguration von Projekten beschrieben, die mit früheren Versionen erstellt (oder aktualisiert wurden), um mit früheren Versionen zu arbeiten.

Erstellt vor 1.0.181002.2

Wenn Ihr Projekt mit einer Version der VSIX-Erweiterung vor 1.0.181002.2 erstellt wurde, wurde die C++/WinRT-Buildunterstützung in diese Version der VSIX-Erweiterung integriert. Das Projekt hat die Eigenschaft <CppWinRTEnabled>true</CppWinRTEnabled> in der Datei .vcxproj festgelegt.

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

Sie können Ihr Projekt aktualisieren, indem Sie das Microsoft.Windows.CppWinRT NuGet-Paket manuell installieren. Nachdem Sie die neueste Version der VSIX-Erweiterung installiert oder auf diese aktualisiert haben, öffnen Sie Ihr Projekt in Visual Studio, klicken Sie auf Projekt>NuGet-Pakete verwalten...>Durchsuchen, geben Sie Microsoft.Windows.CppWinRT im Suchfeld ein, wählen Sie das Element in den Suchergebnissen aus und klicken Sie auf Installieren, um das Paket für Ihr Projekt zu installieren.

Erstellt mit (oder aktualisiert auf) zwischen 1.0.181002.2 und 1.0.190128.3

Wenn Ihr Projekt mit einer Version der VSIX-Erweiterung zwischen 1.0.181002.2 und 1.0.190128.3 erstellt wurde, wurde das Microsoft.Windows.CppWinRT NuGet-Paket automatisch durch die Projektvorlage installiert. Möglicherweise haben Sie auch ein älteres Projekt aktualisiert, um eine Version der VSIX-Erweiterung in diesem Bereich zu verwenden. Wenn Sie dies getan haben, ist Ihr aktualisiertes Projekt möglicherweise – da die Buildunterstützung auch in Versionen der VSIX-Erweiterung in diesem Bereich vorhanden war – möglicherweise das Microsoft.Windows.CppWinRT NuGet-Paket installiert.

Um ihr Projekt zu aktualisieren, befolgen Sie die Anweisungen im vorherigen Abschnitt, und stellen Sie sicher, dass ihr Projekt über die Microsoft.Windows.CppWinRT NuGet-Paket installiert ist.

Ungültige Upgradekonfigurationen

Mit der neuesten Version der VSIX-Erweiterung ist es nicht gültig, dass ein Projekt die <CppWinRTEnabled>true</CppWinRTEnabled> Eigenschaft hat, wenn nicht auch das Microsoft.Windows.CppWinRT- NuGet-Paket installiert ist. Ein Projekt mit dieser Konfiguration erzeugt die Buildfehlermeldung: "Der C++/WinRT VSIX stellt keine Projektbuildunterstützung mehr bereit. Fügen Sie bitte einen Projektverweis zum Microsoft.Windows.CppWinRT Nuget-Paket hinzu."

Wie bereits erwähnt, muss nun ein C++/WinRT-Projekt das NuGet-Paket darin installiert haben.

Da das <CppWinRTEnabled>-Element jetzt veraltet ist, können Sie optional Ihre .vcxprojbearbeiten und das Element löschen. Es ist nicht unbedingt notwendig, aber es ist eine Option.

Auch wenn Ihr .vcxproj<RequiredBundles>$(RequiredBundles);Microsoft.Windows.CppWinRT</RequiredBundles>enthält, können Sie es entfernen, damit Sie kompilieren können, ohne dass die C++/WinRT VSIX-Erweiterung installiert ist.

SDK-Unterstützung für C++/WinRT

Obwohl es jetzt nur aus Kompatibilitätsgründen vorhanden ist, enthält das Windows SDK ab Version 10.0.17134.0 (Windows 10, Version 1803) eine C++-Standardbibliothek, die auf Header-Dateien basiert, zum Konsumieren von First-Party-Windows-APIs (Windows-Runtime-APIs in Windows-Namespaces). Diese Kopfzeilen befinden sich im Ordner %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt. Ab der Windows SDK-Version 10.0.17763.0 (Windows 10, Version 1809) werden diese Header für Sie innerhalb des $(GeneratedFilesDir)- Ordners Ihres Projekts generiert.

Aus Gründen der Kompatibilität enthält das Windows SDK auch das cppwinrt.exe Tool. Es wird jedoch empfohlen, stattdessen die neueste Version von cppwinrt.exezu installieren und zu verwenden, die im Microsoft.Windows.CppWinRT NuGet-Paket enthalten ist. Dieses Paket und cppwinrt.exewerden in den obigen Abschnitten beschrieben.

Benutzerdefinierte Typen in der C++/WinRT-Projektion

In Ihrer C++/WinRT-Programmierung können Sie Standard-C++-Sprachfeatures und Standard-C++-Datentypen und C++/WinRT-verwenden, einschließlich einiger Datentypen der C++-Standardbibliothek. Sie werden sich jedoch auch einiger benutzerdefinierter Datentypen in der Projektion bewusst werden und können sich entscheiden, diese zu verwenden. Wir verwenden z. B. winrt::hstring im Schnellstartcodebeispiel in Erste Schritte mit C++/WinRT.

winrt::com_array ist ein weiterer Typ, den Sie wahrscheinlich irgendwann einmal verwenden werden. Es ist jedoch weniger wahrscheinlich, dass Sie einen Typ wie winrt::array_viewdirekt verwenden. Oder Sie können darauf verzichten, damit Sie keinen Code ändern müssen, falls und wenn ein gleichwertiger Typ in der C++-Standardbibliothek erscheint.

Warnung

Es gibt auch Typen, die Ihnen begegnen könnten, wenn Sie die C++/WinRT Windows-Namespace-Header genau untersuchen. Ein Beispiel ist winrt::param::hstring, aber es gibt auch Beispiele für Sammlungen. Diese existieren ausschließlich, um die Bindung von Eingabeparametern zu optimieren, erzielen große Leistungsverbesserungen und sorgen dafür, dass die meisten Aufrufmuster für verwandte Standard-C++-Typen und -Container einfach funktionieren. Diese Typen werden immer nur von der Projektion verwendet, wenn sie den größten Wert hinzufügen. Sie sind hoch optimiert und nicht für die allgemeine Verwendung gedacht; lassen Sie sich nicht dazu verleiten, sie selbst zu verwenden. Sie sollten auch nichts aus dem winrt::impl-Namespace verwenden, da es sich um Implementierungstypen handelt und daher änderungen unterliegen. Sie sollten weiterhin Standardtypen oder Typen aus dem winrt-Namespaceverwenden.

Siehe auch Übermittlung von Parametern an die ABI-Grenze.