XAML Islands v1 – Updates and Roadmap
At Microsoft Build, we announced that the Windows 10 May 2019 Update (version 1903) would include XAML Islands v1.
Below you can find more details on the roadmap and two workstreams in progress to complete the developer experience: the .NET wrappers and Visual Studio 2019 support.
What are XAML Islands?
XAML Islands enable .NET and native Win32 applications to host UWP XAML controls. You can enhance the experience and functionality of your existing desktop applications with the latest UI innovations previously only available for UWP apps. For example, you can use the UWP XAML controls such as ColorPicker, InkCanvas, CalendarView, and NavigationView in your existing C++ Win32, Windows Forms, and WPF applications.
With XAML Islands you can modernize your app at your own pace without having to rewrite your app–just use the UWP XAML controls.
How can I use XAML Islands?
The first component is the UWP XAML hosting API. This is a set of Windows 10 APIs (Windows Runtime classes and COM interfaces) that are shipped within the Windows 10 version 1903. If you have a native C++ Win32 app that is using the Common Controls library (Comctl32.dll) or MFC and you need to modernize your UI, use these APIs.
The second component consists of the .NET wrapped controls and the host controls. Those are a set of UWP XAML hosting API wrappers in the Windows Community Toolkit for both Windows Forms and WPF developers.
What are the requirements for using XAML Islands in my application?
- Windows 10 version 1903 and above: Regardless you have a native Win32 app or a .NET app, this first version of XAML Islands only works on apps running in the Windows 10 version 1903 and above.
- Windows 10 SDK version 1903 (10.0.18362): This SDK provides the headers, libraries, metadata, and tools for building Windows 10 apps with XAML Islands.
- Packaged desktop app: Desktop apps can be packaged into a MSIX to access certain Windows 10 APIs like live tiles and notifications. To package your desktop app you should use the Windows Application Packaging Project. Packaging your app doesn’t mean that your desktop app will run in the UWP reduced-privileged sandbox. Instead, your packaged Win32 app will run in a full-trust process. Packaged apps with XAML Islands will have a streamlined developer experience with Visual Studio 2019.
Note: Unpackaged apps will have a limited support in this release, but some scenarios will be possible.
- Visual Studio 2019: Only Visual Studio 2019 will have the toolchain necessary for building desktop apps with XAML Islands.
- .NET Core 3.0: This environment is fully supported for .NET apps. Some scenarios will also work in apps that target the .NET Framework 4.7.2, but there are some limitations for these apps, for example consuming managed 3rd party controls.
What versions of .NET Core and .NET Framework can I target with XAML Islands?
The .NET wrapped controls are supported in .NET Framework and .NET Core 3. The .NET host control (WindowsXamlHost) is available for Windows Forms and WPF. This control allows you to host UWP XAML content. If the UWP XAML content is a control that ships with the Windows 10 platform such as ColorPicker or NavigationView, you can target the .NET Framework 4.7.2 or NET Core 3.
If the UWP XAML content is a UWP user control that is implemented in a 3rd party WinRT component, the version of .NET you can target depends on how the user control was developed. A user control is considered a 3rd party WinRT component if it is defined in one of these ways: in a separate UWP project, in a Nuget Package, or via a link to file.
- If the 3rd party WinRT component is native (written in C++/WinRT), the user control can be consumed by both .NET Framework 4.7.2 and the NET Core 3.
- If the 3rd party WinRT component is managed (for example, written in C#), the user control can be consumed only by .NET Core 3. The full .NET Framework is not fully supported in this scenario, and it requires some cross compilation to work at all.
This is the matrix of platform support for XAML Islands v1:
If your app targets .NET Core 3, regardless of whether the 3rd party WinRT component you are hosting is native or managed, you will get a streamlined developer experience. If your app targets the full .NET Framework, you will get a streamlined developer experience only if your 3rd party WinRT component is native.
How can I use XAML Islands in my native C++ Win32 app?
If you’re a C++ developer, you need to use the UWP XAML hosting APIs. These are some basic steps:
- First initializes the UWP XAML framework in the current thread (you can use thestatic InitializeForCurrentThreadmethod of the WindowsXamlManager class).
- Create a DesktopWindowXamlSource object that requires the HWND of your app. The DesktopWindowXamlSource will create a ChildWindow where you can place the XAML content.
- You need to take care of the keyboard focus when users navigate into and out of the XAML Islands. This DesktopWindowXamlSource object exposes event for routing keyboard focus navigation.
You can find more details at: https://docs.microsoft.com/en-us/windows/apps/desktop/modernize/using-the-xaml-hosting-api
How can I use XAML Islands in my .NET App?
The Windows Community Toolkit version 6.0.0 (in preview right now) provides several NuGet packages for Windows Forms and WPF that you can add to your project.
The WindowXamlHost control is a host control in which you can host all kinds of UWP XAML content.
The wrapped controls wrap most of the events and properties of a small set of specific UWP controls into WPF and Windows Forms controls. These wrapped controls are designed to be used as regular Windows Forms and WPF controls so you don’t need to understand UWP concepts. Currently we provide these wrapped controls:
- InkCanvas wraps the UWP InkCanvas and InkToolbar and provides a surface and toolbars for Ink-based user interaction.
- MediaPlayerElement enables your .NET apps to use modern audio and video codecs and provide better performance for streaming and rendering media content.
- MapControl enables you to use the latest innovations from the mapping platform in your apps, such as more photorealistic maps.
- SwapChainPanel (preview) enables you to add DirectX 12 content in your app.
What modern web view controls are available to desktop applications?
Windows Forms and WPF apps use the WebBrowser control, which uses the Internet Explorer rendering engine and therefore lacks support for HTML5 and other features. The Windows Community Toolkit contains a Windows Forms and WPF wrapper for the UWP WebView control that uses Edge as the rendering engine, so these apps can host web content that requires HTML5.
The Windows Community Toolkit also contains the WebViewCompatible control. This control uses either the WebBrowser or the WebView rendering engine, depending on the version of Windows the app is running on:
- Apps running on Windows 10, version 1803 and later will use the current WebView rendering engine.
- Apps running on earlier versions of Windows, like Windows 8.1, will use the older WebBrowser rendering engine.
Are the XAML Islands using a different thread?
No. XAML Islands run on the same UI thread of your desktop app. You can access all the UWP XAML objects from your code behind without doing any marshalling. This is different from Windows Forms and WPF hosted technologies.
XAML Islands Lab is a comprehensive lab that provides step-by-step instructions for using the wrapped controls and host controls in the Windows Community Toolkit to add UWP controls to an existing WPF line-of-business application. This lab includes the complete code for the WPF application as well as detailed instructions for each step in the process.
This C++ Win32 Sample demonstrates a complete implementation of hosting a UWP user control in an unpackaged C++ Win32 application (that is, an application that is not built into an MSIX package).
For a WPF .NET Core 3 app that consumes a UWP project within a User Control you can use this one:
The Windows community Toolkit contains demos to validate the wrapped control and the host control.
What is your roadmap for XAML Islands v1?
1. Windows 10 May 2019 update contains the first release of XAML Islands (v1).
2. The Windows Community Toolkit, v6.0, will contain the WindowsXamlHost and wrapped controls for the .NET Framework.
- This is planned for this Summer of 2019.
- There will be a preview of v6.1 that will contain the .NET Core 3 version of the WindowsXamlHost and the wrapped controls. This update will be released to align with the .NET Core 3 release – the second half of 2019.
3. Visual Studio 2019 will get an update in the second half of 2019, aligned with the release of .NET Core 3 that will support XAML Islands v1. Remember that only packaged apps will get a streamlined developer experience.
What is your roadmap for XAML Islands v2?
XAML Islands v2 is intended to ship as a part of WinUI 3.0. Therefore, v2 will support the same Windows 10 versions as WinUI 3.0. We are planning to release v3 major release of WinUI during the first half of 2020. WinUI is an open source project, and you can follow the latest roadmap and news at: https://github.com/microsoft/microsoft-ui-xaml/blob/master/docs/roadmap.md
What are the best ways for me to give you feedback about XAML Islands?
- The main channel is our GitHub place: https://github.com/microsoft/microsoft-ui-XAML
- You can also email us to XAML Islands Feedback@microsoft.com
- You can tweet us at @windowsui
- If you have issues with the .NET wrappers you can also reach us at https://github.com/windows-toolkit/Microsoft.Toolkit.Win32