Windows-Runtime-Komponenten mit C++/WinRT

In diesem Thema wird gezeigt, wie Sie C++/WinRT verwenden, um eine Windows Runtime-Komponente zu erstellen und zu nutzen– eine Komponente, die über eine universelle Windows-App aufrufbar ist, die mit einer beliebigen Windows Runtime-Sprache erstellt wurde.

Es gibt mehrere Gründe für das Erstellen einer Windows Runtime-Komponente in C++/WinRT.

  • Um den Leistungsvorteil von C++ in komplexen oder rechenintensiven Vorgängen zu nutzen.
  • Um C++-Standardcode wiederzuverwenden, der bereits geschrieben und getestet wurde.
  • Um Win32-Funktionen für eine UWP-App (Universelle Windows-Plattform) verfügbar zu machen, die in geschrieben wurde, z. B. C#.

Wenn Sie Ihre C++/WinRT-Komponente erstellen, können Sie im Allgemeinen Typen aus der C++-Standardbibliothek und integrierte Typen verwenden, mit Ausnahme der ABI-Grenze (Application Binary Interface), an der Sie Daten an und aus Code in einem anderen Paket .winmd übergeben. Verwenden Sie in der ABI Windows Runtime-Typen. Verwenden Sie außerdem in Ihrem C++/WinRT-Code Typen wie Delegat und Ereignis, um Ereignisse zu implementieren, die von Ihrer Komponente ausgelöst und in einer anderen Sprache behandelt werden können. Weitere Informationen zu C++/WinRT finden Sie unter C++/WinRT.

Im restlichen Teil dieses Themas erfahren Sie, wie Sie eine Windows Runtime-Komponente in C++/WinRT erstellen und dann aus einer Anwendung nutzen.

Die Windows Runtime-Komponente, die Sie in diesem Thema erstellen, enthält eine Laufzeitklasse, die ein Thermometer darstellt. Das Thema veranschaulicht auch eine Core-App, die die Laufzeitklasse thermometer verwendet und eine Funktion aufruft, um die Temperatur anzupassen.

Hinweis

Informationen zum Installieren und Verwenden der Visual Studio-Erweiterung (VSIX) C++/WinRT und des NuGet-Pakets (die zusammen die Projektvorlage und Buildunterstützung bereitstellen) findest du unter Visual Studio support for C++/WinRT, XAML, the VSIX extension, and the NuGet package (Visual Studio-Unterstützung für C++/WinRT, XAML, die VSIX-Erweiterung und das NuGet-Paket).

Wichtig

Wichtige Konzepte und Begriffe im Zusammenhang mit der Nutzung und Erstellung von Laufzeitklassen mit C++/WinRT findest du unter Verwenden von APIs mit C++/WinRT sowie unter Erstellen von APIs mit C++/WinRT.

Erstellen einer Windows Runtime-Komponente (ThermometerWRC)

Erstelle zunächst ein neues Projekt in Microsoft Visual Studio. Erstellen Sie ein Windows Runtime Component(C++/WinRT)-Projekt, und nennen Sie es ThermometerWRC (für "thermometer Windows Runtime-Komponente"). Stelle sicher, dass Platzieren Sie die Projektmappe und das Projekt im selben Verzeichnis deaktiviert ist. Die neueste allgemein verfügbare Version von Windows SDK (d. h. keine Vorschauversion). Die Benennung des Projekts ThermometerWRC bietet Ihnen die einfachste Erfahrung mit den restlichen Schritten in diesem Thema.

Führen Sie noch keinen Buildvorgang für das Projekt aus.

Das neu erstellte Projekt enthält eine Datei namens Class.idl. Ändern Sie im Projektmappen-Explorer den Namen der Datei Thermometer.idl. (Durch die Umbenennung der Datei vom Typ .idl werden automatisch auch die abhängigen Dateien .h und .cpp umbenannt.) Ersetze den Inhalt von Thermometer.idl durch das folgende Listing:

// Thermometer.idl
namespace ThermometerWRC
{
    runtimeclass Thermometer
    {
        Thermometer();
        void AdjustTemperature(Single deltaFahrenheit);
    };
}

Speichern Sie die Datei. Das Projekt wird derzeit nicht bis zum Abschluss erstellt, aber jetzt zu erstellen ist hilfreich, da es die Quellcodedateien generiert, in denen Sie die Laufzeitklasse Thermometer implementieren. Erstelle daher als Nächstes das Projekt. (Die in dieser Phase zu erwartenden Buildfehler sind darauf zurückzuführen, dass Class.h und Class.g.h nicht gefunden wurden.)

Während des Buildprozesses wird das Tool midl.exe ausgeführt, um die Windows-Runtime-Metadatendatei (\ThermometerWRC\Debug\ThermometerWRC\ThermometerWRC.winmd) deiner Komponente zu erstellen. Danach wird das Tool cppwinrt.exe (mit der Option -component) ausgeführt, um Quellcodedateien zu generieren, die dich bei der Erstellung deiner Komponente unterstützen. Diese Dateien enthalten Stubs, um Ihnen den Einstieg in die Implementierung der Thermometer-Laufzeitklasse zu geben, die Sie in Ihrer IDL deklariert haben. Diese Stubs sind \ThermometerWRC\ThermometerWRC\Generated Files\sources\Thermometer.h und Thermometer.cpp.

Klicke mit der rechten Maustaste auf den Projektknoten, und klicke auf Ordner in Datei-Explorer öffnen. Dadurch wird der Projektordner im Datei-Explorer geöffnet. Kopiere dort die Stub-Dateien Thermometer.h und Thermometer.cpp aus dem Ordner \ThermometerWRC\ThermometerWRC\Generated Files\sources\ in den Ordner mit deinen Projektdateien (\ThermometerWRC\ThermometerWRC\), und ersetze die Dateien am Ziel. Als Nächstes öffnen wir Thermometer.h und Thermometer.cpp und implementieren unsere Laufzeitklasse. Fügen Sie in der Implementierung (nicht der Factoryimplementierung) von Thermometer ein neues Thermometer.h privates Member hinzu.Thermometer.h

// Thermometer.h
...
namespace winrt::ThermometerWRC::implementation
{
    struct Thermometer : ThermometerT<Thermometer>
    {
        ...

    private:
        float m_temperatureFahrenheit { 0.f };
    };
}
...

Implementieren Thermometer.cpp Sie in die Thermometer.cpp wie in der folgenden Auflistung gezeigt.

// Thermometer.cpp
...
namespace winrt::ThermometerWRC::implementation
{
    void Thermometer::AdjustTemperature(float deltaFahrenheit)
    {
        m_temperatureFahrenheit += deltaFahrenheit;
    }
}

Du siehst eine static_assert-Deklaration am Anfang von Thermometer.h und Thermometer.cpp, die du entfernen musst. Jetzt wird das Projekt erstellt.

Wenn Sie durch Warnungen daran gehindert werden, zu erstellen, lösen Sie sie entweder auf, oder legen Sie die Projekteigenschaft C/C++Allgemein Warnungen als Fehler behandeln auf Nein (/WX-)fest, und erstellen Sie das Projekt erneut.

Erstellen einer Core-App (ThermometerCoreApp) zum Testen der Windows Runtime-Komponente

Erstellen Sie nun ein neues Projekt (entweder in Ihrer ThermometerWRC-Projektmappe oder in einem neuen Projekt). Erstellen Sie ein Core App-Projekt (C++/WinRT), und nennen Sie es ThermometerCoreApp. Legen Sie ThermometerCoreApp als Startprojekt fest, wenn sich die beiden Projekte in derselben Projektmappe befinden.

Hinweis

Wie bereits erwähnt, wird die Windows Runtime-Metadatendatei für Ihre Windows Runtime-Komponente (deren Projekt Sie ThermometerWRCgenannt haben) im Ordner erstellt. Das erste Segment dieses Pfads ist der Name des Ordners, der die Projektmappendatei enthält, das nächste Segment ist dessen Unterverzeichnis namens Debug, das letzte Segment ist das Unterverzeichnis, das nach der Komponente für Windows-Runtime benannt ist. Wenn Sie Ihr Projekt nicht Als ThermometerWRCbezeichnet haben, befindet sich Ihre Metadatendatei im Ordner .

Fügen Sie nun in Ihrem Core-App-Projekt (ThermometerCoreApp)einen Verweis hinzu, und navigieren Sie zu (oder fügen Sie einen Projekt-zu-Projekt-Verweis hinzu, wenn sich die beiden Projekte in derselben Projektmappe befinden). Klicke auf Hinzufügen und anschließend auf OK. Erstellen Sie nun ThermometerCoreApp. Im unwahrscheinlichen Fall, dass ein Fehler angezeigt wird, dass die Nutzlastdatei nicht vorhanden ist, schließen Sie diese Datei aus dem Windows Runtime-Komponentenprojekt aus, erstellen Sie sie neu, und erstellen Sie readme.txtreadme.txt

Während des Buildprozesses wird das Tool cppwinrt.exe ausgeführt, um die referenzierte Datei vom Typ .winmd zu Quellcodedateien mit projizierten Typen zu verarbeiten, die dich bei der Nutzung deiner Komponente unterstützen. Der Header für die projizierten Typen für die Laufzeitklassen Ihrer Komponente mit dem Namen ThermometerWRC.h wird im Ordner \ThermometerCoreApp\ThermometerCoreApp\Generated Files\winrt\ generiert.

Schließe diesen Header in App.cpp ein.

// App.cpp
...
#include <winrt/ThermometerWRC.h>
...

Fügen Sie außerdem in den folgenden Code hinzu, um ein Thermometer-Objekt (unter Verwendung des Standardkonstruktors des projizierten Typs) zu instanziieren und eine Methode für das App.cpp Thermometerobjekt aufzurufen. App.cpp

struct App : implements<App, IFrameworkViewSource, IFrameworkView>
{
    ThermometerWRC::Thermometer m_thermometer;
    ...
    
    void OnPointerPressed(IInspectable const &, PointerEventArgs const & args)
    {
        m_thermometer.AdjustTemperature(1.f);
        ...
    }
    ...
};

Jedes Mal, wenn Sie auf das Fenster klicken, erhöhen Sie die Temperatur des Thermometerobjekts. Sie können Haltepunkte festlegen, wenn Sie den Code schrittweise durchbrechen möchten, um zu bestätigen, dass die Anwendung tatsächlich die Windows Runtime-Komponente aufruft.

Nächste Schritte

Um Ihrer C++/WinRT Windows Runtime-Komponente noch mehr Funktionen oder neue Windows Runtime-Typen hinzuzufügen, können Sie den oben gezeigten Mustern folgen. Verwenden Sie zunächst IDL, um die Funktionalität zu definieren, die Sie verfügbar machen möchten. Erstellen Sie dann das Projekt in Visual Studio, um eine Stubimplementierung zu generieren. Schließen Sie dann die Implementierung nach Besendung ab. Alle Methoden, Eigenschaften und Ereignisse, die Sie in IDL definieren, sind für die Anwendung sichtbar, die Ihre Windows Runtime-Komponente verwendet. Weitere Informationen zu IDL finden Sie unter Einführung in Microsoft Interface Definition Language 3.0.

Ein Beispiel zum Hinzufügen eines Ereignisses zu Ihrer Windows Runtime-Komponente finden Sie unter Erstellen von Ereignissen in C++/WinRT.

Problembehandlung

Symptom Problembehandlung
Wenn in einer C++/WinRT-App eine C#-Windows Runtime-Komponente verwendet wird, die XAML verwendet, erzeugt der Compiler einen Fehler in der Form "MyNamespace_XamlTypeInfo": ist kein Member von"winrt::MyNamespace"– wobei MyNamespace der Name des Namespace der Windows Runtime-Komponente ist. Fügen pch.h Sie in der verwendenden C++/WinRT-App hinzu, und ersetzen Sie dabei #include <winrt/MyNamespace.MyNamespace_XamlTypeInfo.h>pch.h entsprechend.