Using the Visual Layer with Windows Forms

You can use Windows Runtime Composition APIs (also called the Visual layer) in your Windows Forms apps to create modern experiences that light up for Windows 10 users.

The complete code for this tutorial is available on GitHub: Windows Forms HelloComposition sample.

Prerequisites

The UWP hosting API has these prerequisites.

• We assume that you have some familiarity with app development using Windows Forms and UWP. For more info, see:
  • Getting Started with Windows Forms
  • Get started with Windows 10 apps
  • Enhance your desktop application for Windows 10
• .NET Framework 4.7.2 or later
• Windows 10 version 1803 or later
• Windows 10 SDK 17134 or later

How to use Composition APIs in Windows Forms

In this tutorial, you create a simple Windows Forms UI and add animated Composition elements to it. Both the Windows Forms and Composition components are kept simple, but the interop code shown is the same regardless of the complexity of the components. The finished app looks like this.

Create a Windows Forms project

The first step is to create the Windows Forms app project, which includes an application definition and the main form for the UI.

To create a new Windows Forms Application project in Visual C# named HelloComposition:

1. Open Visual Studio and select File >New >Project.
   The New Project dialog opens.
2. Under the Installed category, expand the Visual C# node, and then select Windows Desktop.
3. Select the Windows Forms App (.NET Framework) template.
4. Enter the name HelloComposition, select Framework .NET Framework 4.7.2, then click OK.

Visual Studio creates the project and opens the designer for the default application window named Form1.cs.

Configure the project to use Windows Runtime APIs

To use Windows Runtime (WinRT) APIs in your Windows Forms app, you need to configure your Visual Studio project to access the Windows Runtime. In addition, vectors are used extensively by the Composition APIs, so you need to add the references required to use vectors.

NuGet packages are available to address both of these needs. Install the latest versions of these packages to add the necessary references to your project.

While we recommend using the NuGet packages to configure your project, you can add the required references manually. For more info, see Enhance your desktop application for Windows 10. The following table shows the files that you need to add references to.

File	Location
System.Runtime.WindowsRuntime	C:\Windows\Microsoft.NET\Framework\v4.0.30319
Windows.Foundation.UniversalApiContract.winmd	C:\Program Files (x86)\Windows Kits\10\References \Windows.Foundation.UniversalApiContract
Windows.Foundation.FoundationContract.winmd	C:\Program Files (x86)\Windows Kits\10\References \Windows.Foundation.FoundationContract
System.Numerics.Vectors.dll	C:\WINDOWS\Microsoft.Net\assembly\GAC_MSIL\System.Numerics.Vectors\v4.0_4.0.0.0__b03f5f7f11d50a3a
System.Numerics.dll	C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework.NETFramework\v4.7.2

Create a custom control to manage interop

To host content you create with the visual layer, you create a custom control derived from Control. This control gives you access to a window Handle, which you need in order to create the container for your visual layer content.

This is where you do most of the configuration for hosting Composition APIs. In this control, you use Platform Invocation Services (PInvoke) and COM Interop to bring Composition APIs into your Windows Forms app. For more info about PInvoke and COM Interop, see Interoperating with unmanaged code.

If you need to, check the complete code at the end of the tutorial to make sure all the code is in the right places as you work through the tutorial.

Add a new custom control file to your project that derives from Control.

• In Solution Explorer, right click the HelloComposition project.
• In the context menu, select Add >New Item. .
• In the Add New Item dialog, select Custom Control.
• Name the control CompositionHost.cs, then click Add. CompositionHost.cs opens in the Design view.

Switch to code view for CompositionHost.cs and add the following code to the class.

Add code to the constructor.

In the constructor, you call the InitializeCoreDispatcher and InitComposition methods. You create these methods in the next steps.

Initialize a thread with a CoreDispatcher. The core dispatcher is responsible for processing window messages and dispatching events for WinRT APIs. New instances of Compositor must be created on a thread that has a CoreDispatcher.

• Create a method named InitializeCoreDispatcher and add code to set up the dispatcher queue.

• The dispatcher queue requires a PInvoke declaration. Place this declaration at the end of the code for the class. (We place this code inside a region to keep the class code tidy.)

You now have the dispatcher queue ready and can begin to initialize and create Composition content.

Initialize the Compositor. The Compositor is a factory that creates a variety of types in the Windows.UI.Composition namespace spanning the visual layer, effects system, and animation system. The Compositor class also manages the lifetime of objects created from the factory.

• ICompositorDesktopInterop and ICompositionTarget require COM imports. Place this code after the CompositionHost class, but inside the namespace declaration.

Create a custom control to host composition elements

It’s a good idea to put the code that generates and manages your composition elements in a separate control that derives from CompositionHost. This keeps the interop code you created in the CompositionHost class reusable.

Here, you create a custom control derived from CompositionHost. This control is added to the Visual Studio toolbox so you can add it to your form.

Add a new custom control file to your project that derives from CompositionHost.

• In Solution Explorer, right click the HelloComposition project.
• In the context menu, select Add >New Item. .
• In the Add New Item dialog, select Custom Control.
• Name the control CompositionHostControl.cs, then click Add. CompositionHostControl.cs opens in the Design view.

In the Properties pane for CompositionHostControl.cs design view, set the BackColor property to ControlLight.

Setting the background color is optional. We do it here so you can see your custom control against the form background.

Switch to code view for CompositionHostControl.cs and update the class declaration to derive from CompositionHost.

Update the constructor to call the base constructor.

Add composition elements

With the infrastructure in place, you can now add Composition content to the app UI.

For this example, you add code to the CompositionHostControl class that creates and animates a simple SpriteVisual.

Add a composition element.

In CompositionHostControl.cs, add these methods to the CompositionHostControl class.

Add the control to your form

Now that you have a custom control to host Composition content, you can add it to the app UI. Here, you add an instance of the CompositionHostControl you created in the previous step. CompositionHostControl is automatically added to the Visual Studio toolbox under project name Components.

In Form1.CS design view, add a Button to the UI.

• Drag a Button from the toolbox onto Form1. Place it in the upper left corner of the form. (See the image at the start of the tutorial to check the placement of the controls.)
• In the Properties pane, change the Text property from button1 to Add composition element.
• Resize the Button so that all the text shows.

Add a CompositionHostControl to the UI.

• Drag a CompositionHostControl from the toolbox onto Form1. Place it to the right of the Button.
• Resize the CompositionHost so that it fills the remainder of the form.

Handle the button click event.

• In the Properties pane, click the lightning bolt to switch to the Events view.
• In the events list, select the Click event, type Button_Click, and press Enter.
• This code is added in Form1.cs:

Add code to the button click handler to create new elements.

• In Form1.cs, add code to the Button_Click event handler you created previously. This code calls CompositionHostControl1.AddElement to create a new element with a randomly generated size and offset. (The instance of CompositionHostControl was automatically named compositionHostControl1 when you dragged it onto the form.)

You can now build and run your Windows Forms app. When you click the button, you should see animated squares added to the UI.

Next steps

For a more complete example that builds on the same infrastructure, see the Windows Forms Visual layer integration sample on GitHub.

Additional resources

Complete code

Here’s the complete code for this tutorial.

Использование визуального уровня на платформе Windows Forms Using the Visual Layer with Windows Forms

Вы можете использовать интерфейсы API Composition среды выполнения Windows (также называемые визуальным уровнем) в приложениях Windows Forms, чтобы создавать современные интерфейсы для пользователей Windows 10. You can use Windows Runtime Composition APIs (also called the Visual layer) in your Windows Forms apps to create modern experiences that light up for Windows 10 users.

Полный код для этого руководства доступен на сайте GitHub: Пример приложения Windows Forms HelloComposition The complete code for this tutorial is available on GitHub: Windows Forms HelloComposition sample.

Предварительные условия Prerequisites

Для использования API размещения для UWP накладываются приведенные ниже предварительные требования. The UWP hosting API has these prerequisites.

• Предполагается, что у вас есть опыт разработки приложений с помощью Windows Forms и UWP. We assume that you have some familiarity with app development using Windows Forms and UWP. См. также: For more info, see:
  • Приступая к работе с Windows Forms Getting Started with Windows Forms
  • Приступая к работе с приложениями для Windows 10 Get started with Windows 10 apps
  • Улучшение классического приложения для Windows 10 Enhance your desktop application for Windows 10
• .NET Framework 4.7.2 или более поздней версии. .NET Framework 4.7.2 or later
• Windows 10 версии 1803 или более поздней версии. Windows 10 version 1803 or later
• Пакет SDK для Windows 10 версии 17134 или более поздней версии. Windows 10 SDK 17134 or later

Как использовать интерфейсы API Composition в Windows Forms How to use Composition APIs in Windows Forms

При работе с этим руководством вы создадите пользовательский интерфейс приложения Windows Forms и добавите в него анимированные элементы Composition. In this tutorial, you create a simple Windows Forms UI and add animated Composition elements to it. Компоненты Windows Forms и компоненты Composition простые, но приведенный код взаимодействия одинаков независимо от сложности компонентов. Both the Windows Forms and Composition components are kept simple, but the interop code shown is the same regardless of the complexity of the components. Завершенное приложение выглядит следующим образом. The finished app looks like this.

Создание проекта Windows Forms Create a Windows Forms project

Первым шагом является создание проекта приложения Windows Forms, включающего в себя определение приложения и главную форму для пользовательского интерфейса. The first step is to create the Windows Forms app project, which includes an application definition and the main form for the UI.

Чтобы создать проект приложения Windows Forms на Visual C# с именем HelloComposition, сделайте следующее. To create a new Windows Forms Application project in Visual C# named HelloComposition:

1. Откройте Visual Studio и выберите Файл >Создать >Проект. Open Visual Studio and select File >New >Project.
   Появится диалоговое окно Создать проект. The New Project dialog opens.
2. В категории Установлены разверните узел Visual C# , а затем выберите Windows Desktop. Under the Installed category, expand the Visual C# node, and then select Windows Desktop.
3. Выберите шаблон Приложение Windows Forms (.NET Framework) . Select the Windows Forms App (.NET Framework) template.
4. Введите имя HelloComposition, выберите платформу .NET Framework 4.7.2, а затем нажмите кнопку ОК. Enter the name HelloComposition, select Framework .NET Framework 4.7.2, then click OK.

Visual Studio создаст проект и откроет конструктор для окна приложения по умолчанию, Form1.xaml. Visual Studio creates the project and opens the designer for the default application window named Form1.cs.

Настройка проекта для использования интерфейсов API среды выполнения Windows Configure the project to use Windows Runtime APIs

Чтобы использовать API среды выполнения Windows (WinRT) в приложении Windows Forms, необходимо настроить проект Visual Studio для доступа к среде выполнения Windows. To use Windows Runtime (WinRT) APIs in your Windows Forms app, you need to configure your Visual Studio project to access the Windows Runtime. Кроме того, API Composition активно используют векторы, поэтому нужно добавить ссылки, необходимые для использования векторов. In addition, vectors are used extensively by the Composition APIs, so you need to add the references required to use vectors.

Для решения этих задач предоставляются соответствующие пакеты NuGet. NuGet packages are available to address both of these needs. Установите последние версии этих пакетов, чтобы добавить необходимые ссылки в проект. Install the latest versions of these packages to add the necessary references to your project.

• Microsoft.Windows.SDK.Contracts (требуется задать PackageReference в качестве формата управления пакетами по умолчанию). Microsoft.Windows.SDK.Contracts (Requires default package management format set to PackageReference.)
• System.Numerics.Vectors. System.Numerics.Vectors

Хотя мы рекомендуем использовать для настройки проекта пакеты NuGet, необходимые ссылки можно добавить вручную. While we recommend using the NuGet packages to configure your project, you can add the required references manually. Дополнительные сведения: Улучшение классического приложения для Windows 10. For more info, see Enhance your desktop application for Windows 10. В следующей таблице приведены файлы, на которые необходимо добавить ссылки. The following table shows the files that you need to add references to.

Файл File	Расположение Location
System.Runtime.WindowsRuntime System.Runtime.WindowsRuntime	C:\Windows\Microsoft.NET\Framework\v4.0.30319 C:\Windows\Microsoft.NET\Framework\v4.0.30319
Windows.Foundation.UniversalApiContract.winmd Windows.Foundation.UniversalApiContract.winmd	C:\Program Files (x86)\Windows Kits\10\References \Windows.Foundation.UniversalApiContract C:\Program Files (x86)\Windows Kits\10\References \Windows.Foundation.UniversalApiContract
Windows.Foundation.FoundationContract.winmd Windows.Foundation.FoundationContract.winmd	C:\Program Files (x86)\Windows Kits\10\References \Windows.Foundation.FoundationContract C:\Program Files (x86)\Windows Kits\10\References \Windows.Foundation.FoundationContract
System.Numerics.Vectors.dll System.Numerics.Vectors.dll	C:\WINDOWS\Microsoft.Net\assembly\GAC_MSIL\System.Numerics.Vectors\v4.0_4.0.0.0__b03f5f7f11d50a3a C:\WINDOWS\Microsoft.Net\assembly\GAC_MSIL\System.Numerics.Vectors\v4.0_4.0.0.0__b03f5f7f11d50a3a
System.Numerics.dll System.Numerics.dll	C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework.NETFramework\v4.7.2 C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework.NETFramework\v4.7.2

Создание пользовательского элемента управления для управления взаимодействием Create a custom control to manage interop

Для размещения содержимого, созданного с помощью визуального слоя, создается пользовательский элемент управления, производный от Control. To host content you create with the visual layer, you create a custom control derived from Control. Этот элемент управления предоставляет доступ к дескриптору окна, который нужен, чтобы создать контейнер для содержимого визуального уровня. This control gives you access to a window Handle, which you need in order to create the container for your visual layer content.

Здесь потребуется выполнить большую часть настройки для размещения интерфейсов API Composition. This is where you do most of the configuration for hosting Composition APIs. В этом элементе управления для добавления интерфейсов API Composition в приложение Windows Forms используются службы вызова платформы (PInvoke) и взаимодействие COM. In this control, you use Platform Invocation Services (PInvoke) and COM Interop to bring Composition APIs into your Windows Forms app. Дополнительные сведения о PInvoke и взаимодействии COM см. в разделе Взаимодействие с неуправляемым кодом. For more info about PInvoke and COM Interop, see Interoperating with unmanaged code.

При необходимости сверьтесь с полным кодом в конце руководства, чтобы убедиться в том, что весь код добавлен в соответствующе места при работе с этим руководством. If you need to, check the complete code at the end of the tutorial to make sure all the code is in the right places as you work through the tutorial.

Добавьте в проект новый файл пользовательского элемента управления, производного от Control. Add a new custom control file to your project that derives from Control.

• В обозревателе решений щелкните проект HelloComposition правой кнопкой мыши. In Solution Explorer, right click the HelloComposition project.
• В контекстном меню выберите Добавить >Новый элемент. In the context menu, select Add >New Item. .
• В окне Добавление нового элемента выберите Пользовательский элемент управления. In the Add New Item dialog, select Custom Control.
• Присвойте элементу управления имя CompositionHost.cs, а затем щелкните Добавить. Name the control CompositionHost.cs, then click Add. Файл CompositionHost.cs откроется в представлении конструктора. CompositionHost.cs opens in the Design view.

Перейдите к представлению кода для CompositionHost.cs и добавьте приведенный ниже код в класс. Switch to code view for CompositionHost.cs and add the following code to the class.

Добавьте код в конструктор. Add code to the constructor.

В этом конструкторе вызываются методы InitializeCoreDispatcher и InitComposition. In the constructor, you call the InitializeCoreDispatcher and InitComposition methods. Эти методы создаются на следующих шагах. You create these methods in the next steps.

Инициализируйте поток с помощью CoreDispatcher. Initialize a thread with a CoreDispatcher. Основной диспетчер отвечает за обработку сообщений окон и диспетчеризацию событий интерфейсов API WinRT. The core dispatcher is responsible for processing window messages and dispatching events for WinRT APIs. Новые экземпляры Compositor должны создаваться в потоке с CoreDispatcher. New instances of Compositor must be created on a thread that has a CoreDispatcher.

• Создайте метод InitializeCoreDispatcher и добавьте код для настройки очереди диспетчера. Create a method named InitializeCoreDispatcher and add code to set up the dispatcher queue.

• Для очереди диспетчера требуется объявление PInvoke. The dispatcher queue requires a PInvoke declaration. Поместите это объявление в конец блока кода класса. Place this declaration at the end of the code for the class. (Мы разместим этот код внутри области, чтобы сделать код класса аккуратным.) (We place this code inside a region to keep the class code tidy.)

Теперь очередь диспетчера готова, и можно начать инициализацию и создание содержимого Composition. You now have the dispatcher queue ready and can begin to initialize and create Composition content.

Инициализируйте Compositor. Initialize the Compositor. Compositor — это фабрика, которая создает разные типы в пространстве имен Windows.UI.Composition, охватывающем визуальный уровень, систему эффектов и систему анимации. The Compositor is a factory that creates a variety of types in the Windows.UI.Composition namespace spanning the visual layer, effects system, and animation system. Класс Compositor также управляет временем существования объектов, созданных из фабрики. The Compositor class also manages the lifetime of objects created from the factory.

• Для ICompositorDesktopInterop и ICompositionTarget требуется импорт COM. ICompositorDesktopInterop and ICompositionTarget require COM imports. Поместите этот код после класса CompositionHost внутри объявления пространства имен. Place this code after the CompositionHost class, but inside the namespace declaration.

Создание пользовательского элемента управления для размещения элементов композиции Create a custom control to host composition elements

Рекомендуется разместить код, который создает элементы композиции и управляет ими, в отдельном элементе управления, производном от CompositionHost. It’s a good idea to put the code that generates and manages your composition elements in a separate control that derives from CompositionHost. Это позволяет многократно использовать код взаимодействия, созданный в классе CompositionHost. This keeps the interop code you created in the CompositionHost class reusable.

Здесь создается пользовательский элемент управления, производный от CompositionHost. Here, you create a custom control derived from CompositionHost. Этот элемент управления добавляется на панель элементов Visual Studio, чтобы его можно было добавить в форму. This control is added to the Visual Studio toolbox so you can add it to your form.

Добавьте в проект новый файл пользовательского элемента управления, производного от CompositionHost. Add a new custom control file to your project that derives from CompositionHost.

• В обозревателе решений щелкните проект HelloComposition правой кнопкой мыши. In Solution Explorer, right click the HelloComposition project.
• В контекстном меню выберите Добавить >Новый элемент. In the context menu, select Add >New Item. .
• В окне Добавление нового элемента выберите Пользовательский элемент управления. In the Add New Item dialog, select Custom Control.
• Присвойте элементу управления имя CompositionHostControl.cs, а затем щелкните Добавить. Name the control CompositionHostControl.cs, then click Add. Файл CompositionHostControl.cs откроется в представлении конструктора. CompositionHostControl.cs opens in the Design view.

В области «Свойства» представления конструктора для CompositionHostControl.cs задайте для свойства BackColor значение ControlLight. In the Properties pane for CompositionHostControl.cs design view, set the BackColor property to ControlLight.

Задавать цвет фона необязательно. Setting the background color is optional. Мы делаем это здесь, чтобы пользовательский элемент управления выделялся на фоне формы. We do it here so you can see your custom control against the form background.

Переключитесь на представление кода CompositionHostControl.cs и обновите объявление класса, чтобы он стал производным от CompositionHost. Switch to code view for CompositionHostControl.cs and update the class declaration to derive from CompositionHost.

Обновите конструктор, чтобы вызвать базовый конструктор. Update the constructor to call the base constructor.

Добавление элементов композиции Add composition elements

Теперь, когда инфраструктура настроена, можно добавить содержимое Composition в пользовательский интерфейс приложения. With the infrastructure in place, you can now add Composition content to the app UI.

В этом примере вы добавите в класс CompositionHostControl код, который создает и анимирует простой элемент SpriteVisual. For this example, you add code to the CompositionHostControl class that creates and animates a simple SpriteVisual.

Добавьте элемент композиции. Add a composition element.

В CompositionHostControl.cs добавьте приведенные ниже методы в класс CompositionHostControl. In CompositionHostControl.cs, add these methods to the CompositionHostControl class.

Добавление элемента управления в форму Add the control to your form

Теперь, когда у вас есть пользовательский элемент управления для размещения содержимого Composition, его можно добавить в пользовательский интерфейс приложения. Now that you have a custom control to host Composition content, you can add it to the app UI. Здесь следует добавить экземпляр CompositionHostControl, созданный на предыдущем шаге. Here, you add an instance of the CompositionHostControl you created in the previous step. CompositionHostControl автоматически добавляется на панель элементов Visual Studio в области имя проекта Компоненты. CompositionHostControl is automatically added to the Visual Studio toolbox under project name Components.

В представлении конструктора для Form1.CS добавьте кнопку в пользовательский интерфейс. In Form1.CS design view, add a Button to the UI.

• Перетащите элемент Button с панели элементов на Form1. Drag a Button from the toolbox onto Form1. Поместите его в левый верхний угол формы. Place it in the upper left corner of the form. (Чтобы проверить расположение элементов управления, посмотрите на картинку в начале руководства.) (See the image at the start of the tutorial to check the placement of the controls.)
• В области «Свойства» измените значение свойства Text с Button1 на Add composition element. In the Properties pane, change the Text property from button1 to Add composition element.
• Измените размер элемента Button, чтобы вместить весь текст. Resize the Button so that all the text shows.

Добавьте элемент CompositionHostControl в пользовательский интерфейс. Add a CompositionHostControl to the UI.

• Перетащите CompositionHostControl из панели элементов на форму Form1. Drag a CompositionHostControl from the toolbox onto Form1. Поместите его справа от Button. Place it to the right of the Button.
• Измените размер CompositionHost, чтобы заполнить оставшуюся часть формы. Resize the CompositionHost so that it fills the remainder of the form.

Обработайте событие нажатия кнопки. Handle the button click event.

• В области «Свойства» щелкните значок молнии, чтобы перейти к представлению «События». In the Properties pane, click the lightning bolt to switch to the Events view.
• Из списка событий выберите событие Click, введите Button_Click и нажмите клавишу ВВОД. In the events list, select the Click event, type Button_Click, and press Enter.
• Этот код добавится в Form1.cs. This code is added in Form1.cs:

Добавьте в обработчик нажатия кнопки код для создания новых элементов. Add code to the button click handler to create new elements.

• В Form1.cs добавьте код в обработчик событий Button_Click, созданный ранее. In Form1.cs, add code to the Button_Click event handler you created previously. Этот код вызывает CompositionHostControl1.AddElement для создания нового элемента со случайно заданным размером и смещением. This code calls CompositionHostControl1.AddElement to create a new element with a randomly generated size and offset. (Экземпляр CompositionHostControl был автоматически назван compositionHostControl1 при перетаскивании на форму.) (The instance of CompositionHostControl was automatically named compositionHostControl1 when you dragged it onto the form.)

Теперь выполните сборку приложения Windows Forms и запустите его. You can now build and run your Windows Forms app. Если вы нажмете кнопку, в пользовательском интерфейсе должны появиться анимированные квадраты. When you click the button, you should see animated squares added to the UI.

Дальнейшие действия Next steps

Более полный пример интеграции визуального уровня в Windows Forms, основанный на той же инфраструктуре, доступен на сайте GitHub. For a more complete example that builds on the same infrastructure, see the Windows Forms Visual layer integration sample on GitHub.

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

• Приступая к работе с Windows Forms (.NET) Getting Started with Windows Forms (.NET)
• Взаимодействие с неуправляемым кодом (.NET) Interoperating with unmanaged code (.NET)
• Приступая к работе с приложениями для Windows 10 (UWP) Get started with Windows 10 apps (UWP)
• Улучшение классического приложения для Windows 10 (UWP) Enhance your desktop application for Windows 10 (UWP)
• Пространство имен Windows.UI.Composition (UWP) Windows.UI.Composition namespace (UWP)

Полный код Complete code

Ниже приведен полный код для этого руководства. Here’s the complete code for this tutorial.