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 Klassenbibliotheksprojekts 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 oder höher
• .NET 8.0 SDK (LTS) 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 eines neuen Projekts 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 Projekt.

   a) Klicken Sie in Projektmappen-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.

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 .winmdDatei 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 das Projekt in Projektmappen-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 Projekt in Projektmappen-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

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

Hinweis

Das Verwenden einer C#/WinRT-Komponente aus C#/.NET-Apps wird sowohl von Paketreferenzen als auch von Projektreferenzen unterstützt. Dieses Szenario entspricht der Verwendung einer normalen C#-Klassenbibliothek und erfordert in den meisten Fällen keine WinRT-Aktivierung. Seit C#/WinRT 1.3.5 erfordern Projektverweise für C#-Consumers .NET 6 oder höher.

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 Projektmappen-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. Klicken Sie hierzu auf das Symbol Settings in NuGet Paket-Manager, und fügen Sie dem entsprechenden Pfad eine Paketquelle 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. Bei verpackten Apps muss der App-Consumer die aktivierbaren Klassen in der Package.appxmanifest-Paketmanifestdatei registrieren, wie in Walkthrough erläutert: Erstellen einer C#-Komponente mit WinUI-Steuerelementen und Nutzen aus einer C++-Windows App SDK Anwendung.

   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 Projektmappen-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