Размещение пользовательского элемента управления XAML UWP в приложении WPF с помощью XAML Islands

В этой статье показано, как использовать элемент управления WindowsXamlHost в наборе средств сообщества Windows для размещения пользовательского элемента управления XAML UWP в приложении WPF, которое предназначено для .NET Core 3.1. Пользовательский элемент управления содержит несколько сторонних элементов управления из пакета SDK Windows и привязывает свойство в одном из элементов управления XAML UWP к строке в приложении WPF. В этой статье также показано, как разместить элемент управления из библиотеки WinUI 3.

Хотя в этой статье показано, как это сделать в приложении WPF, процесс аналогичен приложению Windows Forms. Общие сведения о размещении элементов управления XAML UWP в приложениях WPF и Windows Forms см. в статье this.

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

Чтобы разместить пользовательский элемент управления XAML UWP в приложении WPF (или Windows Forms), вам потребуются следующие компоненты в решении. Эта статья содержит инструкции по созданию каждого из этих компонентов.

• Проект и исходный код для вашего приложения. Использование элемента управления WindowsXamlHost для размещения пользовательских элементов управления поддерживается только в приложениях, предназначенных для .NET Core 3.x.

• Пользовательский XAML элемент управления для UWP. Для настраиваемого элемента управления, который необходимо разместить, необходим исходный код, чтобы скомпилировать его в приложение. Как правило, пользовательский элемент управления определяется в библиотеке классов проекта UWP, на которую вы ссылаетесь в том же решении, что и проект WPF или Windows Forms.

• проект UWP приложения, который определяет корневой класс приложения, наследующий от XamlApplication Ваши проекты WPF или Windows Forms должны иметь доступ к экземпляру класса Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication, предоставленного Windows Community Toolkit, чтобы они могли обнаруживать и загружать пользовательские элементы управления UWP XAML. Рекомендуемый способ сделать это — определить этот объект в отдельном проекте приложения UWP, который входит в состав решения для вашего приложения WPF или Windows Forms.

  Замечание

  Решение может содержать только один проект, который определяет объект XamlApplication. Все пользовательские элементы управления XAML UWP в приложении используют один и тот же XamlApplication объект. Проект, который определяет объект XamlApplication, должен содержать ссылки на все другие библиотеки и проекты WinRT, которые используются для размещения элементов управления на XAML Island.

Создание проекта WPF

Прежде чем приступить к работе, следуйте этим инструкциям, чтобы создать проект WPF и настроить его для размещения островов XAML UWP. Если у вас уже есть проект WPF, вы можете адаптировать эти шаги и примеры кода для своего проекта.

1. Если это еще не сделано, установите последнюю версию пакета SDK .NET Core 3.1.

2. В Visual Studio 2019 создайте новый проект приложения WPF (.NET Core).

3. Убедитесь, что ссылки на пакеты package references включены.

   1. В Visual Studio щелкните Tools -> NuGet диспетчер пакетов -> диспетчер пакетов Settings.
   2. Убедитесь, что для формата управления пакетами по умолчанию установлено значение PackageReference.

4. Щелкните правой кнопкой мыши проект WPF в Обозреватель решений и выберите Управление пакетами NuGet.

5. Перейдите на вкладку Browse, найдите пакет Microsoft.Toolkit.Wpf.UI.XamlHost и установите последнюю стабильную версию. Этот пакет предоставляет все необходимое для использования элемента управления WindowsXamlHost для размещения элемента управления XAML UWP, включая другие связанные пакеты NuGet.

   Замечание

   Windows Forms приложения должны использовать пакет Microsoft.Toolkit.Forms.UI.XamlHost.

6. Настройте решение для конкретной платформы, например x86 или x64. Пользовательские элементы управления XAML UWP не поддерживаются в проектах, предназначенных для любого ЦП.

   1. В Обозреватель решений щелкните правой кнопкой мыши узел решения и выберите Properties ->Configuration Properties ->Configuration Manager.
   2. В списке Active solution platform (Активная платформа решения) выберите пункт Создать.
   3. В диалоговом окне Создание платформы решения выберите x64 или x86 и нажмите кнопку ОК.
   4. Закройте открытые диалоговые окна.

Определение класса XamlApplication в project приложения UWP

Затем добавьте проект приложения UWP в ваше решение и измените класс App по умолчанию в этом проекте, чтобы он наследовался от класса Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication, предоставленного Windows Community Toolkit. Этот класс поддерживает интерфейс IXamlMetadataProvider, который позволяет приложению обнаруживать и загружать метаданные для настраиваемых элементов управления UWP XAML в сборках в текущем каталоге приложения во время выполнения. Этот класс также инициализирует платформу UWP XAML для текущего потока.

1. В Обозреватель решений щелкните правой кнопкой мыши узел решения и выберите Add ->New Project.

2. Добавьте проект Blank App (универсальное приложение Windows) в ваше решение. Убедитесь, что целевая версия и минимальная версия имеют значение Windows 10 версии 1903 (сборка 18362) или более поздней версии.

3. В проекте приложения UWP установите пакет NuGet Microsoft.Toolkit.Win32.UI.XamlApplication (последняя стабильная версия).

4. Откройте файл App.xaml и замените его содержимое приведенным ниже кодом XAML. Замените MyUWPApp пространством имен вашего проекта приложения UWP.

   <xaml:XamlApplication
       x:Class="MyUWPApp.App"
       xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       xmlns:xaml="using:Microsoft.Toolkit.Win32.UI.XamlHost"
       xmlns:local="using:MyUWPApp">
   </xaml:XamlApplication>
   

5. Откройте файл App.xaml.cs и замените его содержимое приведенным ниже кодом. Замените MyUWPApp пространством имен вашего проекта приложения UWP.

   namespace MyUWPApp
   {
       public sealed partial class App : Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication
       {
           public App()
           {
               this.Initialize();
           }
       }
   }
   

6. Удалите файл MainPage.xaml из project приложения UWP.

7. Очистите приложение UWP project, а затем создайте его.

Добавьте ссылку на project UWP в WPF project

1. Укажите совместимую версию платформы в файле WPF project.

   1. В Обозреватель решений дважды щелкните узел WPF project, чтобы открыть файл project в редакторе.

   2. В первый элемент PropertyGroup добавьте следующий дочерний элемент. Измените часть значения 19041, чтобы она соответствовала целевой и минимальной сборкам ОС проекта UWP.

      <AssetTargetFallback>uap10.0.19041</AssetTargetFallback>
      

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

      <PropertyGroup>
          <OutputType>WinExe</OutputType>
          <TargetFramework>netcoreapp3.1</TargetFramework>
          <UseWPF>true</UseWPF>
          <Platforms>AnyCPU;x64</Platforms>
          <AssetTargetFallback>uap10.0.19041</AssetTargetFallback>
      </PropertyGroup>
      

2. В Обозреватель решений щелкните правой кнопкой мыши на узле Dependencies в проекте WPF и добавьте ссылку на проект приложения UWP.

Инициализируйте объект XamlApplication в точке запуска приложения WPF

Затем добавьте код в точку входа для приложения WPF, чтобы создать экземпляр класса App, который вы только что определили в project UWP (это класс, производный от XamlApplication).

1. В WPF project щелкните правой кнопкой мыши узел project, выберите Add ->New Item и выберите Class. Назовите класс Program и щелкните Добавить.

2. Замените созданный класс Program кодом ниже, а затем сохраните файл. Замените MyUWPApp пространством имен вашего проекта приложения UWP и замените MyWPFApp пространством имен вашего проекта приложения WPF.

   public class Program
   {
       [System.STAThreadAttribute()]
       public static void Main()
       {
           using (new MyUWPApp.App())
           {
               MyWPFApp.App app = new MyWPFApp.App();
               app.InitializeComponent();
               app.Run();
           }
       }
   }
   

3. Щелкните правой кнопкой мыши узел project и выберите Properties.

4. На вкладке Приложение в диалоговом окне "Свойства" щелкните раскрывающийся список Объект запуска и выберите полное имя класса Program, добавленного на предыдущем шаге.

   Замечание

   По умолчанию WPF проекты определяют функцию точки входа Main в созданном файле кода, который не предназначен для изменения. На этом шаге точка входа для project изменяется на метод Main нового класса Program, который позволяет добавлять код, который выполняется как можно раньше в процессе запуска приложения.

5. Сохраните изменения в свойствах проекта.

Создайте пользовательский элемент управления UWP XAML

Чтобы разместить пользовательский элемент управления XAML UWP в приложении WPF, необходимо иметь исходный код для элемента управления, чтобы его можно было скомпилировать с помощью приложения. Обычно пользовательские элементы управления определяются в библиотеке классов проекта UWP для простой переносимости.

В этом разделе вы создадите простой пользовательский элемент управления в новом проекте библиотеки классов. Можно также определить пользовательский элемент управления в приложении UWP project, созданном в предыдущем разделе. Однако эти действия выполняются в проекте библиотеки классов в иллюстративных целях, так как обычно это способ реализации пользовательских элементов управления для обеспечения переносимости.

Если у вас уже есть настраиваемый элемент управления, его можно использовать вместо элемента управления, показанного здесь. Однако вам по-прежнему потребуется настроить проект, содержащий элемент управления, как показано на следующих шагах.

1. В Обозреватель решений щелкните правой кнопкой мыши узел решения и выберите Add ->New Project.

2. Добавьте проект библиотеки классов (Универсальная платформа Windows) в ваше решение. Убедитесь, что целевая версия и минимальная версия установлены на ту же целевую и минимальную сборку ОС, что и в проекте UWP.

3. Щелкните правой кнопкой мыши файл project и выберите Unload Project. Щелкните правой кнопкой мыши файл project и выберите Edit.

4. Перед закрывающим элементом </Project> добавьте следующий XML-файл, чтобы отключить несколько свойств, а затем сохранить файл project. Эти свойства должны быть включены для размещения пользовательского элемента управления в приложении WPF (или Windows Forms).

   <PropertyGroup>
     <EnableTypeInfoReflection>false</EnableTypeInfoReflection>
     <EnableXBindDiagnostics>false</EnableXBindDiagnostics>
   </PropertyGroup>
   

5. Щелкните правой кнопкой мыши файл project и выберите Reload Project.

6. Удалите файл Class1.cs по умолчанию и добавьте новый элемент User Control в project.

7. В файле XAML для пользовательского элемента управления добавьте следующий объект StackPanel в качестве дочернего элемента Grid по умолчанию. В этом примере добавляется элемент управления TextBlock, а затем атрибут Text этого элемента управления привязывается к полю XamlIslandMessage.

   <StackPanel Background="LightCoral">
       <TextBlock>This is a simple custom UWP XAML control</TextBlock>
       <Rectangle Fill="Blue" Height="100" Width="100"/>
       <TextBlock Text="{x:Bind XamlIslandMessage}" FontSize="50"></TextBlock>
   </StackPanel>
   

8. В файле кода программной части пользовательского интерфейса добавьте поле XamlIslandMessage к классу пользовательского элемента управления, как показано ниже.

   public sealed partial class MyUserControl : UserControl
   {
       public string XamlIslandMessage { get; set; }
   
       public MyUserControl()
       {
           this.InitializeComponent();
       }
   }
   

9. Соберите проект библиотеки классов UWP.

10. В вашем WPF проекте щелкните правой кнопкой мыши узел Dependencies и добавьте ссылку на проект библиотеки классов UWP.

11. В проекте приложения UWP щелкните правой кнопкой мыши узел References и добавьте ссылку на проект библиотеки классов UWP.

12. Перестройте все решение и убедитесь, что все проекты успешно построены.

Размещение пользовательского элемента управления XAML UWP в приложении WPF

1. В Обозреватель решений разверните WPF project и откройте файл MainWindow.xaml или другое окно, в котором требуется разместить пользовательский элемент управления.

2. В файле XAML добавьте следующее объявление пространства имен в элемент <Window>.

   xmlns:xaml="clr-namespace:Microsoft.Toolkit.Wpf.UI.XamlHost;assembly=Microsoft.Toolkit.Wpf.UI.XamlHost"
   

3. В том же файле добавьте указанный ниже элемент управления в элемент <Grid>. Измените атрибут InitialTypeName на полное имя пользовательского элемента управления в проекте библиотеки классов UWP.

   <xaml:WindowsXamlHost InitialTypeName="UWPClassLibrary.MyUserControl" ChildChanged="WindowsXamlHost_ChildChanged" />
   

4. Откройте файл кода программной части и добавьте указанный ниже код в класс Window. Этот код определяет обработчик событий ChildChanged, который назначает значение поля XamlIslandMessage пользовательского элемента управления UWP значению поля WPFMessage в приложении WPF. Измените UWPClassLibrary.MyUserControl на полное имя пользовательского элемента управления в библиотеке классов проекта UWP.

   private void WindowsXamlHost_ChildChanged(object sender, EventArgs e)
   {
       // Hook up x:Bind source.
       global::Microsoft.Toolkit.Wpf.UI.XamlHost.WindowsXamlHost windowsXamlHost =
           sender as global::Microsoft.Toolkit.Wpf.UI.XamlHost.WindowsXamlHost;
       global::UWPClassLibrary.MyUserControl userControl =
           windowsXamlHost.GetUwpInternalObject() as global::UWPClassLibrary.MyUserControl;
   
       if (userControl != null)
       {
           userControl.XamlIslandMessage = this.WPFMessage;
       }
   }
   
   public string WPFMessage
   {
       get
       {
           return "Binding from WPF to UWP XAML";
       }
   }
   

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

Добавьте элемент управления из библиотеки WinUI для UWP в пользовательский элемент управления

Традиционно элементы управления XAML UWP были выпущены в составе ос Windows и предоставлены разработчикам через пакет SDK Windows. Библиотека WinUI — это альтернативный подход, при котором обновленные версии элементов управления UWP XAML из пакета SDK Windows распределены в пакете NuGet, который не привязан к выпускам пакета SDK Windows. Эта библиотека также содержит новые элементы управления, которые не входят в состав пакета Windows SDK и платформы UWP по умолчанию.

В этом разделе показано, как добавить элемент управления XAML UWP из библиотеки WinUI для UWP в пользовательский элемент управления.

1. В проекте приложения UWP установите последнюю версию или предварительный релиз пакета NuGet Microsoft.UI.Xaml.

   Замечание

   Если настольное приложение упаковано в пакет MSIX, можно использовать предварительную или окончательную версию пакета NuGet Microsoft.UI.Xaml. Если настольное приложение не упаковано с использованием MSIX, необходимо установить предварительную версию пакета NuGet Microsoft.UI.Xaml.

2. В файле App.xaml в этом проекте добавьте следующий дочерний элемент в элемент <xaml:XamlApplication>.

   <Application.Resources>
       <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
   </Application.Resources>
   

   После добавления этого элемента содержимое файла должно выглядеть следующим образом:

   <xaml:XamlApplication
       x:Class="MyUWPApp.App"
       xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       xmlns:xaml="using:Microsoft.Toolkit.Win32.UI.XamlHost"
       xmlns:local="using:MyUWPApp">
       <Application.Resources>
           <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
       </Application.Resources>
   </xaml:XamlApplication>
   

3. В проекте библиотеки классов UWP установите последнюю версию пакета NuGet Microsoft.UI.Xaml (ту же версию, что и в проекте приложения UWP).

4. В том же проекте откройте XAML-файл для элемента управления пользователем и добавьте следующее объявление пространства имен в элемент "<UserControl>".

   xmlns:winui="using:Microsoft.UI.Xaml.Controls"
   

5. В том же файле добавьте элемент <winui:RatingControl /> в качестве дочернего элемента <StackPanel>. Этот элемент добавляет экземпляр класса RatingControl из библиотеки WinUI. После добавления этого элемента <StackPanel> должен выглядеть следующим образом.

   <StackPanel Background="LightCoral">
       <TextBlock>This is a simple custom UWP XAML control</TextBlock>
       <Rectangle Fill="Blue" Height="100" Width="100"/>
       <TextBlock Text="{x:Bind XamlIslandMessage}" FontSize="50"></TextBlock>
       <winui:RatingControl />
   </StackPanel>
   

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

Создание пакета приложения

При необходимости можно упаковить приложение WPF в пакете MSIX для развертывания. MSIX — это современная технология упаковки приложений для Windows. В ее основе лежат технологии установки MSI, APPX, App-V и ClickOnce.

В следующих инструкциях показано, как упаковать все компоненты решения в пакет MSIX с помощью пакета Windows Application Package Project в Visual Studio 2019. Эти действия необходимы только в том случае, если вы хотите упаковать приложение WPF в пакет MSIX.

1. Добавьте в решение новый проект Windows Application Packaging Project. При создании project выберите ту же версию Target и версию Minimum, что и для project UWP.

2. В проекте упаковки щелкните правой кнопкой мыши узел Applications и выберите Add reference. В списке проектов выберите WPF project в решении и щелкните OK.

   Замечание

   Если вы хотите опубликовать ваше приложение в Microsoft Store, необходимо добавить ссылку на проект UWP в проект упаковки.

3. Настройте решение для конкретной платформы, например x86 или x64. Это необходимо для создания пакета MSIX из приложения WPF с помощью Проекта упаковки приложений Windows.

   1. В Обозреватель решений щелкните правой кнопкой мыши узел решения и выберите Properties ->Configuration Properties ->Configuration Manager.
   2. В списке Active solution platform (Активная платформа решения) выберите пункт x64 или x86.
   3. В строке для вашего WPF проекта в столбце Platform выберите Новый.
   4. В диалоговом окне Создание платформы решения выберите x64 или x86 (ту же платформу, которую вы выбрали в списке Active solution platform (Активная платформа решения)) и нажмите кнопку ОК.
   5. Закройте открытые диалоговые окна.

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

5. Сведения о распространении и развертывании пакета см. в статье Управление развертыванием MSIX.

Устранение ошибки"Не удалось найти ресурс" при размещении элемента управления WinUI

Если вы размещаете пользовательский элемент управления, содержащий элемент управления из библиотеки WinUI, может возникнуть проблема, из-за которой элемент управления не удается загрузить в упакованное приложение, а при отладке кода отображается следующая ошибка.

Чтобы устранить эту ошибку, скопируйте файл App.xbf из выходной папки сборки проекта WPF в папку \AppX\<проекта WPF>, выходную папку сборки упаковочного проекта.

Например, если WPF project называется WPFXamlIslandsApp и предназначен для платформы x86, скопируйте App.xbf из \WPFXamlIslandsApp\bin\x86\Release\netcoreapp3.1 на \WPFXamlIslandsApp.Pack\bin\x86\Release\AppX\WPFXamlIslandsAPP.

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

• Размещение элементов управления XAML UWP в классических приложениях (XAML Islands UWP)
• Примеры кода XAML Islands UWP
• WindowsXamlHost