Anleitung – Erstellen einer C#/WinRT-Komponente und Verwenden aus C++/WinRT

Mit C#/WinRT können Entwickler .NET verwenden, um ihre eigenen Windows Runtime-Komponenten in C# mithilfe eines Klassenbibliothek-Projekts zu erstellen. Erstellte Komponenten können in nativen Desktopanwendungen als Paketverweis oder als Projektreferenz mit einigen Anpassungen eingesetzt werden.

In dieser exemplarischen Vorgehensweise wird veranschaulicht, wie Sie eine einfache Windows Runtime Komponente mit C#/WinRT erstellen, die Komponente als NuGet-Paket verteilen und die Komponente aus einer C++/WinRT-Konsolenanwendung nutzen. Das vollständige Beispiel, das den Code für diesen Artikel bereitstellt, finden Sie im C#/WinRT-Erstellungsbeispiel. Weitere Informationen zur Erstellung finden Sie unter Authoring components.

Eine exemplarische Vorgehensweise zum Erstellen von WinUI 3-Steuerelementen mit C#/WinRT speziell für die Verwendung in Windows App SDK Anwendungen finden Sie im Artikel Walkthrough: Erstellen einer C#-Komponente mit WinUI-Steuerelementen und Verwenden von einer C++-Windows App SDK Anwendung

Voraussetzungen

Für diese Schritt-für-Schritt-Anleitung sind die folgenden Werkzeuge und Komponenten erforderlich:

• Visual Studio 2022
• .NET 6.0 SDK oder höher
• C++/WinRT VSIX für C++/WinRT-project-Vorlagen

Erstellen einer einfachen Windows Runtime Komponente mit C#/WinRT

Beginnen Sie mit dem Erstellen einer neuen project in Visual Studio. Wählen Sie die Projektvorlage Class Library aus, und benennen Sie das Projekt AuthoringDemo. Sie müssen die folgenden Änderungen und Ergänzungen am Projekt vornehmen.

1. Aktualisieren Sie das TargetFramework in der Datei AuthoringDemo.csproj und fügen Sie dem PropertyGroupdie folgenden Elemente hinzu:

   <PropertyGroup>
       <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
       <Platforms>x64</Platforms>
   </PropertyGroup>
   

   Um auf Windows Runtime-Typen zuzugreifen, müssen Sie eine bestimmte Windows SDK-Version im TFM festlegen. Weitere Informationen zur unterstützten Version finden Sie unter .NET 6 und höher: Verwenden Sie die TFM-Option.

2. Installieren Sie das Microsoft.Windows.CsWinRT NuGet-Paket in Ihrem project.

   a) Klicken Sie in Solution Explorer mit der rechten Maustaste auf den Projektknoten, und wählen Sie Manage NuGet Packages aus.

   b. Suchen Sie nach dem Microsoft.Windows.CsWinRT NuGet-Paket, und installieren Sie die neueste Version. In dieser Anleitung wird C#/WinRT Version 1.4.1 verwendet.

3. Fügen Sie ein neues PropertyGroup Element hinzu, das die CsWinRTComponent Eigenschaft festlegt. Dadurch wird angegeben, dass Ihr Projekt eine Windows-Runtime-Komponente ist, sodass beim Erstellen des Projekts eine .winmd-Datei generiert wird.

   <PropertyGroup>   
       <CsWinRTComponent>true</CsWinRTComponent>
   </PropertyGroup>
   

   Eine vollständige Liste der C#/WinRT-project Eigenschaften finden Sie in der C#/WinRT NuGet-Dokumentation.

4. Sie können Ihre Laufzeitklassen mithilfe von Bibliotheks- .cs Klassendateien erstellen. Klicken Sie mit der rechten Maustaste auf die Class1.cs Datei und benennen Sie sie in Example.cs um. Fügen Sie dieser Datei den folgenden Code hinzu, der der Laufzeitklasse eine öffentliche Eigenschaft und Methode hinzufügt. Denken Sie daran, alle Klassen zu markieren, die Sie in der Laufzeitkomponente publicals verfügbar machen möchten.

   namespace AuthoringDemo
   {
       public sealed class Example
       {
           public int SampleProperty { get; set; }
   
           public static string SayHello()
           {
               return "Hello from your C# WinRT component";
           }
       }
   }
   

5. Jetzt können Sie das Projekt builden, um die Datei .winmd für Ihre Komponente zu generieren. Klicken Sie mit der rechten Maustaste auf die project in Solution Explorer, und klicken Sie auf Build. Im Buildoutput-Ordner wird die generierte AuthoringDemo.winmd-Datei angezeigt.

Generieren eines NuGet-Pakets für die Komponente

Die meisten Entwickler möchten ihre Windows Runtime Komponente als NuGet-Paket verteilen und freigeben. Eine weitere Möglichkeit besteht darin, die Komponente als Projektreferenz zu nutzen. Die folgenden Schritte veranschaulichen das Verpacken der AuthoringDemo--Komponente. Wenn Sie das Paket generieren, konfiguriert C#/WinRT die Komponente und Host-Assemblys im Paket, um die Verwendung durch native Anwendungen zu ermöglichen.

Es gibt mehrere Möglichkeiten zum Generieren des NuGet-Pakets:

• Wenn Sie jedes Mal, wenn Sie das project erstellen, ein NuGet-Paket generieren möchten, fügen Sie der Datei AuthoringDemo project die folgende Eigenschaft hinzu, und erstellen Sie dann die project neu.

  <PropertyGroup>
      <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
  </PropertyGroup>
  

• Alternativ können Sie ein NuGet-Paket generieren, indem Sie mit der rechten Maustaste auf das AuthoringDemo project in Solution Explorer klicken und Pack auswählen.

Beim Erstellen des Pakets sollte das Fenster Build angeben, dass das NuGet-Paket AuthoringDemo.1.0.0.nupkg erfolgreich erstellt wurde. Weitere Informationen zu NuGet-Paketeigenschaften mit der .NET CLI finden Sie unter Create a package using the dotnet CLI.

Nutzen der Komponente aus einer C++/WinRT-App

Mit C#/WinRT erstellte Windows Runtime-Komponenten können von jeder beliebigen Windows Runtime (WinRT)-kompatiblen Sprache verwendet werden. Die folgenden Schritte veranschaulichen, wie Sie die erstellte Komponente oben in einer C++/WinRT-Konsolenanwendung aufrufen.

1. Fügen Sie Ihrer Lösung eine neue C++/WinRT Console Application project hinzu. Beachten Sie, dass dieses Projekt auch Teil einer anderen Lösung sein kann, wenn Sie dies wünschen.

   a) Klicken Sie in Solution Explorer mit der rechten Maustaste auf den Lösungsknoten, und klicken Sie auf Add ->Neue Project.

   b. Suchen Sie im Dialogfeld Neues Projekt nach der Vorlage C++/WinRT Console Application. Wählen Sie die Vorlage aus, und klicken Sie auf Weiter.

   Abschnitt c. Benennen Sie den neuen project CppConsoleApp, und klicken Sie auf Create.

2. Fügen Sie einen Verweis auf die AuthoringDemo-Komponente hinzu, entweder als NuGet-Paket oder als Projektverweis.

   • Option 1 (Paketreferenz):

     a) Klicken Sie mit der rechten Maustaste auf die CppConsoleApp project und wählen Sie Manage NuGet-Pakete aus. Möglicherweise müssen Sie Ihre Paketquellen konfigurieren, um einen Verweis auf das AuthoringDemo NuGet-Paket hinzuzufügen. Um dies zu tun, klicken Sie auf das Symbol Settings im NuGet-Paket-Manager und fügen Sie eine Paketquelle zum entsprechenden Pfad hinzu.

     

     b. Nachdem Sie Ihre Paketquellen konfiguriert haben, suchen Sie nach dem AuthoringDemo--Paket und klicken Sie auf Installieren.

     

   • Option 2 (Projektreferenz):

     a) Klicken Sie mit der rechten Maustaste auf die CppConsoleApp project, und wählen Sie Add ->Reference aus. Fügen Sie unter dem Knoten Projects einen Verweis auf den AuthoringDemo project hinzu.

3. Um die Komponente zu hosten, müssen Sie eine Manifestdatei für aktivierbare Klassenregistrierungen hinzufügen. Weitere Informationen zum Hosten verwalteter Komponenten finden Sie unter Managed component hosting.

   a) Um die Manifestdatei hinzuzufügen, klicken Sie erneut mit der rechten Maustaste auf das project, und wählen Sie Add -> Neues Element aus. Suchen Sie nach der Textdatei-Vorlage und nennen Sie sie CppConsoleApp.exe.manifest. Fügen Sie den folgenden Inhalt ein, der die Laufzeitklassen mithilfe von aktivierbaren Klassenregistrierungseinträgen angibt:

   <?xml version="1.0" encoding="utf-8"?>
   <assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
       <assemblyIdentity version="1.0.0.0" name="CppConsoleApp"/>
       <file name="WinRT.Host.dll">
           <activatableClass
               name="AuthoringDemo.Example"
               threadingModel="both"
               xmlns="urn:schemas-microsoft-com:winrt.v1" />
       </file>
   </assembly>
   

   Die Anwendungsmanifestdatei ist für Apps erforderlich, die nicht verpackt sind. Für verpackte Apps muss der App-Nutzer die aktivierbaren Klassen in der Package.appxmanifest Paketmanifestdatei registrieren, wie im Walkthrough: Erstellen einer C#-Komponente mit WinUI-Steuerelementen und Einbindung von einer C++-Windows App SDK-Anwendung erläutert.

   b. Ändern Sie das Projekt so, dass die Manifestdatei in die Ausgabe aufgenommen wird, wenn das Projekt bereitgestellt wird. Klicken Sie auf die CppConsoleApp.exe.manifest Datei in Solution Explorer und legen Sie die Eigenschaft Content auf True fest. Hier ist ein Beispiel dafür, wie das aussieht.

   

4. Öffnen Sie pch.h unter den Headerdateien des project, und fügen Sie die folgende Codezeile hinzu, um die Komponente einzuschließen.

   #include <winrt/AuthoringDemo.h>
   

5. Öffnen Sie main.cpp unter den Quelldateien des project, und ersetzen Sie sie durch den folgenden Inhalt.

   #include "pch.h"
   #include "iostream"
   
   using namespace winrt;
   using namespace Windows::Foundation;
   
   int main()
   {
       init_apartment();
   
       AuthoringDemo::Example ex;
       ex.SampleProperty(42);
       std::wcout << ex.SampleProperty() << std::endl;
       std::wcout << ex.SayHello().c_str() << std::endl;
   }
   

6. Erstellen Und ausführen Sie die CppConsoleApp project. Nun sollte die Ausgabe unten angezeigt werden.

   

Zugehörige Themen

• Sample-Code
• Erstellungskomponenten
• Verwaltetes Komponenten-Hosting