UWP manual upgrade

docs/TOC.yml

@@ -69,6 +69,8 @@
                   href: migration/apple-projects.md
                 - name: iOS binding project migration
                   href: migration/ios-binding-projects.md
+            - name: UWP project migration
+              href: migration/uwp-projects.md
             - name: Xamarin.Essentials migration
               href: migration/native-essentials.md
         - name: Xamarin.Forms projects

docs/migration/index.md

@@ -24,6 +24,7 @@ Xamarin projects can run on .NET after completing an upgrade process. The follow
 | Metal                   | ✅       | [Upgrade Xamarin native projects](native-projects.md) |
 | OpenGL                  | ❌ (iOS) | Removed from iOS since OpenTK isn't available |
 | Xamarin.watchOS         | ❌       | Recommendation: bundle Swift extensions with .NET for iOS apps |
+| Xamarin.Forms UWP       | ✅       | [Upgrade Xamarin native projects](native-projects.md) |
 
 <!-- markdownlint-disable MD032 -->
 > [!IMPORTANT]
@@ -33,7 +34,7 @@ Xamarin projects can run on .NET after completing an upgrade process. The follow
 > - Multi-project solutions **don't** need to become a multi-targeted single project.
 <!-- markdownlint-enable MD025 -->
 
-To upgrade your Xamarin native projects to .NET, you'll first have to update the projects to be SDK-style projects and then update your dependencies to .NET 8. For more information, see [Upgrade Xamarin.Android, Xamarin.iOS, and Xamarin.Mac apps to .NET](native-projects.md).
+To upgrade your Xamarin native projects to .NET, you'll first have to update the projects to be SDK-style projects and then update your dependencies to .NET 8. For more information, see [Upgrade Xamarin.Android, Xamarin.iOS, Xamarin.Mac, and UWP projects to .NET](native-projects.md).
 
 The .NET Upgrade Assistant is a command-line tool that can help you upgrade multi-project Xamarin.Forms apps to multi-project .NET Multi-platform App UI (.NET MAUI) apps. After running the tool, in most cases the app will require additional effort to complete the upgrade. For more information, see [Upgrade a Xamarin.Forms app to a .NET MAUI app with the .NET Upgrade Assistant](upgrade-assistant.md).
 

docs/migration/native-projects.md

@@ -1,10 +1,10 @@
 ---
-title: "Upgrade Xamarin.Android, Xamarin.iOS, and Xamarin.Mac projects to .NET"
-description: "Learn how to manually upgrade Xamarin native project files to .NET."
+title: "Upgrade Xamarin.Android, Xamarin.iOS, Xamarin.Mac, and UWP projects to .NET"
+description: "Learn how to manually upgrade Xamarin native projects to .NET."
 ms.date: 02/15/2023
 ---
 
-# Upgrade Xamarin.Android, Xamarin.iOS, and Xamarin.Mac projects to .NET
+# Upgrade Xamarin.Android, Xamarin.iOS, Xamarin.Mac, and UWP projects to .NET
 
 To upgrade your Xamarin native projects to .NET, you must:
 
@@ -14,13 +14,13 @@ To upgrade your Xamarin native projects to .NET, you must:
 > - Update or replace incompatible dependencies with .NET 8 versions.
 > - Compile and test your app.
 
-For most apps, you won't need to change namespaces or undertake other rewrites.
+For most projects, with the exception of UWP projects, you won't need to change namespaces or undertake other rewrites.
 
-To simplify the upgrade process, we recommend creating a new .NET project of the same type and name as your Xamarin native project, and then copying in your code. This is the approach outlined below.
+To simplify the upgrade process, we recommend creating a new .NET or WinUI 3 project of the same type and name as your Xamarin native project, and then copy in your code. This is the approach outlined below.
 
 ## Create a new project
 
-In Visual Studio, create a new .NET project of the same type and name as your Xamarin native project. For example, to upgrade from Xamarin.Android to .NET Android select the **Android Application** project template:
+In Visual Studio, create a new .NET or WinUI 3 project of the same type and name as your Xamarin native project. For example, to upgrade from Xamarin.Android to .NET Android select the **Android Application** project template:
 
 :::image type="content" source="media/new-android-app.png" alt-text="Screenshot of selecting the Android app project template in Visual Studio.":::
 
@@ -42,17 +42,17 @@ The new project should be given the same project and package name as your existi
 ```
 
 > [!IMPORTANT]
-> The target framework moniker (TFM) is what denotes the project as using .NET, in this case .NET 8. Valid TFMs for equivalent Xamarin native projects are net8.0-android, net8.0-ios, net8.0-macos, net8.0-tvos. For information about target frameworks in SDK-style projects, see [Target frameworks in SDK-style projects](/dotnet/standard/frameworks).
+> The target framework moniker (TFM) is what denotes the project as using .NET, in this case .NET 8. Valid TFMs for equivalent Xamarin native projects are net8.0-android, net8.0-ios, net8.0-macos, net8.0-tvos, and net8.0-windows*. For information about target frameworks in SDK-style projects, see [Target frameworks in SDK-style projects](/dotnet/standard/frameworks).
 
 Launch the app to confirm that your development environment can build the app.
 
 ## Merge files
 
-Copy your code and resource files from the folders of your Xamarin native app to identical folders within your new app. You should overwrite any files of the same name.
+Copy your code and resource files from the folders of your Xamarin native project to identical folders within your new app. You should overwrite any files of the same name.
 
 If you have other library projects, you should add them to your new solution and [add project references](/visualstudio/ide/managing-references-in-a-project) to them from your new .NET project.
 
-You'll also need to copy some project properties from your Xamarin native project to your new .NET project, for settings like conditional compilation arguments and code signing. Opening the projects side-by-side in separate Visual Studio instances will enable you to compare the project properties. Alternatively, you can migrate the settings by editing the new project file directly. For more information, see [Xamarin.Android project migration](android-projects.md) and [Xamarin Apple project migration](apple-projects.md).
+You'll also need to copy some project properties from your Xamarin native project to your new .NET project or WinUI 3 project, for settings like conditional compilation arguments and code signing. Opening the projects side-by-side in separate Visual Studio instances will enable you to compare the project properties. Alternatively, you can migrate the settings by editing the new project file directly. For more information, see [Xamarin.Android project migration](android-projects.md), [Xamarin Apple project migration](apple-projects.md), and [Xamarin.Forms UWP project migration](uwp-projects.md).
 
 ## Update dependencies
 
@@ -83,7 +83,7 @@ For information about migrating Xamarin.Essentials code in a .NET Android or .NE
 
 ## Compile and troubleshoot
 
-Once your dependencies are resolved and your code and resource files are added to your .NET native project, you should build your project. Any errors will guide you towards next steps.
+Once your dependencies are resolved and your code and resource files are added to your .NET native or Windows App SDK project, you should build your project. Any errors will guide you towards next steps.
 
 <!-- markdownlint-disable MD032 -->
 > [!TIP]

docs/migration/uwp-projects.md

@@ -0,0 +1,132 @@
+---
+title: "Xamarin.Forms UWP project migration"
+description: "Learn how to migrate a Xamarin.Forms UWP project to a WinUI 3 project."
+ms.date: 11/13/2023
+---
+
+# Xamarin.Forms UWP project migration
+
+A .NET 8 project for a .NET MAUI WinUI 3 app is similar to the following example:
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>WinExe</OutputType> <!-- in Xamarin.Forms this was AppContainerExe -->
+    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
+    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
+    <RootNamespace>MyApp.WinUI</RootNamespace>
+    <ApplicationManifest>app.manifest</ApplicationManifest>
+    <Platforms>x86;x64;ARM64</Platforms>
+    <RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>
+    <UseWinUI>true</UseWinUI>
+    <EnableMsixTooling>true</EnableMsixTooling>
+    <UseMaui>true</UseMaui>
+    <!-- We do not want XAML files to be processed as .NET MAUI XAML -->
+    <EnableDefaultMauiItems>false</EnableDefaultMauiItems>
+  </PropertyGroup>
+</Project>
+```
+
+For a library project, omit the `$(OutputType)` property completely or specify `Library` as the property value.
+
+## Changes to MSBuild properties
+
+While upgrading your project, it's recommended to remove the following UWP MSBuild properties from your project file:
+
+- `WindowsXamlEnableOverview`
+- `AppxPackageSigningEnabled`
+- `GenerateAssemblyInfo`
+
+You'll also need to ensure that the platform architectures in the target project are specified with the following .NET runtime identifiers:
+
+```xml
+<PropertyGroup>
+   <!-- Used in .NET MAUI WinUI projects -->
+   <Platforms>x86;x64;ARM64</Platforms>
+</PropertyGroup>
+```
+
+For more information about runtime identifiers, see [.NET RID Catalog](/dotnet/core/rid-catalog).
+
+## Namespace changes
+
+There are differences in the names of namespaces between UWP and WinUI 3. In many cases it's as easy as changing a namespace name and then your code will compile. For example, you'll need to replace the `Windows.UI.Xaml` namespace with the `Microsoft.UI.Xaml` namespace. Similarly, you'll need to replace the `Windows.UI.Xaml.Controls` namespace with the `Microsoft.UI.Xaml.Controls` namespace.
+
+Other times, the mapping takes a bit more work, and in rare cases requires a change in approach. For more information, see [Mapping UWP APIs and libraries to the Windows App SDK](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/api-mapping-table).
+
+## API changes
+
+You'll need to address any API changes that may affect your app. For example, some types, methods, and properties may have been renamed, deprecated or removed. For information on what's supported when upgrading your UWP project to WinUI 3, see [What's supported when migrating from UWP to WinUI 3](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/what-is-supported). For information about mapping UWP features and APIs to WinUI 3, see [Mapping UWP features to the Windows App SDK](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/feature-mapping-table) and [Mapping UWP APIs and libraries to the Windows App SDK](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/api-mapping-table).
+
+Your project can be made compatible with earlier OS versions by setting the `$(SupportedOSPlatformVersion)` property in your project file:
+
+```xml
+<PropertyGroup>
+   <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">10.0.19041.0</SupportedOSPlatformVersion>
+</PropertyGroup>
+```
+
+The `$(SupportedOSPlatformVersion)` property indicates the minimum OS version required to run your app or library. If you don't explicitly specify this minimum runtime OS version in your project, it defaults to the platform version from the Target Framework Moniker (TFM).
+
+If your project only targets Windows, it's sufficient to omit the platform checking condition and set the `$(SupportedOSPlatformVersion)` property directly:
+
+```xml
+<PropertyGroup>
+   <SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>
+</PropertyGroup>
+```
+
+For more information about the `$(SupportedOSPlatformVersion)` property, see [Support older OS versions](/dotnet/standard/frameworks#support-older-os-versions).
+
+For an app to run correctly on an older OS version, it can't call APIs that don't exist on that version of the OS. However, you can add guards around calls to newer APIs so they are only called when running on a version of the OS that supports them. This can be achieved with the <xref:System.OperatingSystem.IsWindowsVersionAtLeast%2A> method:
+
+```csharp
+if (OperatingSystem.IsWindowsVersionAtLeast(10))
+{
+    // Use the API here
+}
+```
+
+## Remove files
+
+The following files, which are present in Xamarin.Forms UWP projects, don't exist in WinUI 3 projects:
+
+- *MainPage.xaml* and *MainPage.xaml.cs*
+- *AssemblyInfo.cs*
+- *Default.rd.xml*
+
+Therefore, you should remove these files if you've copied them from your UWP project to your WinUI 3 project. Any required business logic contained in these files should be moved elsewhere.
+
+[!INCLUDE [AssemblyInfo changes](includes/assemblyinfo-changes.md)]
+
+## Add files
+
+You'll need to add the following files to your WinUI 3 project:
+
+- [*MauiProgram.cs*](https://github.com/mattleibow/MultiHeadMauiTemplates/blob/main/sample/MauiMultiHeadApp/MauiMultiHeadApp.WinUI/MauiProgram.cs)
+- [*App.xaml*](https://github.com/mattleibow/MultiHeadMauiTemplates/blob/main/sample/MauiMultiHeadApp/MauiMultiHeadApp.WinUI/App.xaml) and [*App.xaml.cs*](https://github.com/mattleibow/MultiHeadMauiTemplates/blob/main/sample/MauiMultiHeadApp/MauiMultiHeadApp.WinUI/App.xaml.cs)
+  - Your Xamarin.Forms UWP project includes *App.xaml* and *App.xaml.cs* files, to which you may have added additional business logic. Therefore, migrate any business logic over to the new versions of these files.
+- [*launchSettings.json*](https://github.com/mattleibow/MultiHeadMauiTemplates/blob/main/sample/MauiMultiHeadApp/MauiMultiHeadApp.WinUI/Properties/launchSettings.json)
+
+These files are required to bootstrap your .NET MAUI WinUI 3 project.
+
+## Changes to Package.appxmanifest
+
+The following changes must be made to your migrated project's *Package.appxmanifest* file:
+
+1. Set the application entry point to `$targetentrypoint$`. For more information, see [Target entry point](https://github.com/mattleibow/MultiHeadMauiTemplates/blob/6e7cb786ed18756749a617d303df46130eab45d9/sample/MauiMultiHeadApp/MauiMultiHeadApp.WinUI/Package.appxmanifest#L34).
+2. Add the `runFullTrust` capability. For more information, see [Run full trust capability](https://github.com/mattleibow/MultiHeadMauiTemplates/blob/6e7cb786ed18756749a617d303df46130eab45d9/sample/MauiMultiHeadApp/MauiMultiHeadApp.WinUI/Package.appxmanifest#L48).
+3. Add the `Windows.Universal` and `Windows.Desktop` target device families. For more information, see [Universal target device family](https://github.com/mattleibow/MultiHeadMauiTemplates/blob/6e7cb786ed18756749a617d303df46130eab45d9/sample/MauiMultiHeadApp/MauiMultiHeadApp.WinUI/Package.appxmanifest#L23) and [Desktop target device family](https://github.com/mattleibow/MultiHeadMauiTemplates/blob/6e7cb786ed18756749a617d303df46130eab45d9/sample/MauiMultiHeadApp/MauiMultiHeadApp.WinUI/Package.appxmanifest#L24).
+
+Making these changes fixes common deployment errors for your app on Windows.
+
+For an example of a compliant *Package.appxmanifest* file, see [*Package.appxmanifest*](https://github.com/mattleibow/MultiHeadMauiTemplates/blob/main/sample/MauiMultiHeadApp/MauiMultiHeadApp.WinUI/Package.appxmanifest).
+
+## Runtime behavior
+
+There are behavioral changes to the `String.IndexOf()` method in .NET 5+ on different platforms. For more information, see [.NET globalization and ICU](/dotnet/standard/globalization-localization/globalization-icu).
+
+## See also
+
+- [Manually upgrade a Xamarin.Forms app to a multi-project .NET MAUI app](multi-project-to-multi-project.md)
+- [Manually upgrade a Xamarin.Forms app to a single project .NET MAUI app](multi-project-to-single-project.md)