Freigeben über

Anleitung: Erstellen einer C#-Komponente mit WinUI 3-Steuerelementen und deren Nutzung in einer C++/WinRT-App, die das Windows App SDK verwendet.

C#/WinRT bietet Unterstützung für die Erstellung Windows Runtime Komponenten, einschließlich benutzerdefinierter WinUI-Typen und benutzerdefinierter Steuerelemente. Diese Komponenten können von C#- oder C++/WinRT-Anwendungen genutzt werden, die die Windows App SDK verwenden. Wir empfehlen die Verwendung von C#/WinRT v1.6.4 oder höher, um Laufzeitkomponenten mit NuGet-Paketunterstützung zu erstellen.

Weitere Informationen zu den unterstützten Szenarien finden Sie unter Authoring C#/WinRT components in the C#/WinRT GitHub repo.

In dieser exemplarischen Vorgehensweise wird das Erstellen einer C#-Komponente mit einem benutzerdefinierten WinUI-Steuerelement und das Verwenden dieser Komponente aus einer C++/WinRT-App mithilfe der Windows App SDK project-Vorlagen veranschaulicht.

Voraussetzungen

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

Erstellen Sie Ihre C#/WinRT-Komponente mithilfe des Windows App SDK

  1. Erstellen Sie ein neues C#-Bibliotheksprojekt mithilfe der Vorlage Class Library (WinUI in Desktop), die vom Windows App SDK bereitgestellt wird. Für diese Anleitung haben wir das Bibliotheksprojekt WinUIComponentCs und die Lösung AuthoringWinUI benannt.

    Lassen Sie das Kontrollkästchen Solution und Projekt im selben Verzeichnis ablegen nicht ausgewählt (andernfalls wird der Ordner packages für die C++-Anwendung im vorherigen Abschnitt das C#-Bibliotheksprojekt beeinträchtigen).

    Dialogfeld

  2. Löschen Sie die Class1.cs Standardmäßig enthaltene Datei.

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

    i. Klicken Sie in Solution Explorer mit der rechten Maustaste auf den Knoten project, und wählen Sie Manage NuGet Packages aus.

    ii. Suchen Sie nach dem Microsoft.Windows.CsWinRT NuGet-Paket, und installieren Sie die neueste Version.

  4. Fügen Sie Ihrem Bibliothek-Projekt die folgenden Eigenschaften hinzu:

    <PropertyGroup>   
    <CsWinRTComponent>true</CsWinRTComponent>
</PropertyGroup>
    • Die eigenschaft CsWinRTComponent gibt an, dass ihr project eine Windows Runtime Komponente ist, sodass beim Erstellen des project eine .winmddatei generiert wird.

  5. Fügen Sie Ihrer Bibliothek ein benutzerdefiniertes Steuerelement oder ein Benutzersteuerelement hinzu. Klicken Sie hierzu in Visual Studio mit der rechten Maustaste auf Ihr Projekt, klicken Sie auf Add>Neues Element, und wählen Sie im linken Seitenbereich WinUI aus. Für diese exemplarische Vorgehensweise haben wir ein neues Benutzersteuerelement (WinUI) hinzugefügt und benannt NameReporter.xaml. Das NameReporter Benutzersteuerelement ermöglicht es einem Benutzer, einen Vor- und Nachnamen in das entsprechende TextBox--Steuerelement einzugeben und auf eine Schaltfläche zu klicken. Das Steuerelement zeigt dann ein Meldungsfeld mit dem Namen an, den der Benutzer eingegeben hat.

  6. Fügen Sie den folgenden Code in die NameReporter.xaml Datei ein:

    <UserControl
x:Class="WinUIComponentCs.NameReporter"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:local="using:WinUIComponentCs"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d">

    <StackPanel HorizontalAlignment="Center">
        <StackPanel.Resources>
            <Style x:Key="BasicTextStyle" TargetType="TextBlock" BasedOn="{StaticResource BodyTextBlockStyle}">
                <Setter Property="Margin" Value="10,10,10,10"/>
            </Style>
        </StackPanel.Resources>

        <TextBlock Text="Enter your name." Margin="0,0,0,10"/>
        <StackPanel Orientation="Horizontal" Margin="0,0,0,10">
            <TextBlock Style="{StaticResource BasicTextStyle}">
                First Name:
            </TextBlock>
            <TextBox Name="firstName" />
        </StackPanel>
        <StackPanel Orientation="Horizontal" Margin="0,0,0,10">
            <TextBlock Style="{StaticResource BasicTextStyle}">
                Last Name:
            </TextBlock>
            <TextBox Name="lastName" />
        </StackPanel>
        <Button Content="Submit" Click="Button_Click" Margin="0,0,0,10"/>
        <TextBlock Name="result" Style="{StaticResource BasicTextStyle}" Margin="0,0,0,10"/>
    </StackPanel>
</UserControl>

  7. Fügen Sie die folgende Methode zum NameReporter.xaml.cshinzu:

    using System.Text;
...
private void Button_Click(object sender, RoutedEventArgs e)
{
    StringBuilder displayText = new StringBuilder("Hello, ");
    displayText.AppendFormat("{0} {1}.", firstName.Text, lastName.Text);
    result.Text = displayText.ToString();
}

  8. Sie können jetzt das WinUIComponentCs-Projekt kompilieren, um eine .winmd Datei für die Komponente zu generieren.

Hinweis

Sie können die Komponente auch als NuGet-Paket verpacken, damit Endbenutzer der Anwendung darauf verweisen können. Weitere Informationen finden Sie unter Authoring C#/WinRT components on the C#/WinRT Github repo.

Verweisen auf die Komponente aus einer Windows App SDK C++/WinRT-App

Die folgenden Schritte zeigen, wie Sie die Komponente verwenden, die aus dem vorherigen Abschnitt in einer C++/WinRT-Anwendung mit dem Windows App SDK erstellt wurde. Die Verwendung einer C#/WinRT-Komponente aus C++ erfordert derzeit die Verwendung der Single-Project-Blank App, Packaged (WinUI in Desktop) Vorlage. Beachten Sie, dass C#-Komponenten auch von C#-verpackten Apps ohne Klassenregistrierungen referenziert werden können.

Die Nutzung von verpackten Apps, die ein separates Windows Application Packaging (WAP)-Projekt verwenden, wird derzeit nicht unterstützt. Weitere Informationen finden Sie unter Authoring C#/WinRT components im C#/WinRT GitHub Repository für die neuesten Updates zu unterstützten Projektkonfigurationen.

  1. Fügen Sie Ihrer Lösung ein neues C++ Windows App-SDK-Anwendungsprojekt hinzu. Klicken Sie in Visual Studio mit der rechten Maustaste auf Ihre Lösung, und wählen Sie Add>Neue Project aus. Wählen Sie die C++-Blank App, Packaged (WinUI in Desktop)-Vorlage aus, die von dem Windows App SDK bereitgestellt wird. Für diese Anleitung haben wir die App CppAppbenannt.

  2. Fügen Sie der C#-Komponente einen Projektverweis von der C++-App hinzu. Klicken Sie in Visual Studio mit der rechten Maustaste auf die C++-project, und wählen Sie Add>Reference aus, und wählen Sie die WinUIComponentCs project aus.

    Hinweis

    Die Nutzung von Komponenten als NuGet-Paketreferenz wird mit einigen Einschränkungen unterstützt. Komponenten mit benutzerdefinierten Benutzersteuerelementen können derzeit nicht als NuGet-Paketreferenz genutzt werden.

  3. Fügen Sie in der Kopfzeilendatei pch.h der App die folgenden Zeilen hinzu:

    #include <winrt/WinUIComponentCs.h>
#include <winrt/WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.h>

  4. Öffnen Sie die Paketmanifestdatei, Package.appxmanifest.

    Hinweis

    Es gibt ein bekanntes Problem, bei dem die datei Package.appxmanifest nicht in Visual Studio Solution Explorer angezeigt wird. Um dies zu umgehen, klicken Sie mit der rechten Maustaste auf Ihre C++-project, wählen Sie Unload Project aus, und doppelklicken Sie auf die project, um die Datei CppApp.vcxproj zu öffnen. Fügen Sie der datei project den folgenden Eintrag hinzu, und laden Sie dann die project neu:

    <ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
    <SubType>Designer</SubType>
    </AppxManifest>
</ItemGroup>

    Fügen Sie in Package.appxmanifestdie folgenden aktivierbaren Klassenregistrierungen hinzu. Sie benötigen außerdem einen zusätzlichen ActivatableClass Eintrag für die WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider- Klasse, um die WinUI-Typen zu aktivieren. Klicken Sie mit der rechten Maustaste auf die Package.appxmanifest Datei, und wählen Sie Mit>XML (Text-Editor) öffnen aus, um die Datei zu bearbeiten.

    <!--In order to host the C# component from C++, you must add the following Extension group and list the activatable classes-->
<Extensions>
    <Extension Category="windows.activatableClass.inProcessServer">
        <InProcessServer>
            <Path>WinRT.Host.dll</Path>
            <ActivatableClass ActivatableClassId="WinUIComponentCs.NameReporter" ThreadingModel="both" />
            <ActivatableClass ActivatableClassId="WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider" ThreadingModel="both" />
        </InProcessServer>
    </Extension>
</Extensions>

  5. Öffnen Sie die Datei MainWindow.xaml.

    i. Fügen Sie oben in der Datei einen Verweis auf den Namespace der Komponente hinzu.

    xmlns:custom="using:WinUIComponentCs"

    ii. Fügen Sie das Benutzersteuerelement dem vorhandenen XAML-Code hinzu.

    <StackPanel>
    ...
    <custom:NameReporter/>
</StackPanel>

  6. Legen Sie CppApp als Start-project fest. Klicken Sie mit der rechten Maustaste auf CppApp, und wählen Sie Set as Startup Project aus. Legen Sie die Lösungskonfiguration auf x86. Vor dem Erstellen müssen Sie Ihre Lösung möglicherweise auch neu ausrichten, um sie mit den Buildtools von Visual Studio 2022 zu erstellen. Klicken Sie mit der rechten Maustaste auf die Lösung, wählen Sie Retarget-Lösungaus, und aktualisieren Sie das Platform-Toolset auf v143.

  7. Erstellen Sie die App, und führen Sie sie aus, um das benutzerdefinierte NameReporter--Steuerelement anzuzeigen.

Bekannte Probleme

  • Für die Verwendung einer C#-Komponente als Projektverweis muss PublishReadyToRun auf False festgelegt werden. Weitere Informationen finden Sie unter Github Problem Nr. 1151.
  • Das Verwenden einer C#-Komponente, die für AnyCPU aus C++ erstellt wurde, wird nur von x86-Anwendungen unterstützt. x64 und Arm64 Apps führen zu einem Laufzeitfehler ähnlich wie folgt: %1 ist keine gültige Win32-Anwendung. Weitere Informationen finden Sie unter Github-Problem #1151.
  • Last updated on