Merge pull request #360 from MicrosoftDocs/mcleans/xamlisland-winui

Updated XAML Island instructions

Author: PRMerger18

hub/apps/desktop/modernize/host-custom-control-with-xaml-islands.md

@@ -12,7 +12,7 @@ ms.custom: 19H1
 
 # Host a custom UWP control in a WPF app using XAML Islands
 
-This article demonstrates how to use the [WindowsXamlHost](https://docs.microsoft.com/windows/communitytoolkit/controls/wpf-winforms/windowsxamlhost) control in the Windows Community Toolkit to host a custom UWP control in a WPF app that targets .NET Core 3. The custom control contains several first-party UWP controls and binds a property in one of the UWP controls to a string in the WPF app.
+This article demonstrates how to use the [WindowsXamlHost](https://docs.microsoft.com/windows/communitytoolkit/controls/wpf-winforms/windowsxamlhost) control in the Windows Community Toolkit to host a custom UWP control in a WPF app that targets .NET Core 3. The custom control contains several first-party UWP controls from the Windows SDK and binds a property in one of the UWP controls to a string in the WPF app. This article also demonstrates how to also host a first-party UWP control from the [WinUI library](https://docs.microsoft.com/uwp/toolkits/winui/).
 
 Although this article demonstrates how to do this in a WPF app, the process is similar for a Windows Forms app. For an overview about hosting UWP controls in WPF and Windows Forms apps, see [this article](xaml-islands.md#wpf-and-windows-forms-applications).
 
@@ -101,7 +101,7 @@ Next, add a UWP app project to the same solution as your WPF project. You will r
 
 To host a custom UWP control in your WPF app, you must have the source code for the control so you can compile it with your app. Typically custom controls are defined in a UWP class library project for easy portability.
 
-In this section, you will define a simple custom UWP control in a new class library project. You can alternatively define the custom UWP control in the UWP app project you created in the previous section. However, these steps do this in a separate class library project for illustrative purposes because this is typically how custom controls are implemented for portability. 
+In this section, you will define a simple custom UWP control in a new class library project. You can alternatively define the custom UWP control in the UWP app project you created in the previous section. However, these steps do this in a separate class library project for illustrative purposes because this is typically how custom controls are implemented for portability.
 
 If you already have a custom control, you can use it instead of the control shown here. However, you'll still need to configure the project that contains the control as shown in these steps.
 
@@ -191,6 +191,60 @@ If you already have a custom control, you can use it instead of the control show
 
 6. Build and run your app and confirm that the UWP user control displays as expected.
 
+## Add a control from the WinUI library to the custom control
+
+Traditionally, UWP controls have been released as part of the Windows 10 OS and made available to developers through the Windows SDK. The [WinUI library](https://docs.microsoft.com/uwp/toolkits/winui/) is an alternative approach, where updated versions of the first-party UWP controls from the Windows SDK are distributed in a NuGet package that is not tied to Windows SDK releases. This library also includes new controls that aren't part of the Windows SDK and the default UWP platform. See our [WinUI library roadmap](https://github.com/microsoft/microsoft-ui-xaml/blob/master/docs/roadmap.md) for more details.
+
+This section demonstrates how to add a UWP control from the WinUI library to your user control so you can host this control in your WPF app. 
+
+1. In the UWP app project, install the latest prerelease version of the [Microsoft.UI.Xaml](https://www.nuget.org/packages/Microsoft.UI.Xaml) NuGet package.
+    > [!NOTE]
+    > Make sure you install the latest *prerelease* version. Currently, only prerelease versions of this package will work if you choose to package your app in an [MSIX package](https://docs.microsoft.com/windows/msix) for deployment.
+
+2. In the App.xaml file in this project, add the following child element to the `<xaml:Application>` element.
+
+    ```xml
+    <Application.Resources>
+        <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
+    </Application.Resources>
+    ```
+
+    After adding this element, the contents of this file should now look similar to this.
+
+    ```xml
+    <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. In the UWP class library project, install the latest prerelease version of the [Microsoft.UI.Xaml](https://www.nuget.org/packages/Microsoft.UI.Xaml) NuGet package (the same version that you installed in the UWP app project).
+
+4. In the same project, open the XAML file for the user control and add the following namespace declaration to the `<UserControl>` element.
+
+    ```xml
+    xmlns:winui="using:Microsoft.UI.Xaml.Controls"
+    ```
+
+5. In the same file, add a `<winui:RatingControl />` element as a child of the `<StackPanel>`. This element adds an instance of the [RatingControl](https://docs.microsoft.com/uwp/api/microsoft.ui.xaml.controls.ratingcontrol?view=winui-2.2) class from the WinUI library. After adding this element, the `<StackPanel>` should now look similar to this.
+
+    ```xml
+    <StackPanel Background="LightCoral">
+        <TextBlock>This is a simple custom UWP control</TextBlock>
+        <Rectangle Fill="Blue" Height="100" Width="100"/>
+        <TextBlock Text="{x:Bind XamlIslandMessage}" FontSize="50"></TextBlock>
+        <winui:RatingControl />
+    </StackPanel>
+    ```
+
+6. Build and run your app and confirm that the new rating control displays as expected.
+
 ## Package the app
 
 You can optionally package the WPF app in an [MSIX package](https://docs.microsoft.com/windows/msix) for deployment. MSIX is the modern app packaging technology for Windows, and it is based on a combination of MSI, APPX, App-V and ClickOnce installation technologies.

hub/apps/desktop/modernize/host-standard-control-with-xaml-islands.md

@@ -15,15 +15,25 @@ ms.custom: 19H1
 This article demonstrates two ways to host a standard UWP control (that is, a first-party UWP control provided by the Windows SDK or WinUI library) in a WPF app by using [XAML Islands](xaml-islands.md):
 
 * It shows how to host a UWP [InkCanvas](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.InkCanvas) and [InkToolbar](https://docs.microsoft.com/uwp/api/windows.ui.xaml.controls.inktoolbar) controls by using [wrapped controls](xaml-islands.md#wrapped-controls) in the Windows Community Toolkit. These controls wrap the interface and functionality of a small set of useful UWP controls. You can add them 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 the designer.
+
 * It also shows how to host a UWP [CalendarView](https://docs.microsoft.com/uwp/api/Windows.UI.Xaml.Controls.CalendarView) control by using the [WindowsXamlHost](https://docs.microsoft.com/windows/communitytoolkit/controls/wpf-winforms/windowsxamlhost) control in the Windows Community Toolkit. Because only a small set of UWP controls are available as wrapped controls, you can use [WindowsXamlHost](https://docs.microsoft.com/windows/communitytoolkit/controls/wpf-winforms/windowsxamlhost) to host any other standard UWP control.
 
-Although this article demonstrates how to host these controls in a WPF app, the process is similar for a Windows Forms app.
+To host a UWP control in a WPF app, you'll need the following components. This article provides instructions for creating each of these components.
+
+* The project and source code for your WPF app.
+* A UWP app project that defines an instance of the `Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication` class from the Windows Community Toolkit.
+  > [!NOTE]
+  > To ensure that your app works well in all XAML Island scenarios, your WPF (or Windows Forms) project must have access to a `XamlApplication` object. This object acts as a root metadata provider for loading metadata for UWP XAML types in assemblies in the current directory of your application. The recommended way to do this is to add a **Blank App (Universal Windows)** project to the same solution as your WPF (or Windows Forms) project and revise the default `App` class in this project to derive from `XamlApplication`.
+  >
+  > Although this step isn't required for trivial XAML Island scenarios such as hosting a first-party UWP control, your WPF app needs this `XamlApplication` object to support the full range of XAML Island scenarios, including hosting custom UWP controls. We recommend that you always add a UWP project and define a `XamlApplication` object in any solution in which you are using XAML Islands. Your solution can contain only one project that defines a `XamlApplication` object. All custom UWP controls in your app share the same `XamlApplication` object.
+
+Although this article demonstrates how to host UWP controls in a WPF app, the process is similar for a Windows Forms app.
 
 ## Create a WPF project
 
 Before getting started, follow these instructions to create a WPF project and configure it to host XAML Islands. If you have an existing WPF project, you can adapt these steps and code examples for your project.
 
-1. In Visual Studio 2019, create a new **WPF App (.NET Framework)** or **WPF App (.NET Core)** project.
+1. In Visual Studio 2019, create a new **WPF App (.NET Framework)** or **WPF App (.NET Core)** project. If you want to create a **WPF App (.NET Core)** project, you must first install the latest available preview version of the [.NET Core 3 Preview SDK](https://dotnet.microsoft.com/download/dotnet-core/3.0).
 
 2. Make sure [package references](https://docs.microsoft.com/nuget/consume-packages/package-references-in-project-files) are enabled:
 
@@ -38,6 +48,51 @@ Before getting started, follow these instructions to create a WPF project and co
     > [!NOTE]
     > Windows Forms apps must use the [Microsoft.Toolkit.Forms.UI.Controls](https://www.nuget.org/packages/Microsoft.Toolkit.Forms.UI.Controls) package (version v6.0.0-preview7 or later).
 
+6. Configure your solution to target a specific platform such as x86 or x64. Most XAML Islands scenarios are not supported in projects that target **Any CPU**.
+
+    1. In **Solution Explorer**, right-click the solution node and select **Properties** -> **Configuration Properties** -> **Configuration Manager**. 
+    2. Under **Active solution platform**, select **New**. 
+    3. In the **New Solution Platform** dialog, select **x64** or **x86** and press **OK**. 
+    4. Close the open dialog boxes.
+
+## Create a XamlApplication object in a UWP app project
+
+Next, add a UWP app project to the same solution as your WPF project. You will revise the default `App` class in this project to derive from the `Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication` class provided by the Windows Community Toolkit. Although this step isn't required for trivial XAML Island scenarios such as hosting a single first-party UWP control, your WPF app needs this `XamlApplication` object to support the full range of XAML Island scenarios. We recommend that you always add this project to any solution in which you are using XAML Islands.
+
+1. In **Solution Explorer**, right-click the solution node and select **Add** -> **New Project**.
+2. Add a **Blank App (Universal Windows)** project to your solution. Make sure the target version and minimum version are both set to **Windows 10, version 1903** or later.
+3. In the UWP app project, install the [Microsoft.Toolkit.Win32.UI.XamlApplication](https://www.nuget.org/packages/Microsoft.Toolkit.Win32.UI.XamlApplication) NuGet package (version v6.0.0-preview7 or later).
+4. Open the **App.xaml** file and replace the contents of this file with the following XAML. Replace `MyUWPApp` with the namespace of your UWP app project.
+
+    ```xml
+    <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. Open the **App.xaml.cs** file and replace the contents of this file with the following code. Replace `MyUWPApp` with the namespace of your UWP app project.
+
+    ```csharp
+    namespace MyUWPApp
+    {
+        sealed partial class App : Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication
+        {
+            public App()
+            {
+                this.Initialize();
+            }
+        }
+    }
+    ```
+
+6. Delete the **MainPage.xaml** file from the UWP app project.
+7. Build the UWP app project.
+8. In your WPF project, right-click the **Dependencies** node and add a reference to your UWP app project.
+
 ## Host an InkCanvas and InkToolbar by using wrapped controls
 
 Now that you have configured your project to use UWP XAML Islands, you are now ready to add the [InkCanvas](https://docs.microsoft.com/windows/communitytoolkit/controls/wpf-winforms/inkcanvas) and [InkToolbar](https://docs.microsoft.com/windows/communitytoolkit/controls/wpf-winforms/inktoolbar) wrapped UWP controls to the app.

hub/apps/desktop/modernize/modernize-wpf-tutorial-2.md

@@ -16,6 +16,9 @@ This is the second part of a tutorial that demonstrates how to modernize a sampl
 
 In the fictional scenario of this tutorial, the Contoso development team wants to add support for digital signatures to the Contoso Expenses app. The UWP **InkCanvas** control is a great option for this scenario, because it supports digital ink and AI-powered features like the capability to recognize text and shapes. To do this, you will use the [InkCanvas](https://docs.microsoft.com/windows/communitytoolkit/controls/wpf-winforms/inkcanvas) wrapped UWP control available in the Windows Community Toolkit. This control wraps the interface and functionality of the UWP **InkCanvas** control for use in a WPF app. For more details about wrapped UWP controls, see [Host UWP XAML controls in desktop apps (XAML Islands)](xaml-islands.md).
 
+> [!NOTE]
+> In this tutorial, the WPF app will host only first-party UWP controls from the Windows SDK. To support other XAML Island scenarios including custom UWP controls, the app project must have access to an instance of the `Microsoft.Toolkit.Win32.UI.XamlHost.XamlApplication` class provided by the Windows Community Toolkit. The recommended way to do this is to add a **Blank App (Universal Windows)** project to the same solution as your WPF (or Windows Forms) project and revise the default `App` class in this project. Because this step isn't required for the basic scenario of hosting first-party UWP controls from the Windows SDK, this tutorial omits this step. For more details, see [this article](host-standard-control-with-xaml-islands.md).
+
 ## Configure the project to use XAML Islands
 
 Before you can add an **InkCanvas** control to the Contoso Expenses app, you first need to configure the project to support UWP XAML Islands.