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

Język C#/WinRT zapewnia obsługę tworzenia składników środowiska Windows Runtime, w tym specjalnych typów WinUI i kontrolek specjalnych. Te składniki mogą być używane z poziomu aplikacji C# lub C++/WinRT korzystających z Windows App SDK. 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 poziomu aplikacji C++/WinRT przy użyciu szablonów Windows App SDK project.

Wymagania wstępne

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

Visual Studio 2026
SDK .NET 6.0
Windows App SDK VSIX (1.1 z kanału stabilnego)

Tworzenie składnika C#/WinRT przy użyciu Windows App SDK

Utwórz nowy projekt biblioteki C# korzystając z szablonu Class Library (WinUI in Desktop) dostarczonego przez Windows App SDK. 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#).
Class1.cs Usuń plik dołączony domyślnie.
Zainstaluj najnowszy pakiet NuGet Microsoft.Windows.CsWinRT w projekcie.

punkt i. W Solution Explorer kliknij prawym przyciskiem myszy węzeł project i wybierz pozycję Zarządzaj pakietami NuGet.

ii. Wyszukaj pakiet NuGet Microsoft.Windows.CsWinRT i zainstaluj najnowszą wersję.
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 Windows Runtime, tak aby plik .winmd był generowany podczas kompilacji projektu.
Dodaj kontrolkę niestandardową lub kontrolkę użytkownika do biblioteki. Aby to zrobić, kliknij prawym przyciskiem myszy na swój projekt w Visual Studio, wybierz Dodaj>Nowy element i wybierz WinUI w okienku po lewej stronie. 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.

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>

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();
}

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 GitHub C#/WinRT.

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

W poniższych krokach pokazano, jak korzystać ze składnika utworzonego w poprzedniej sekcji z aplikacji Windows App SDK 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.

Wykorzystywanie spakowanych aplikacji korzystających z oddzielnego projektu Pakowanie aplikacji systemu Windows (WAP) nie jest obecnie obsługiwane. Zobacz elementy Authoring C#/WinRT w repozytorium GitHub C#/WinRT, aby uzyskać najnowsze aktualizacje obsługiwanych konfiguracji projektu.

Dodaj nowy projekt aplikacji Windows App SDK w języku 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) dostarczony przez Windows App SDK. W tym przewodniku nazwaliśmy aplikację CppApp.
Dodaj odwołanie do projektu z aplikacji C++ do składnika C#. W Visual Studio kliknij prawym przyciskiem myszy project C++ i wybierz Dodaj>Reference i wybierz WinUIComponentCs project.

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.

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

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

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 Solution Explorer. Aby obejść ten problem, kliknij prawym przyciskiem myszy na projekt C++, wybierz pozycję Unload Project, a następnie kliknij dwukrotnie 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.
```

<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>
```
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>
```
Ustaw CppApp jako projekt startowy — kliknij prawym przyciskiem myszy CppApp i wybierz Ustaw jako projekt startowy. Ustaw konfigurację rozwiązania na x86. Przed kompilacją może być również konieczne przeukierunkowanie rozwiązania do kompilacji za pomocą narzędzi Build programu Visual Studio 2026. Kliknij rozwiązanie prawym przyciskiem myszy, wybierz rozwiązanie Retargeti uaktualnij zestaw narzędzi platformy do v143.
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 #1151 aby uzyskać więcej szczegółów.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-03-11