Freigeben über

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

C#/WinRT ermöglicht es Entwicklern, die .NET nutzen, eigene Windows-Runtime-Komponenten in C# mithilfe eines Klassenbibliotheksprojekts zu erstellen. Entwickelte Komponenten können in nativen Desktopanwendungen als Paketreferenz oder als Projektreferenz nach einigen Anpassungen genutzt werden.

In dieser exemplarischen Vorgehensweise wird veranschaulicht, wie Sie eine einfache Komponente für Windows-Runtime 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 zum Erstellen finden Sie unter Erstellungskomponenten.

Eine beispielhafte Vorgehensweise zum Erstellen von WinUI-Steuerelementen mit C#/WinRT speziell für die Verwendung in Windows App SDK-Anwendungen finden Sie im Artikel Schritt-für-Schritt-Anleitung: Erstellen Sie eine C#-Komponente mit WinUI 3-Steuerelementen und verwenden Sie sie in einer C++ Windows App SDK-Anwendung

Voraussetzungen

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

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

Beginnen Sie mit dem Erstellen eines neuen 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 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 im Solution Explorer mit der rechten Maustaste auf den Projektknoten, und wählen Sie NuGet-Pakete verwaltenaus.

    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 Komponente für Windows-Runtime ist, sodass beim Erstellen des Projekts eine .winmd Datei generiert wird.

    <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 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. Sie können nun das Projekt erstellen, um die .winmd Datei für Ihre Komponente zu generieren. Klicken Sie mit der rechten Maustaste auf das Projekt im 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 Projektverweis 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 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 im Projektmappen- Explorer mit der rechten Maustaste auf das AuthoringDemo--Projekt 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 Erstellen eines Pakets mithilfe der dotnet CLI-.

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

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

Hinweis

Die Verwendung 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. Ab der Version C#/WinRT 1.3.5 benötigen Projektverweise für C#-Anwender .NET 6.

  1. Fügen Sie Ihrer Lösung ein neues C++/WinRT-Konsolenanwendungsprojekt hinzu. Beachten Sie, dass dieses Projekt auch Teil einer anderen Lösung sein kann, wenn Sie dies auswählen.

    a) Klicken Sie im Projektmappen-Explorermit der rechten Maustaste auf den Projektmappenknoten, und klicken Sie auf Hinzufügen ->Neues Projekt.

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

    Abschnitt c. Benennen 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 (Paketreferenz):

      a) Klicken Sie mit der rechten Maustaste auf das CppConsoleApp- Projekt, und wählen Sie NuGet-Pakete verwaltenaus. 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 Einstellungen im NuGet-Paket-Manager und fügen Sie dem entsprechenden Pfad eine Paketquelle hinzu.

      NuGet-Einstellungen

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

      NuGet-Paket installieren

    • Option 2 (Projekt-Referenz):

      a) Klicken Sie mit der rechten Maustaste auf das CppConsoleApp Projekt und wählen Sie Hinzufügen ->Verweisaus. 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 Hosting verwalteter Komponenten finden Sie unter Managed component hosting.

    a) Um die Manifestdatei hinzuzufügen, klicken Sie erneut mit der rechten Maustaste auf das Projekt, und wählen Sie "Hinzufügen –> 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 in Exemplarische Vorgehensweise erläutert: Erstellen einer C#-Komponente mit WinUI 3-Steuerelementen und Verwenden in einer C++-Windows App SDK-Anwendung.

    b. Ändern Sie das Projekt so, dass die Manifestdatei beim Bereitstellen des Projekts in die Ausgabe eingeschlossen wird. Klicken Sie im Projektmappen- Explorer auf die CppConsoleApp.exe.manifest-Datei, und legen Sie die Eigenschaft Content- auf Truefest. Hier ist ein Beispiel dafür, wie das aussieht.

    Inhalt bereitstellen

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

    #include <winrt/AuthoringDemo.h>

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

    C++/WinRT-Konsolenausgabe

  • Last updated on