Udostępnij za pośrednictwem

Przewodnik — tworzenie składnika języka C# za pomocą kontrolek WinUI 3 i używanie go z poziomu aplikacji C++/WinRT korzystającej z Zestaw SDK do aplikacji systemu Windows

C#/WinRT zapewnia obsługę tworzenia komponentów środowisko wykonawcze systemu Windows, w tym niestandardowych typów WinUI i kontrolek niestandardowych. Te składniki mogą być używane z poziomu aplikacji C# lub C++/WinRT korzystających z Zestaw SDK do aplikacji systemu Windows. Zalecamy używanie języka C#/WinRT w wersji 1.6.4 lub nowszej do tworzenia składników środowiska uruchomieniowego z obsługą pakietów NuGet.

Aby uzyskać więcej informacji na temat obsługiwanych scenariuszy, zobacz Authoring C#/WinRT components w repozytorium C#/WinRT GitHub.

W tym przewodniku pokazano, jak utworzyć składnik języka C# za pomocą niestandardowej kontrolki WinUI oraz jak korzystać z tego składnika z aplikacji C++/WinRT przy użyciu szablonów projektów Zestaw SDK do aplikacji systemu Windows.

Wymagania wstępne

Ten przewodnik wymaga następujących narzędzi i składników:

Tworzenie składnika C#/WinRT przy użyciu Zestaw SDK do aplikacji systemu Windows

  1. Utwórz nowy projekt biblioteki języka C# przy użyciu szablonu Class Library (WinUI in Desktop) dostarczonego przez Zestaw SDK do aplikacji systemu Windows. W tym przewodniku nazwaliśmy projekt biblioteki WinUIComponentCs, a rozwiązanie AuthoringWinUI.

    Pozostaw pole Umieść rozwiązanie i projekt w tym samym katalogu niezaznaczone (w przeciwnym razie folder packages dla aplikacji C++ w poprzedniej sekcji spowoduje zakłócenia w projekcie biblioteki języka C#).

    okno dialogowe Nowa biblioteka

  2. Class1.cs Usuń plik dołączony domyślnie.

  3. Zainstaluj najnowszy pakiet NuGet Microsoft.Windows.CsWinRT w swoim projekcie.

    punkt i. W Eksplorator rozwiązań kliknij prawym przyciskiem myszy węzeł projektu i wybierz pozycję Zarządzaj pakietami NuGet.

    ii. Wyszukaj Microsoft.Windows. CsWinRT pakiet NuGet i zainstaluj najnowszą wersję.

  4. Dodaj następujące właściwości do projektu biblioteki:

    <PropertyGroup>   
    <CsWinRTComponent>true</CsWinRTComponent>
</PropertyGroup>
    • Właściwość CsWinRTComponent określa, że projekt jest składnikiem środowisko wykonawcze systemu Windows, tak aby plik .winmd był generowany podczas tworzenia projektu.

  5. Dodaj kontrolkę niestandardową lub kontrolkę użytkownika do biblioteki. Aby to zrobić, kliknij prawym przyciskiem myszy projekt w Visual Studio, kliknij Dodaj>Nowy element i wybierz WinUI w lewym okienku. W tym przewodniku dodaliśmy nową kontrolkę użytkownika (WinUI) i nazwaliśmy ją NameReporter.xaml. Kontrolka użytkownika NameReporter umożliwia użytkownikowi wprowadzenie imienia i nazwiska do odpowiedniej kontrolki TextBox oraz kliknięcie przycisku. Kontrolka wyświetla następnie pole komunikatu o nazwie wprowadzonej przez użytkownika.

  6. Wklej następujący kod w NameReporter.xaml pliku:

    <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. Dodaj następującą metodę do NameReporter.xaml.cs:

    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. Teraz możesz skompilować WinUIComponentCs project w celu wygenerowania pliku .winmd dla składnika.

Uwaga / Notatka

Możesz również spakować składnik jako pakiet NuGet, aby użytkownicy aplikacji końcowych mogli się odwołać. Aby uzyskać więcej informacji, zobacz Tworzenie komponentów C#/WinRT w repozytorium C#/WinRT na GitHubie.

Odwołanie do składnika z aplikacji Zestaw SDK do aplikacji systemu Windows C++/WinRT

W poniższych krokach pokazano, jak korzystać ze składnika utworzonego w poprzedniej sekcji z aplikacji Zestaw SDK do aplikacji systemu Windows C++/WinRT. Korzystanie ze składnika C#/WinRT z języka C++ obecnie wymaga użycia szablonu WinUI Blank App (Packaged). Należy pamiętać, że do składników języka C# można również odwoływać się z aplikacji spakowanych w języku C# bez rejestracji klas.

Korzystanie ze spakowanych aplikacji korzystających z oddzielnego projektu Windows Application Packaging (WAP) nie jest obecnie obsługiwane. Zobacz Authoring C#/WinRT components w repozytorium C#/WinRT GitHub, aby uzyskać najnowsze aktualizacje dotyczące obsługiwanych konfiguracji projektu.

  1. Dodaj nowy projekt aplikacji Zestaw SDK do aplikacji systemu Windows języka C++ do rozwiązania. Kliknij prawym przyciskiem myszy rozwiązanie w Visual Studio i wybierz pozycję Dodaj>Nowy Project. Wybierz szablon C++ WinUI Blank App (Packaged) udostępniony przez Zestaw SDK do aplikacji systemu Windows. W tym przewodniku nazwaliśmy aplikację CppApp.

  2. Dodaj odwołanie do projektu z aplikacji C++ do składnika C#. W Visual Studio kliknij prawym przyciskiem myszy projekt C++ i wybierz Dodaj>Reference i wybierz projekt WinUIComponentCs.

    Uwaga / Notatka

    Korzystanie ze składników jako referencji pakietu NuGet jest obsługiwane z pewnymi ograniczeniami. Mianowicie składniki z niestandardowymi kontrolkami użytkownika nie mogą być obecnie używane jako odwołanie do pakietu NuGet.

  3. W pliku nagłówkowym pch.h aplikacji dodaj następujące wiersze:

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

  4. Otwórz plik manifestu pakietu, Package.appxmanifest.

    Uwaga / Notatka

    Istnieje znany problem polegający na tym, że plik Package.appxmanifest nie jest wyświetlany w Visual Studio Eksplorator rozwiązań. Aby obejść ten problem, kliknij prawym przyciskiem myszy na projekt C++, wybierz pozycję Unload Project i kliknij dwukrotnie na projekt, aby otworzyć plik CppApp.vcxproj. Dodaj następujący wpis do pliku project, a następnie załaduj ponownie project:

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

    Wprowadź następujące rejestracje klas możliwych do aktywacji w Package.appxmanifest. Aby aktywować typy WinUI, potrzebny będzie również dodatkowy wpis dla klasy WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider. Kliknij plik prawym przyciskiem myszy Package.appxmanifest i wybierz polecenie Otwórz za pomocą>kodu XML (Edytor tekstów), aby edytować plik.

    <!--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. Otwórz plik MainWindow.xaml.

    punkt i. Dodaj odwołanie do przestrzeni nazw składnika w górnej części pliku.

    xmlns:custom="using:WinUIComponentCs"

    ii. Dodaj kontrolkę użytkownika do istniejącego kodu XAML.

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

  6. Ustaw CppApp jako projekt startowy — kliknij prawym na CppApp i wybierz Ustaw jako projekt startowy. Ustaw konfigurację rozwiązania na x86. Przed utworzeniem może być również konieczne dostosowanie rozwiązania do użycia narzędzi kompilacji Visual Studio 2026. Kliknij rozwiązanie prawym przyciskiem myszy, wybierz rozwiązanie Retargeti uaktualnij zestaw narzędzi platformy do v143.

  7. Skompiluj i uruchom aplikację, aby zobaczyć niestandardową kontrolkę NameReporter.

Znane problemy

  • Korzystanie ze składnika języka C# jako odwołania project wymaga ustawienia PublishReadyToRun na False. Aby uzyskać więcej informacji, zobacz GitHub Problem nr 1151.
  • Korzystanie ze składnika C# stworzonego na AnyCPU jest obecnie obsługiwane tylko przez aplikacje x86 z poziomu C++. x64 i Arm64 aplikacje powodują błąd środowiska uruchomieniowego podobny do: %1 nie jest prawidłową aplikacją Win32. Zobacz GitHub Problem #1093 aby uzyskać więcej szczegółów.
  • Last updated on