Freigeben über

Schritt-für-Schritt-Anleitung: Erstellen einer C#-Komponente mit WinUI 3-Steuerelementen und deren Verwendung in einer C++/WinRT-App, die das Windows App SDK verwendet

C#/WinRT bietet Unterstützung für die Erstellung von Komponenten für Windows-Runtime, einschließlich benutzerdefinierter WinUI-Typen und benutzerdefinierter Steuerelemente. Diese Komponenten können von C#- oder C++/WinRT-Anwendungen genutzt werden, die das 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 in den C #/WinRT-Komponenten im GitHub-Repository "C#/WinRT".

Dieses Tutorial verdeutlicht, wie Sie eine C#-Komponente mit einem benutzerdefinierten WinUI 3-Steuerelement erstellen und, wie Sie diese Komponente aus einer C++/WinRT-App mithilfe der Windows App SDK-Projektvorlagen verwenden.

Voraussetzungen

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

Erstellen Ihrer C#/WinRT-Komponente mit dem Windows App SDK

  1. Erstellen Sie ein neues C#-Bibliotheksprojekt mit der Vom Windows App SDK bereitgestellten Vorlage "Klassenbibliothek (WinUI 3 in Desktop) ". Für diese Anleitung haben wir das Bibliotheksprojekt WinUIComponentCsund die Lösung AuthoringWinUIbenannt.

    Lassen Sie die Projektmappe und Projekt im selben Verzeichnis aufheben, Kontrollkästchen deaktiviert ist (andernfalls beeinträchtigt der packages Ordner für die C++-Anwendung im vorherigen Abschnitt das C#-Bibliotheksprojekt).

    Dialogfeld

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

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

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

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

  4. Fügen Sie ihrem Bibliotheksprojekt die folgenden Eigenschaften hinzu:

    <PropertyGroup>   
    <CsWinRTComponent>true</CsWinRTComponent>
</PropertyGroup>
    • Die CsWinRTComponent Eigenschaft gibt an, dass ihr Projekt eine Komponente für Windows-Runtime ist, sodass beim Erstellen des Projekts eine .winmd Datei generiert wird.

  5. Fügen Sie Ihrer Bibliothek ein benutzerdefiniertes Steuerelement oder ein Benutzersteuerelement hinzu. Klicken Sie dazu in Visual Studio mit der rechten Maustaste auf Ihr Projekt, klicken Sie auf Hinzufügen>neues Element, und wählen Sie im linken Bereich WinUI- aus. Für diese exemplarische Vorgehensweise haben wir ein neues Benutzersteuerelement (WinUI 3) hinzugefügt und NameReporter.xamlbenannt. 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 die WinUIComponentCs Projekt erstellen, 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 Erstellen von C#/WinRT-Komponenten auf dem GitHub-Repository "C#/WinRT".

Eine Komponente aus einer Windows App SDK C++/WinRT-App referenzieren

Die folgenden Schritte zeigen, wie Sie die Komponente nutzen, die aus dem vorherigen Abschnitt erstellt wurde, aus einer C++/WinRT Windows App SDK-Anwendung. Für die Verwendung einer C#/WinRT-Komponente aus C++ ist momentan die Verwendung des Single-Project-Templates Blank App, Packaged (WinUI 3 in Desktop) erforderlich. 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. Die neuesten Updates für unterstützte Projektkonfigurationen finden Sie unter " Authoring C#/WinRT "-Komponenten im GitHub-Repository "C#/WinRT".

  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 "Hinzufügen>Neues Projekt" aus. Wählen Sie die C++-Leere Anwendung, als Paket (WinUI 3 in Desktop) Vorlage aus, die vom Windows App SDK bereitgestellt wird. Für diese Anleitung haben wir die App CppAppbenannt.

  2. Fügen Sie der C#-Komponente einen Projektverweis aus der C++-App hinzu. Klicken Sie in Visual Studio mit der rechten Maustaste auf das C++-Projekt, wählen Sie >Verweis hinzufügen, und dann das WinUIComponentCs Projekt 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 existiert ein bekanntes Problem, bei dem die Package.appxmanifest-Datei im Projektmappen-Explorer von Visual Studio nicht angezeigt wird. Um dies zu umgehen, klicken Sie mit der rechten Maustaste auf Ihr C++-Projekt, wählen Sie Projekt entladenaus und doppelklicken Sie dann auf das Projekt, um die CppApp.vcxproj Datei zu öffnen. Fügen Sie der Projektdatei den folgenden Eintrag hinzu, und laden Sie das Projekt erneut:

    <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 Startprojekt fest, indem Sie mit der rechten Maustaste auf CppAppklicken und Als Startprojekt festlegenauswählen. Legen Sie die Lösungskonfiguration auf x86. Vor dem Erstellen müssen Sie Ihre Lösung möglicherweise auch neuausrichten, um mit den Visual Studio 2022-Build-Tools 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

  • Um eine C#-Komponente als Projektverweis zu verwenden, muss PublishReadyToRun auf Falsefestgelegt werden. Weitere Details finden Sie unter Github Issue #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: %1 ist keine gültige Win32-Anwendung. Weitere Informationen finden Sie unter Github-Problem nr. 1151.
  • Last updated on