Пошаговое руководство. Создание компонента C# с элементами управления WinUI 3 и его использование в приложении C++/WinRT, которое использует Windows App SDK

Статья
08/25/2023

C#/WinRT обеспечивает поддержку разработки компонентов среды выполнения Windows, включая настраиваемые типы WinUI и настраиваемые элементы управления. Эти компоненты можно использовать в приложениях C# или C++/WinRT, которые используют Windows App SDK. Мы рекомендуем использовать C#/WinRT версии 1.6.4 или более поздней версии для разработки компонентов среды выполнения с поддержкой упаковки NuGet.

Дополнительные сведения о поддерживаемых сценариях см. в статье Компоненты C#/WinRT в репозитории C#/WinRT GitHub.

В этом пошаговом руководстве показано, как создать компонент C# с настраиваемым элементом управления WinUI 3 и как использовать этот компонент из приложения C++/WinRT с помощью шаблонов проекта Windows App SDK.

Необходимые компоненты

Для выполнения данного пошагового руководства требуются следующие инструменты, средства и компоненты:

Visual Studio 2022 год
Пакет SDK для .NET 6.0
ПАКЕТ SDK для приложений Windows (VSIX 1.1 из стабильного канала)

Создание компонента C#/WinRT с помощью Windows App SDK

Создайте новый проект библиотеки C# с помощью шаблона библиотеки классов (WinUI 3 в классических приложениях), доступного в Windows App SDK. В этом пошаговом руководстве мы присвоили проекту библиотеки имя WinUIComponentCs и решению — имя AuthoringWinUI.

Не устанавливайте флажок Поместить решение Place и проект в один каталог (в противном случае папка packages для приложения C++ в предыдущем разделе будет мешать работе проекта библиотеки C#).
Удалите файл Class1.cs, включенный по умолчанию.
Установите последнюю версию пакета NuGet Microsoft.Windows.CsWinRT в проекте.

i. В обозревателе решений щелкните правой кнопкой мыши по проекту и выберите Управление пакетами NuGet.

ii. Найдите Microsoft.Windows.CsWinRT пакет NuGet и установите последнюю версию.
Добавьте следующие свойства в проект библиотеки:
```
<PropertyGroup>   
    <CsWinRTComponent>true</CsWinRTComponent>
</PropertyGroup>
```
- Свойство CsWinRTComponent указывает, что проект является компонентом среды выполнения Windows, чтобы при сборке проекта создавался файл .winmd.
Добавьте в библиотеку настраиваемый или пользовательский элемент управления. Для этого щелкните правой кнопкой мыши проект в Visual Studio, выберите Добавить>Новый элемент и выберите WinUI на панели слева. В этом пошаговом руководстве мы добавили новый пользовательский элемент управления (WinUI 3) и назвали его NameReporter.xaml. Элемент управления NameReporter позволяет пользователю ввести имя и фамилию в соответствующий элемент управления TextBox и нажать кнопку. Затем элемент управления отобразит окно сообщения с именем, которое ввел пользователь.

Вставьте в файл NameReporter.xaml приведенный ниже код.

<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>

Добавьте следующий метод к 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();
}

Теперь моно выполнить сборку проекта WinUIComponentCs, чтобы создать файл .winmd для компонента.

Примечание.

Вы также можете упаковать компонент в виде пакета NuGet, на который могут ссылаться конечные потребители. Дополнительные сведения см. в статье Разработка компонентов C#/WinRT в репозитории C#/WinRT GitHub.

Создание ссылки на компонент из приложения Windows App SDK C++/WinRT

Далее показано, как использовать компонент, созданный в предыдущем разделе, из приложения Windows App SDK C++/WinRT. В настоящее время для использования компонента C#/WinRT из C++ требуется использовать шаблон Пустое приложение, упакованное (WinUI 3 в классических приложениях) с одним проектом. Обратите внимание, что на компоненты C# также можно ссылаться из упакованных приложений C# без регистрации классов.

Потребление из упакованных приложений, использующих отдельный проект упаковки приложений Windows (WAP), в настоящее время не поддерживается. Сведения о последних обновлениях поддерживаемых конфигураций проектов см. в статье Разработка компонентов C# и Win GitHub RT в репозитории C#/WinRT.

Добавьте новый проект С++ Windows App SDK в свое решение. Щелкните решение правой кнопкой мыши в Visual Studio и выберите Добавить>Новый проект. Выберите шаблон C++ Пустое приложение, упакованный (WinUI 3 в классических приложениях), предоставленный Windows App SDK. В этом пошаговом руководстве мы назвали приложение CppApp.
Добавьте ссылку на проект из приложения C++ в компонент C#. В Visual Studio щелкните правой кнопкой мыши проект C++ и выберите команду Добавить>Cсылка и выберите проект WinUIComponentCs.

Примечание.

Использование компонентов в качестве ссылки на пакет NuGet поддерживается с некоторыми ограничениями. То есть, компоненты с пользовательскими элементами управления в настоящее время нельзя использовать в качестве ссылки на пакет NuGet.
В файле заголовка приложения pch.h добавьте следующие строки:
```
#include <winrt/WinUIComponentCs.h>
#include <winrt/WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.h>
```
Откройте файл манифеста пакета (Package.appxmanifest).

Примечание.

Существует известная проблема, из-за которой файл Package.appxmanifest не отображается в Обозревателе решений Visual Studio. Чтобы решить эту проблему, щелкните правой кнопкой мыши проект C++, выберите Выгрузить проект и дважды щелкните проект, чтобы открыть файл CppApp.vcxproj. Добавьте следующую запись в файл проекта и перезагрузите проект:
```
<ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
    <SubType>Designer</SubType>
    </AppxManifest>
</ItemGroup>
```
В Package.appxmanifest добавьте следующие активируемые регистрации классов. Кроме того, для активации типов WinUI потребуется дополнительная запись ActivatableClass для класса WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider. Щелкните файл Package.appxmanifest правой кнопкой мыши и выберите команду Открыть с помощью>XML (текстовый редактор), чтобы отредактировать файл.
```

<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>
```
Откройте файл MainWindow.xaml.

i. Добавьте ссылку на пространство имен компонента в верхней части файла.
```
xmlns:custom="using:WinUIComponentCs"
```
ii. Добавьте пользовательский элемент управления в существующий код XAML.
```
<StackPanel>
    ...
    <custom:NameReporter/>
</StackPanel>
```
Задайте CppApp в качестве проекта запуска — щелкните правой кнопкой мыши CppApp и выберите Задать в качестве проекта запуска. Настройте для конфигурации решения значение x86. Прежде чем выполнить сборку, вам также может потребоваться перенацелить решение для сборки с помощью инструментов сборки Visual Studio 2022. Щелкните решение правой кнопкой мыши, выберите Перенацелить решение и обновите набор инструментов платформы до версии 143.
Выполните сборку и запустите приложение, чтобы просмотреть настраиваемый элемент управления NameReporter.

Известные проблемы

Для использования компонента C# в качестве ссылки на проект необходимо задать для параметра PublishReadyToRun значение False. Дополнительные сведения см. в описании проблемы GitHub № 1151.
Использование компонента C#, созданного для AnyCPU на основе C++, в настоящее время поддерживается только из приложений x86. Приложения x64 и Arm64 приводят к ошибке среды выполнения, аналогичной следующей ошибке: %1 не является допустимым приложением Win32. Дополнительные сведения см. в выпуске GitHub № 1151.

Поделиться через

Пошаговое руководство. Создание компонента C# с элементами управления WinUI 3 и его использование в приложении C++/WinRT, которое использует Windows App SDK

Необходимые компоненты

Создание компонента C#/WinRT с помощью Windows App SDK

Создание ссылки на компонент из приложения Windows App SDK C++/WinRT

Известные проблемы

Дополнительные ресурсы

Поделиться через

Пошаговое руководство. Создание компонента C# с элементами управления WinUI 3 и его использование в приложении C++/WinRT, которое использует Windows App SDK

Необходимые компоненты

Создание компонента C#/WinRT с помощью Windows App SDK

Создание ссылки на компонент из приложения Windows App SDK C++/WinRT

Известные проблемы

См. также

Дополнительные ресурсы