Windows-Runtime-Komponenten mit C++/WinRTWindows Runtime components with C++/WinRT

In diesem Thema wird gezeigt, wie C++/WinRT verwendet wird, um eine Windows-Runtime Komponente zu erstellen und zu nutzen, — die von einer universellen Windows-app aufgerufen werden kann, die mit einer beliebigen Windows-Runtime Sprache erstellt wurde.This topic shows how to use C++/WinRT to create and consume a Windows Runtime component—a component that's callable from a Universal Windows app built using any Windows Runtime language.

Es gibt verschiedene Gründe für das Entwickeln einer Windows-Runtime Komponente in C++/WinRT.There are several reasons for building a Windows Runtime component in C++/WinRT.

  • Um die Leistungsvorteile von C++ in komplexen oder rechenintensiven Vorgängen zu nutzen.To enjoy the performance advantage of C++ in complex or computationally intensive operations.
  • Zum wieder verwenden von Standard-C++-Code, der bereits geschrieben und getestet wurde.To reuse standard C++ code that's already written and tested.
  • Zum verfügbar machen von Win32-Funktionen für eine in geschriebene universelle Windows-Plattform (UWP)-app, z. b. c#.To expose Win32 functionality to a Universal Windows Platform (UWP) app written in, for example, C#.

Wenn Sie die C++/WinRT-Komponente erstellen, können Sie im allgemeinen Typen aus der C++-Standardbibliothek und integrierte Typen verwenden, außer an der Grenze der Anwendungs Binärschnittstelle (ABI), an die Sie Daten an den Code in einem anderen .winmd Paket übergeben.In general, when you author your C++/WinRT component, you can use types from the standard C++ library, and built-in types, except at the application binary interface (ABI) boundary where you're passing data to and from code in another .winmd package. Verwenden Sie in der ABI Windows-Runtime Typen.At the ABI, use Windows Runtime types. Verwenden Sie außerdem im C++/WinRT-Code Typen wie Delegat und Ereignis, um Ereignisse zu implementieren, die von der Komponente ausgelöst und in einer anderen Sprache behandelt werden können.In addition, in your C++/WinRT code, use types such as delegate and event to implement events that can be raised from your component and handled in another language. Weitere Informationen zu C++/WinRT. finden Sie unter C++/WinRT .See C++/WinRT for more info about C++/WinRT.

Im restlichen Teil dieses Themas erfahren Sie, wie Sie eine Windows-Runtime Komponente in C++/WinRT erstellen und dann in einer Anwendung verwenden.The remainder of this topic walks you through how to author a Windows Runtime component in C++/WinRT, and then how to consume it from an application.

Die Windows-Runtime Komponente, die Sie in diesem Thema erstellen, enthält eine Lauf Zeit Klasse, die ein Thermometer darstellt.The Windows Runtime component that you'll build in this topic contains a runtime class representing a thermometer. Außerdem wird in diesem Thema eine Core-App veranschaulicht, die die Thermometer-Lauf Zeit Klasse nutzt und eine Funktion aufruft, mit der die Temperatur angepasst wird.The topic also demonstrates a Core App that consumes the thermometer runtime class, and calls a function to adjust the temperature.

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).For info about installing and using the C++/WinRT Visual Studio Extension (VSIX) and the NuGet package (which together provide project template and build support), see Visual Studio support for C++/WinRT.

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.For essential concepts and terms that support your understanding of how to consume and author runtime classes with C++/WinRT, see Consume APIs with C++/WinRT and Author APIs with C++/WinRT.

Erstellen einer Windows-Runtime Komponente (thermometerwrc)Create a Windows Runtime component (ThermometerWRC)

Erstelle zunächst ein neues Projekt in Microsoft Visual Studio.Begin by creating a new project in Microsoft Visual Studio. Erstellen Sie ein Windows-Runtime Component-Projekt (C++/WinRT) , und nennen Sie es thermometerwrc (für "Thermometer Windows-Runtime Component").Create a Windows Runtime Component (C++/WinRT) project, and name it ThermometerWRC (for "thermometer Windows Runtime component"). Stellen Sie sicher, dass Platzieren Sie die Projektmappe und das Projekt im selben Verzeichnis deaktiviert ist.Make sure that Place solution and project in the same directory is unchecked. Die neueste allgemein verfügbare Version von Windows SDK (d. h. keine Vorschauversion).Target the latest generally-available (that is, not preview) version of the Windows SDK. Wenn Sie das Projekt thermometerwrc benennen, erhalten Sie die einfachste Möglichkeit, die restlichen Schritte in diesem Thema auszuführen.Naming the project ThermometerWRC will give you the easiest experience with the rest of the steps in this topic.

Führen Sie noch keinen Buildvorgang für das Projekt aus.Don't build the project yet.

Das neu erstellte Projekt enthält eine Datei namens Class.idl.The newly-created project contains a file named 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.)In Solution Explorer, rename that file Thermometer.idl (renaming the .idl file automatically renames the dependent .h and .cpp files, too). Ersetze den Inhalt von Thermometer.idl durch das folgende Listing:Replace the contents of Thermometer.idl with the listing below.

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

Speichern Sie die Datei.Save the file. Das Projekt wird im Moment nicht bis zum Abschluss erstellt, aber das Erstellen von jetzt ist eine sinnvolle Sache, da es die Quell Code Dateien generiert, in denen Sie die thermometerlaufzeitklasse implementieren.The project won't build to completion at the moment, but building now is a useful thing to do because it generates the source code files in which you'll implement the Thermometer runtime class. 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.)So go ahead and build now (the build errors you can expect to see at this stage have to do with Class.h and Class.g.h not being found).

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.During the build process, the midl.exe tool is run to create your component's Windows Runtime metadata file (which is \ThermometerWRC\Debug\ThermometerWRC\ThermometerWRC.winmd). 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.Then, the cppwinrt.exe tool is run (with the -component option) to generate source code files to support you in authoring your component. Diese Dateien enthalten stubvorgänge, um den Einstieg in die Implementierung der Thermometer -Lauf Zeit Klasse zu erleichtern, die Sie in ihrer IDL deklariert habenThese files include stubs to get you started implementing the Thermometer runtime class that you declared in your IDL. Diese Stubs sind \ThermometerWRC\ThermometerWRC\Generated Files\sources\Thermometer.h und Thermometer.cpp.Those stubs are \ThermometerWRC\ThermometerWRC\Generated Files\sources\Thermometer.h and Thermometer.cpp.

Klicke mit der rechten Maustaste auf den Projektknoten, und klicke auf Ordner in Datei-Explorer öffnen.Right-click the project node and click Open Folder in File Explorer. Dadurch wird der Projektordner im Datei-Explorer geöffnet.This opens the project folder in File Explorer. 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.There, copy the stub files Thermometer.h and Thermometer.cpp from the folder \ThermometerWRC\ThermometerWRC\Generated Files\sources\ and into the folder that contains your project files, which is \ThermometerWRC\ThermometerWRC\, and replace the files in the destination. Als Nächstes öffnen wir Thermometer.h und Thermometer.cpp und implementieren unsere Laufzeitklasse.Now, let's open Thermometer.h and Thermometer.cpp and implement our runtime class. Thermometer.hFügen Sie in der-Implementierung (nicht der Factory-Implementierung) des Thermometerseinen neuen privaten Member hinzu.In Thermometer.h, add a new private member to the implementation (not the factory implementation) of Thermometer.

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

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

Implementieren Sie in Thermometer.cpp die Methode "- Temperatur ", wie in der folgenden Liste gezeigt.In Thermometer.cpp, implement the AdjustTemperature method as shown in the listing below.

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

Sie müssen auch static_assert aus beiden Dateien löschen.You'll also need to delete the static_assert from both files.

Sollte die Erstellung aufgrund von Warnungen nicht möglich sein, behebe entweder die Ursachen, oder lege die Projekteigenschaft C/C++ > Allgemein > Warnungen als Fehler behandeln auf Nein (/WX-) fest, und erstelle das Projekt erneut.If any warnings prevent you from building, then either resolve them or set the project property C/C++ > General > Treat Warnings As Errors to No (/WX-), and build the project again.

Erstellen Sie eine Core-app (thermometercoreapp), um die Windows-Runtime Komponente zu testen.Create a Core App (ThermometerCoreApp) to test the Windows Runtime component

Erstellen Sie nun ein neues Projekt (entweder in Ihrer thermometerwrc -Projekt Mappe oder in einer neuen).Now create a new project (either in your ThermometerWRC solution, or in a new one). Erstellen Sie ein Core-App-Projekt (C++/WinRT) , und nennen Sie es thermometercoreapp.Create a Core App (C++/WinRT) project, and name it ThermometerCoreApp. Legen Sie thermometercoreapp als Startprojekt fest, wenn sich die beiden Projekte in derselben Projekt Mappe befinden.Set ThermometerCoreApp as the startup project if the two projects are in the same solution.

Hinweis

Wie bereits erwähnt, wird die Windows-Runtime Metadatendatei für die Windows-Runtime Komponente (deren Projekt Sie " thermometerwrc" genannt haben) im Ordner erstellt \ThermometerWRC\Debug\ThermometerWRC\ .As mentioned earlier, the Windows Runtime metadata file for your Windows Runtime component (whose project you named ThermometerWRC) is created in the folder \ThermometerWRC\Debug\ThermometerWRC\. 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.The first segment of that path is the name of the folder that contains your solution file; the next segment is the subdirectory of that named Debug; and the last segment is the subdirectory of that named for your Windows Runtime component. Wenn Sie Ihr Projekt nicht mit dem Namen thermometerwrcbenennen, befindet sich Ihre Metadatendatei im Ordner \<YourProjectName>\Debug\<YourProjectName>\ .If you didn't name your project ThermometerWRC, then your metadata file will be in the folder \<YourProjectName>\Debug\<YourProjectName>\.

Fügen Sie nun in Ihrem Core-App-Projekt (thermometercoreapp) einen Verweis hinzu, und navigieren Sie zu \ThermometerWRC\Debug\ThermometerWRC\ThermometerWRC.winmd (oder fügen Sie einen Projekt-zu-Projekt-Verweis hinzu, wenn sich die beiden Projekte in derselben Projekt Mappe befinden).Now, in your Core App project (ThermometerCoreApp), add a reference, and browse to \ThermometerWRC\Debug\ThermometerWRC\ThermometerWRC.winmd (or add a project-to-project reference, if the two projects are in the same solution). Klicke auf Hinzufügen und anschließend auf OK.Click Add, and then OK. Erstellen Sie nun thermometercoreapp.Now build ThermometerCoreApp. Im unwahrscheinlichen Fall, dass eine Fehlermeldung angezeigt wird, dass die Nutz Last Datei readme.txt nicht vorhanden ist, schließen Sie diese Datei aus dem Projekt Windows-Runtime Komponente aus, erstellen Sie Sie neu, und erstellen Sie dann thermometercoreappneuIn the unlikely event that you see an error that the payload file readme.txt doesn't exist, exclude that file from the Windows Runtime component project, rebuild it, then rebuild ThermometerCoreApp.

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.During the build process, the cppwinrt.exe tool is run to process the referenced .winmd file into source code files containing projected types to support you in consuming your component. Der Header für die projizierten Typen für die Laufzeitklassen deiner Komponente (ThermometerWRC.h) wird im Ordner \ThermometerCoreApp\ThermometerCoreApp\Generated Files\winrt\ generiert.The header for the projected types for your component's runtime classes—named ThermometerWRC.h—is generated into the folder \ThermometerCoreApp\ThermometerCoreApp\Generated Files\winrt\.

Schließe diesen Header in App.cpp ein.Include that header in App.cpp.

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

App.cppFügen Sie außerdem in den folgenden Code hinzu, um ein thermometerobjekt (mithilfe des Standardkonstruktors des projizierten Typs) zu instanziieren und eine Methode für das thermometerobjekt aufzurufen.Also in App.cpp, add the following code to instantiate a Thermometer object (using the projected type's default constructor), and call a method on the thermometer object.

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.Each time you click the window, you increment the thermometer object's temperature. Sie können Haltepunkte festlegen, wenn Sie den Code schrittweise durchlaufen möchten, um zu bestätigen, dass die Anwendung tatsächlich die Windows-Runtime Komponente aufruft.You can set breakpoints if you want to step through the code to confirm that the application really is calling into the Windows Runtime component.

Nächste SchritteNext steps

Wenn Sie Ihrer C++/WinRT Windows-Runtime-Komponente noch mehr Funktionalität oder neue Windows-Runtime Typen hinzufügen möchten, können Sie die oben gezeigten Muster befolgen.To add even more functionality, or new Windows Runtime types, to your C++/WinRT Windows Runtime component, you can follow the same patterns shown above. Verwenden Sie zuerst IDL, um die Funktionalität zu definieren, die Sie verfügbar machen möchten.First, use IDL to define the functionality you want to expose. Erstellen Sie dann das Projekt in Visual Studio, um eine Stub-Implementierung zu generieren.Then build the project in Visual Studio to generate a stub implementation. Und schließen Sie die Implementierung dann entsprechend ab.And then complete the implementation as appropriate. Alle Methoden, Eigenschaften und Ereignisse, die Sie in IDL definieren, sind für die Anwendung sichtbar, die Ihre Windows-Runtime Komponente verwendet.Any methods, properties, and events that you define in IDL are visible to the application that consumes your Windows Runtime Component. Weitere Informationen zu IDL finden Sie unter Einführung in Microsoft Interface Definition Language 3,0.For more info about IDL, see Introduction to Microsoft Interface Definition Language 3.0.

Ein Beispiel für das Hinzufügen eines Ereignisses zur Windows-Runtime Komponente finden Sie unter Verfassen von Ereignissen in C++/WinRT.For an example of how to add an event to your Windows Runtime Component, see Author events in C++/WinRT.

ProblembehandlungTroubleshooting

SymptomSymptom ProblembehandlungRemedy
Wenn in einer C++/WinRT-App eine C#-Komponente für Windows-Runtime, die XAML verwendet, verarbeitet wird, erzeugt der Compiler einen Fehler der Form „ 'MyNamespace_XamlTypeInfo': is not a member of 'winrt::MyNamespace' “, wobei MyNamespace der Name des Namespace der Windows Runtime-Komponente ist.In a C++/WinRT app, when consuming a C# Windows Runtime component that uses XAML, the compiler produces an error of the form "'MyNamespace_XamlTypeInfo': is not a member of 'winrt::MyNamespace'"—where MyNamespace is the name of the Windows Runtime component's namespace. Fügen Sie in pch.h in der verarbeitenden C++/WinRT-App #include <winrt/MyNamespace.MyNamespace_XamlTypeInfo.h> hinzu, und ersetzen Sie MyNamespace entsprechend.In pch.h in the consuming C++/WinRT app, add #include <winrt/MyNamespace.MyNamespace_XamlTypeInfo.h>—replacing MyNamespace as appropriate.