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

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

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

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

Предпосылки

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

• Visual Studio 2022 или более поздней версии
• .NET SDK 8.0 (LTS) или более поздняя
• Windows App SDK VSIX (1.1 из стабильного канала)

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

1. Создайте проект библиотеки C# с помощью шаблона Class Library (WinUI in Desktop), предоставленного Windows App SDK. В этом пошаговом руководстве мы назвали библиотеку project WinUIComponentCs и решение AuthoringWinUI.

   Оставьте флажок Разместить решение и проект в том же каталоге не отмеченным (в противном случае папка packages для приложения на C++, упомянутого в предыдущем разделе, будет конфликтовать с проектом библиотеки на C#).

   

2. Удалите файл Class1.cs, включенный по умолчанию.

3. Установите самую последнюю версию пакета NuGet Майкрософт.Windows.CsWinRT в своем проекте.

   и. В Обозреватель решений щелкните правой кнопкой мыши узел проекта и выберите Manage NuGet Packages.

   ii. Найдите Майкрософт.Windows. CsWinRT пакет NuGet и установите последнюю версию.

4. Добавьте следующие свойства в проект библиотеки:

   <PropertyGroup>   
       <CsWinRTComponent>true</CsWinRTComponent>
   </PropertyGroup>
   

   • Свойство CsWinRTComponent указывает, что проект является компонентом среда выполнения Windows, так что при сборке проекта создается файл .winmd.

5. Добавьте в библиотеку пользовательский элемент управления или элемент управления пользователем. Для этого щелкните проект правой кнопкой мыши в Visual Studio, щелкните Add>New Item и выберите WinUI на левой панели. В этом пошаговом руководстве мы добавили новый элемент управления пользователем (WinUI) и назвали его NameReporter.xaml. Элемент управления NameReporter позволяет пользователю ввести имя и фамилию в соответствующий элемент управления TextBox и нажать кнопку. Затем элемент управления отображает поле сообщения с именем, введенным пользователем.

6. Вставьте следующий код в файл 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>
   

7. Добавьте следующий метод в 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. Теперь можно создать WinUIComponentCs project для создания файла .winmd для компонента.

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

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

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

1. Добавьте новый проект приложения C++ Windows App SDK в решение. Щелкните правой кнопкой мыши решение в Visual Studio и выберите Add>New Project. Выберите шаблон WinUI Blank App (Packaged) на C++, предоставленный Windows App SDK. В этом пошаговом руководстве мы назвали приложение CppApp.

2. Добавьте ссылку project из приложения C++ в компонент C#. В Visual Studio щелкните проект C++ правой кнопкой мыши и выберите Add>Reference и выберите проект WinUIComponentCs.

   Замечание

   Использование компонентов в качестве ссылки на пакет NuGet поддерживается с некоторыми ограничениями. Компоненты с пользовательскими элементами управления не могут быть использованы в качестве ссылки на пакет NuGet.

3. В файле заголовка приложения pch.h добавьте следующие строки:

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

4. Откройте файл манифеста пакета, Package.appxmanifest.

   Замечание

   Существует известная проблема, из-за которой файл Package.appxmanifest не отображается в Visual Studio Обозреватель решений. Чтобы обойти эту проблему, щелкните правой кнопкой мыши на C++ проекте, выберите "Unload Project", а затем дважды щелкните на проект, чтобы открыть файл CppApp.vcxproj. Добавьте следующую запись в файл project, а затем перезагрузите project:

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

   В Package.appxmanifestдобавьте следующие регистрации активируемых классов. Кроме того, для активации типов WinUI потребуется дополнительная запись ActivatableClass для класса WinUIComponentCs.WinUIComponentCs_XamlTypeInfo.XamlMetaDataProvider. Щелкните правой кнопкой мыши файл Package.appxmanifest и выберите Открыть с помощью>XML (текстовый редактор), чтобы изменить файл.

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

   и. Добавьте ссылку на пространство имен компонента в верхней части файла.

   xmlns:custom="using:WinUIComponentCs"
   

   ii. Добавьте пользовательский элемент управления в существующий код XAML.

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

6. Задайте CppApp в качестве стартового проекта — щелкните правой кнопкой мыши на CppApp и выберите Установить как стартовый проект. Задайте для конфигурации решения значение x86. Прежде чем собирать, вам также может потребоваться перенацелить решение для сборки с помощью инструментов сборки Visual Studio 2026. Щелкните решение правой кнопкой мыши, выберите решение Retargetи обновите набор инструментов платформы до версии 143.

7. Создайте и запустите приложение, чтобы просмотреть пользовательский элемент управления NameReporter.

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

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

Связанные темы

• Образец приложения для создания C#/WinRT
• Создание компонентов C#/WinRT
• Размещение управляемого компонента