Host UWP XAML controls in desktop apps (XAML Islands)

Starting in Windows 10, version 1903, you can host UWP controls in non-UWP desktop applications using a feature called XAML Islands. This feature enables you to enhance the look, feel, and functionality of your existing desktop applications with the latest Windows 10 UI features that are only available via UWP controls. This means that you can use UWP features such as Windows Ink and controls that support the Fluent Design System in your existing WPF, Windows Forms, and C++ Win32 applications.

We provide several ways to use XAML Islands in your WPF, Windows Forms, and C++ Win32 applications, depending on the technology or framework you are using.

Note

If you have feedback about XAML Islands, create a new issue in the Microsoft.Toolkit.Win32 repo and leave your comments there. If you prefer to submit your feedback privately, you can send it to XamlIslandsFeedback@microsoft.com. Your insights and scenarios are critically important to us.

How do XAML Islands work?

Starting in Windows 10, version 1903, we provide two ways to use XAML Islands in your WPF, Windows Forms, and C++ Win32 applications:

  • The Windows SDK provides several Windows Runtime classes and COM interfaces that your application can use to host any UWP control that derives from Windows.UI.Xaml.UIElement. Collectively, these classes and interfaces are called the UWP XAML hosting API, and they enable you to host UWP controls in any UI element in your application that has an associated window handle (HWND). For more information about this API, see Using the XAML hosting API.

  • The Windows Community Toolkit also provides additional XAML Island controls for WPF and Windows Forms. These controls use the UWP XAML hosting API internally and implement all of the behavior you would otherwise need to handle yourself if you used the UWP XAML hosting API directly, including keyboard navigation and layout changes. For WPF and Windows Forms applications, we strongly recommend that you use these controls instead of the UWP XAML hosting API directly because they abstract away many of the implementation details of using the API. Note that as of Windows 10, version 1903, these controls are available as a developer preview.

Note

C++ Win32 desktop applications must use the UWP XAML hosting API to host UWP controls. The XAML Island controls in the Windows Community Toolkit are not available for C++ Win32 desktop applications.

There are two types of XAML Island controls provided by the Windows Community Toolkit for WPF and Windows Forms applications: wrapped controls and host controls.

Wrapped controls

WPF and Windows Forms applications can use a selection of wrapped UWP controls in the Windows Community Toolkit. These are called wrapped controls because they wrap the interface and functionality of a specific UWP control. You can add these controls directly to the design surface of your WPF or Windows Forms project and then use them like any other WPF or Windows Forms control in your designer.

The following wrapped UWP controls for implementing XAML Islands are currently available for WPF and Windows Forms applications.

Control Minimum supported OS Description
InkCanvas
InkToolbar
Windows 10, version 1903 Provide a surface and related toolbars for Windows Ink-based user interaction in your Windows Forms or WPF desktop application.
MediaPlayerElement Windows 10, version 1903 Embeds a view that streams and renders media content such as video in your Windows Forms or WPF desktop application.
MapControl Windows 10, version 1903 Enables you to display a symbolic or photorealistic map in your Windows Forms or WPF desktop application.

In addition to the wrapped controls for XAML Islands, the Windows Community Toolkit also provides the following controls for hosting web content.

Control Minimum supported OS Description
WebView Windows 10, version 1803 Uses the Microsoft Edge rendering engine to show web content.
WebViewCompatible Windows 7 Provides a version of WebView that is compatible with more OS versions. This control uses the Microsoft Edge rendering engine to show web content on Windows 10 version 1803 and later, and the Internet Explorer rendering engine to show web content on earlier versions of Windows 10, Windows 8.x, and Windows 7.

Host controls

For scenarios beyond those covered by the available wrapped controls, WPF and Windows Forms applications can also use the WindowsXamlHost control in the Windows Community Toolkit. This control can host any UWP control that derives from Windows.UI.Xaml.UIElement, including any UWP control provided by the Windows SDK as well as custom user controls. This control supports Windows 10 Insider Preview SDK build 17709 and later releases.

Architecture overview

Here's a quick look at how these controls are organized architecturally.

Host control Architecture

The APIs that appear at the bottom of this diagram ship with the Windows SDK. The wrapped controls and host controls are available via Nuget packages in the Windows Community Toolkit.

Feature roadmap

As of the release of Windows 10, version 1903, the wrapped controls and host controls in the Windows Community Toolkit are still in developer preview until the version 1.0 release of the controls is available.

  • Version 1.0 of the controls for the .NET Framework 4.6.2 and later are planned to be released in the 6.0 release of the toolkit.
  • Version 1.0 of the controls for .NET Core 3 are planned for a later release of the toolkit.
  • If you want to try the latest previews of the version 1.0 releases of these controls for the .NET Framework and .NET Core 3, see the 6.0.0-preview3 NuGet packages in the UWP Community Toolkit gallery.

Requirements

XAML Islands require Windows 10, version 1903, and later. To use XAML Islands in your application, you must first set up your project.

Step 1: Modify your project to use Windows Runtime APIs

For instructions, see this article.

Step 2: Enable XAML Island support in your project

Make one of the following changes to your project to enable XAML Island support. For more details, see this blog post.

Option 1: Package your application in an MSIX package

Install the Windows 10, version 1903 SDK (or a later release). Then, package your application in an MSIX package by adding a Windows Application Packaging Project to your solution and adding a reference to your WPF or Windows Forms project.

Option 2: Set the maxVersionTested value in your assembly manifest

If you don't want to package your application in an MSIX package, you can add a side-by-side assembly manifest to your project and add the maxVersionTested value to the manifest to specify that your application is compatible with Windows 10, version 1903 or later.

  1. If you don't already have an assembly manifest in your project, add a new XML file to your project and name it app.manifest. For a WPF or Windows Forms application, make sure you also assign the Manifest property to .app.manifest in the Application page of your project properties.

  2. In your assembly manifest, include the compatibility element and the child elements shown in the following example. Replace the Id attribute of the maxVersionTested element with the version number of Windows 10 you are targeting (this must be Windows 10, version 1903 or a later release).

    <?xml version="1.0" encoding="UTF-8"?>
    <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
        <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
            <application>
                <!-- Windows 10 -->
                <maxversiontested Id="10.0.18362.0"/>
                <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
            </application>
        </compatibility>
    </assembly>
    

Additional resources

For more background information and tutorials about using XAML Islands, see the following articles and resources: