Exemplarische Vorgehensweise: Erstellen einer C#/WinRT-Komponente und deren Verwendung aus C++/WinRT

C#/WinRT ermöglicht .NET-Entwickler*innen, ihre eigenen Komponenten für Windows-Runtime in C# mithilfe eines Klassenbibliotheksprojekts zu erstellen. Die erstellten Komponenten können in nativen Desktopanwendungen als Paketverweis oder als Projektverweis mit wenigen Änderungen genutzt 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 enthält, finden Sie im C#/WinRT-Erstellungsbeispiel. Weitere Informationen zur Erstellung finden Sie unter Erstellen von Komponenten.

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

Voraussetzungen

Für diese exemplarische Vorgehensweise werden folgende Tools und Komponenten benötigt:

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

Erstellen einer einfachen Windows-Runtime-Komponente mit C#/WinRT

Beginnen Sie mit dem Erstellen eines neues Projekts in Visual Studio. Wählen Sie die Projektvorlage Klassenbibliothek aus, und nennen Sie das Projekt AuthoringDemo. Sie müssen die folgenden Ergänzungen und Änderungen am Projekt vornehmen:

1. Aktualisieren Sie das TargetFramework in der Datei AuthoringDemo.csproj, und fügen Sie der PropertyGroup die folgenden Elemente hinzu:

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

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

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

   a. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektknoten, und wählen Sie NuGet-Pakete verwalten aus.

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

3. Fügen Sie ein neues PropertyGroup-Element hinzu, das die CsWinRTComponent-Eigenschaft festlegt. Diese gibt an, dass Ihr Projekt eine Komponente für Windows-Runtime ist, sodass eine .winmd-Datei generiert wird, wenn Sie das Projekt erstellen.

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

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

4. Sie können Ihre Runtimeklassen mithilfe von Bibliotheksklassendateien (.cs) erstellen. Klicken Sie mit der rechten Maustaste auf die Datei Class1.cs, und geben Sie ihr den Namen Example.cs. 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 Runtimekomponente als public 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. Sie können das Projekt jetzt erstellen, um die .winmd-Datei für Ihre Komponente zu generieren. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie Erstellen aus. Die generierte Datei AuthoringDemo.winmd wird im Buildausgabeordner angezeigt.

Generieren eines NuGet-Pakets für die Komponente

Die meisten Entwickler*innen möchten ihre Komponente für Windows-Runtime als NuGet-Paket verteilen und freigeben. Eine weitere Möglichkeit besteht darin, die Komponente als Projektverweis zu nutzen. Die folgenden Schritte veranschaulichen, wie die AuthoringDemo-Komponente gepackt wird. Wenn Sie das Paket generieren, konfiguriert C#/WinRT die Komponenten- und Hostingassemblys im Paket für die Verwendung in nativen Anwendungen.

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

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

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

• Alternativ können Sie ein NuGet-Paket generieren, indem Sie mit der rechten Maustaste auf das AuthoringDemo-Projekt im Projektmappen-Explorer klicken und Packen auswählen.

Wenn Sie das Paket erstellen, sollte das Fenster Erstellen anzeigen, dass das NuGet-Paket AuthoringDemo.1.0.0.nupkg erfolgreich erstellt wurde. Weitere Informationen zu NuGet-Paketeigenschaften mit der .NET CLI finden Sie unter Erstellen eines Pakets mithilfe der .NET CLI.

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

Mit C#/WinRT erstellte Komponenten für Windows-Runtime können mit jeder WinRT-kompatiblen Programmiersprache genutzt werden. Die folgenden Schritte veranschaulichen, wie Sie die oben erstellte Komponente in einer nativen C++/WinRT-Konsolenanwendung aufrufen.

Hinweis

Das Verwenden einer C#/WinRT-Komponente aus C#/.NET-Apps wird sowohl vom Paketverweis als auch vom Projektverweis unterstützt. Dieses Szenario entspricht der Nutzung einer normalen C#-Klassenbibliothek und beinhaltet in den meisten Fällen keine WinRT-Aktivierung. Ab C#/WinRT 1.3.5 erfordern Projektverweise für C#-Consumer .NET 6.

1. Fügen Sie Ihrer Projektmappe ein neues C++/WinRT-Konsolenanwendung-Projekt hinzu. Beachten Sie, dass dieses Projekt auch Teil einer anderen Projektmappe sein kann, wenn Sie dies entscheiden.

   a. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Ihren Projektmappenknoten, und klicken Sie auf Hinzufügen ->Neues Projekt.

   b. Suchen Sie im Dialogfeld Neues Projekt hinzufügen nach der Projektvorlage C++/WinRT-Konsolenanwendung. Wählen Sie die Vorlage aus und klicken Sie auf Weiter.

   c. Nennen Sie das neue Projekt CppConsoleApp, und klicken Sie auf Erstellen.

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

   • Option 1 (Paketverweis):

     a. Klicken Sie mit der rechten Maustaste auf das CppConsoleApp-Projekt, und wählen Sie NuGet-Pakete verwalten aus. Möglicherweise müssen Sie Ihre Paketquellen so konfigurieren, dass sie einen Verweis auf das AuthoringDemo-NuGet-Paket hinzufügen. Klicken Sie hierzu im NuGet-Paket-Manager auf das Symbol Einstellungen, und fügen Sie dem entsprechenden Pfad eine Paketquelle hinzu.

     

     b. Suchen Sie nach dem Konfigurieren Ihrer Paketquellen nach dem AuthoringDemo-Paket, und klicken Sie auf Installieren.

     

   • Option 2 (Projektverweis):

     a. Klicken Sie dazu mit der rechten Maustaste auf das CppConsoleApp-Projekt, und wählen Sie Hinzufügen ->Verweis aus. Fügen Sie unter dem Knoten Projekte einen Verweis auf das Projekt AuthoringDemo 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 Hosten verwalteter Komponenten.

   a. Klicken Sie zum Hinzufügen der Manifestdatei erneut mit der rechten Maustaste auf das Projekt, und wählen Sie Hinzufügen -> Neues Element aus. Suchen Sie nach der Vorlage Text File, und nennen Sie sie CppConsoleApp.exe.manifest. Fügen Sie den folgenden Inhalt ein, der die Runtimeklassen 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 gepackt sind. Für gepackte Apps muss der App-Consumer die aktivierbaren Klassen in der Paketmanifestdatei Package.appxmanifest registrieren, wie in Exemplarischer Vorgehensweise: Erstellen einer C#-Komponente mit WinUI 3-Steuerelementen und verwenden dieser in einer C++-Windows App SDK-Anwendung erläutert.

   b. Ändern Sie das Projekt so, dass die Manifestdatei bei der Bereitstellung des Projekts in die Ausgabe aufgenommen wird. Klicken Sie im Projektmappen-Explorer auf die Datei CppConsoleApp.exe.manifest, und legen Sie die Eigenschaft Content (Inhalt) auf True fest. Hier sehen Sie ein Beispiel, wie dies aussehen sollte.

   

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

   #include <winrt/AuthoringDemo.h>
   

5. Öffnen Sie unter den Quelldateien des Projekts main.cpp, 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 Sie das Projekt CppConsoleApp, und führen Sie es aus. Nun sollte die folgende Ausgabe angezeigt werden.

   

Zugehörige Themen

• Beispielcode
• Erstellen von Komponenten
• Hosten verwalteter Komponenten