From c99a2c0a2be62188c20dde6a2671831694a845b2 Mon Sep 17 00:00:00 2001
From: Steven White <31261191+stevewhims@users.noreply.github.com>
Date: Mon, 12 Sep 2022 18:30:26 -0700
Subject: [PATCH] scrubbing and editing the topic (#2947)
* scrubbing and editing the topic
* non-interactive mode
---
.../upgrade-assistant.md | 630 +++++++-----------
1 file changed, 246 insertions(+), 384 deletions(-)
diff --git a/hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/upgrade-assistant.md b/hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/upgrade-assistant.md
index 14f56e56e6..003b004d82 100644
--- a/hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/upgrade-assistant.md
+++ b/hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/upgrade-assistant.md
@@ -2,7 +2,7 @@
title: Migrate from UWP to the Windows App SDK with the .NET Upgrade Assistant
description: The [.NET Upgrade Assistant](/dotnet/core/porting/upgrade-assistant-overview) is a command-line tool that can assist with migrating a C# UWP app to a [Windows UI Library (WinUI) 3](/windows/apps/winui/) app that uses the Windows App SDK.
ms.topic: article
-ms.date: 09/08/2022
+ms.date: 09/12/2022
keywords: Windows, App, SDK, migrate, migrating, migration, port, porting, .NET Upgrade Assistant, Upgrade, Assistant, UWP,
ms.author: stwhi
author: stevewhims
@@ -11,484 +11,342 @@ ms.localizationpriority: medium
# Migrate from UWP to the Windows App SDK with the .NET Upgrade Assistant
-The [.NET Upgrade Assistant](/dotnet/core/porting/upgrade-assistant-overview) is a command-line tool that can assist with migrating a C# UWP app to a [Windows UI Library (WinUI) 3](/windows/apps/winui/) app that uses the Windows App SDK.
+The [.NET Upgrade Assistant](/dotnet/core/porting/upgrade-assistant-overview) is a command-line tool that can assist with migrating a C# Universal Windows Platform (UWP) app to a [Windows UI Library (WinUI) 3](/windows/apps/winui/) app that uses the Windows App SDK.
-This article provides:
+Also see the [Upgrade Assistant](https://github.com/dotnet/upgrade-assistant) GitHub repository. Command-line options for running the tool are documented there.
-- What to expect
-- Things to know before starting
-- A demonstration of how to run the tool against a UWP app
-- Troubleshooting tips
+## Install the .NET Upgrade Assistant
-For more information on how to install the tool, see [Overview of the .NET Upgrade Assistant](/dotnet/core/porting/upgrade-assistant-overview).
+For info about installing the tool, see [Overview of the .NET Upgrade Assistant](/dotnet/core/porting/upgrade-assistant-overview).
-## What to expect
+## Summary
-This tool migrates your app by:
+When you use the .NET Upgrade Assistant to migrate your UWP app, here are the high-level steps and stages in the migration process that the tool carries out.
-- Backing up your project.
-- Converts your project to the latest SDK format and cleans up your NuGet package references.
-- Targets .NET 6 and Windows App SDK.
-- Upgrades from WinUI 2 to WinUI 3.
-- Adds new template files such as _App.Xaml_, _MainWindow.Xaml_ and publish profiles.
-- Update namespaces and adds **MainPage** navigation.
-- Attempts to detect and fix APIs that have changed, and marks APIs that are no longer supported, with `//TODO` code comments.
+* Makes a backup (a copy) of your project in a new folder.
+* Migrates your project in-place, in the same folders and files, without renaming folders.
+* Upgrades your project to the latest SDK format, and cleans up NuGet package references.
+* Targets .NET 6, and the Windows App SDK.
+* Upgrades from WinUI 2 to WinUI 3.
+* Adds new template files such as `App.Xaml`, `MainWindow.Xaml`, and publishing profiles.
+* Update namespaces, and adds **MainPage** navigation.
+* Attempts to detect and fix APIs that are different between UWP and the Windows App SDK, and uses **Task List** TODOs to mark APIs that are no longer supported.
-We aim to provide migration guidance in form of warning messages within the tool and TODO comments within your project as the tool tries to migrate the project. In this way, you'll always be in control of your migration. And for the APIs where complete automation isn't possible, plan is to add `//TODO` comments for the developers to know where the work will be needed. A typical `//TODO` comment will also include a link to our existing migration documentation. Check the Task list within the Visual Studio to see all the action items as TODO comments.
+As it runs, the tool also aims to provide migration guidance in the form of warning messages within the tool's output, and **Task List** TODOs in the form of comments within your project's source code (for example, for cases where completely automated migration of your UWP source code isn't possible). A typical **Task List** TODO includes a link to a topic in this migration documentation. As the developer, you're always in control of the migration process.
-> [!NOTE]
-> After a successful run of the tool, you may choose to do the following if needed: move your code from _App.xaml.old.cs_ to _App.xaml.cs_ and move AssemblyInfo.cs from backup
+> [!TIP]
+> To see all of the TODOs that the tool has generated, look in the **Task list** in Visual Studio.
-## Things to know before starting
+> [!NOTE]
+> After the tool has finished running, there are some follow-up steps you can choose to do if needed. You can move your code from `App.xaml.old.cs` to `App.xaml.cs`; and you can restore `AssemblyInfo.cs` from the backup that the tool creates.
-This tool currently supports C#, and in most cases the app will require more effort to complete the migration. The goal of the tool is to convert your project and code, so that it can compile. Some features require you to investigate and fix, and have `//TODO` code comments. For more information about what to consider before migrating, see [What is supported when migrating from UWP to WinUI 3](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/what-is-supported).
+## What the tool supports
-Additionally, you may choose to wait for the next version of .NET Upgrade Assistant tool before you start migrating your app, because of the current limitations of the tool:
+This release of the .NET Upgrade Assistant is currently in preview, and is receiving frequent updates. The tool currently supports only the C# programming language; not C++. And in most cases with this release, your project will require additional effort from you to complete the migration.
-- `ApplicationView` APIs aren't supported.
-- `AppWindow` related APIs aren't supported.
+The tool aims to migrate your project and code so that it compiles. But some features require you to investigate and fix them (via **Task List** TODOs). For more information about what to consider before migrating, see [What is supported when migrating from UWP to WinUI 3](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/what-is-supported).
- The upgrade tries to generate a warning where possible, and deliberately breaks your code so it doesn't compile until you adjust your code.
+Because of the following limitations of the current release of the .NET Upgrade Assistant, you might choose to wait for a future release before migrating your app:
-- Custom views aren't supported.
+* Migrating from [**ApplicationView**](/uwp/api/windows.ui.viewmanagement.applicationview) APIs isn't supported.
+* Migrating from [**AppWindow**](/uwp/api/windows.ui.windowmanagement.appwindow.trycreateasync)-related APIs isn't supported.
- For example, you won't receive a warning or a fix for a `CustomDialog` that extends `MessageDialog` and calls an API incorrectly.
+Where possible, the tool tries to generate a warning; and it intentionally causes your code not to compile until you change it.
-- WinRT Components aren't supported.
-- Multi window apps might not convert correctly.
-- Apps that follow a nonstandard file structure (Such as _App.xaml_, _App.xaml.cs_ missing from the root folder) might not be converted correctly.
+* Custom views aren't supported. For example, you won't receive a warning or a fix for a custom dialog that extends [**MessageDialog**](/uwp/api/windows.ui.popups.messagedialog), and calls an API incorrectly.
+* Windows Runtime Components aren't supported.
+- Multi-window apps might not be migrated correctly.
+- A project that follows a non-standard file structure (such as `App.xaml` and `App.xaml.cs` not being in the root folder) might not be migrated correctly.
-This release is currently in preview, and is receiving frequent updates. If you discover problems using the tool, report them in the tool's [GitHub repository](https://github.com/dotnet/upgrade-assistant). Use the **UWP** area tag so that all UWP related issues can be redirected to us.
+The [Upgrade Assistant GitHub repository](https://github.com/dotnet/upgrade-assistant) documents troubleshooting tips and known issues. If you find any issues while using the tool, please report them in that same GitHub repository, tagging them with an area tag of `UWP`. We appreciate it!
> [!NOTE]
-> You may also refer UWP migration guide [here](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/migrate-to-windows-app-sdk-ovw) that will tell you more about the changes from UWP APIs to the new Windows App SDK supported APIs and capabilities.
+> For guidance about the migration process—and the differences between UWP and Windows App SDK features and APIs—see [Migrate from UWP to the Windows App SDK](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/migrate-to-windows-app-sdk-ovw).
-## A demonstration of how to run the tool against a UWP app
+> [!TIP]
+> You can see what version of the tool you have by issuing the command `upgrade-assistant --version`.
-You can use the [PhotoLab UWP Sample app](https://github.com/microsoft/Windows-appsample-photo-lab.git) project to test upgrading with the Upgrade Assistant.
+## Test drive the tool with the UWP PhotoLab sample
-> [!NOTE]
-> You may also want to see the manual migration of PhotoLab sample app as a case study documented [here](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/case-study-1).
+Let's take the .NET Upgrade Assistant for a test-drive.
+
+As source material, we'll be migrating the UWP [PhotoLab sample](https://github.com/microsoft/Windows-appsample-photo-lab.git) application. PhotoLab is a sample app for viewing and editing image files. It demonstrates XAML layout, data binding, and UI customization features.
+
+Begin by cloning or downloading the PhotoLab sample source code from the link above.
-For the demo, we have a UWP sample app called "PhotoLab", which is an app for viewing and editing image files, demonstrating XAML layout, data binding, and UI customization features. The app will require more effort to complete the migration. This should be familiar if you've used .NET Upgrade Assistant in the past to migrate a WPF or WinForms app from .NET Framework to .NET 6. Now, run it against the PhotoLab app, which is .NET Native UWP project, and follow the steps one-by-one.
+Be aware that after we've used the tool to automate the migration of the app, additional manual effort will be needed to complete the migration.
-## Analyze your app
+> [!NOTE]
+> You can see a case study of the PhotoLab sample being fully migrated manually in [A Windows App SDK migration of the UWP PhotoLab sample app](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/case-study-1).
+
+### The analysis stage
> [!NOTE]
-> At the time of publishing this document, Analyze command is not working as it should. We are working to resolve the same. You may use the upgrade command without skipping the backup step.
+> In the current release of the .NET Upgrade Assistant, the `analyze` command is still in development, and it isn't yet working as intended.
-The .NET Upgrade Assistant tool includes an analyze mode that performs a simplified dry run of upgrading your app. It may provide insights as to what changes may be required before the upgrade is started. Open a terminal and navigate to the folder where the target project or solution is located. Run the `upgrade-assistant analyze` command, passing in the name of the project or solution you're upgrading.
+The `analyze` command performs a simplified dry run of migrating your app. This stage might provide insights as to what changes you might need to make to your project before going ahead with the migration proper.
-For example, running the analyze mode with the [PhotoLab UWP Sample app](https://github.com/microsoft/Windows-appsample-photo-lab.git) produces the following output, indicating that there aren't any changes to be made before upgrading:
+At a command prompt, navigate to the folder where the `.sln` file of the PhotoLab sample is. As shown below, to perform the analyis stage, you issue the command `upgrade-assistant analyze`, and pass in the name of the project or solution you want to analyze. In this test drive, we want to analyze `PhotoLab.sln`.
```console
-> upgrade-assistant analyze .\PhotoLab.sln
-
-[23:08:38 INF] Loaded 7 extensions
-[23:08:53 INF] Using MSBuild from C:\Program Files\dotnet\sdk\6.0.200\
-[23:08:53 INF] Using Visual Studio install from C:\Program Files\Microsoft Visual Studio\2022\Preview [v17]
-[23:09:04 INF] Writing output to .\AnalysisReport.sarif
-[23:09:04 INF] Skip minimum dependency check because Windows App SDK cannot work with targets lower than already recommended TFM.
-[23:09:04 INF] Recommending Windows TFM net6.0-windows because the project either has Windows-specific dependencies or builds to a WinExe
-[23:09:04 INF] Marking package Microsoft.NETCore.UniversalWindowsPlatform for removal based on package mapping configuration UWP
-[23:09:04 INF] Adding package Microsoft.WindowsAppSDK based on package mapping configuration UWP
-[23:09:04 INF] Adding package CommunityToolkit.WinUI.UI.Animations based on package mapping configuration UWP
-[23:09:04 INF] Adding package Microsoft.Graphics.Win2D based on package mapping configuration UWP
-[23:09:04 INF] Marking package Microsoft.Toolkit.Uwp.UI.Animations for removal based on package mapping configuration UWP
-[23:09:04 INF] Marking package Microsoft.UI.Xaml for removal based on package mapping configuration UWP
-[23:09:06 WRN] No version of Microsoft.Toolkit.Uwp.UI.Animations found that supports ["net6.0-windows"]; leaving unchanged
-[23:09:07 INF] Package Microsoft.UI.Xaml, Version=2.4.2 does not support the target(s) net6.0-windows but a newer version (2.7.1) does.
-[23:09:09 INF] Package Microsoft.WindowsAppSDK, Version=1.0.0 does not support the target(s) net6.0-windows but a newer version (1.0.3) does.
-[23:09:10 WRN] No version of CommunityToolkit.WinUI.UI.Animations found that supports ["net6.0-windows"]; leaving unchanged
-[23:09:11 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.3.326103) needs to be added
-[23:09:13 INF] Adding Microsoft.Windows.Compatibility 6.0.0 helps with speeding up the upgrade process for Windows-based APIs
-[23:09:14 WRN] Unable to find a supported WinUI nuget package for Microsoft.Toolkit.Uwp.UI.Animations. Skipping this package.
-[23:09:16 INF] Running analyzers on PhotoLab
-[23:09:25 INF] Identified 7 diagnostics in project PhotoLab
-[23:09:25 INF] Diagnostic UA307 with the message Detect UWP back button generated
-[23:09:25 INF] Diagnostic UA307 with the message Detect UWP back button generated
-[23:09:25 INF] Diagnostic UA309 with the message Detect content dialog api generated
-[23:09:25 INF] Diagnostic UA307 with the message Detect UWP back button generated
-[23:09:25 INF] Diagnostic UA307 with the message Detect UWP back button generated
-[23:09:25 INF] Diagnostic UA309 with the message Detect content dialog api generated
-[23:09:25 INF] Diagnostic UA310 with the message Tries to detect the creation of known classes that implement IInitializeWithWindow generated
-[23:09:25 INF] Analysis Complete, the report is available at .\AnalysisReport.sarif
+> upgrade-assistant analyze PhotoLab.sln
+
+[17:36:32 INF] Loaded 8 extensions
+[17:36:34 INF] Using MSBuild from C:\Program Files\dotnet\sdk\6.0.400\
+[17:36:34 INF] Using Visual Studio install from D:\Program Files\Microsoft Visual Studio\2022\Enterprise [v17]
+[17:36:39 INF] Writing output to D:\Windows-appsample-photo-lab-master\AnalysisReport.sarif
+[17:36:40 INF] Skip minimum dependency check because Windows App SDK cannot work with targets lower than already recommended TFM.
+[17:36:40 INF] Recommending Windows TFM net6.0-windows because the project either has Windows-specific dependencies or builds to a WinExe
+[17:36:40 INF] Marking package Microsoft.NETCore.UniversalWindowsPlatform for removal based on package mapping configuration UWP
+[17:36:40 INF] Adding package Microsoft.WindowsAppSDK based on package mapping configuration UWP
+[17:36:40 INF] Adding package Microsoft.Graphics.Win2D based on package mapping configuration UWP
+[17:36:40 INF] Marking package Microsoft.UI.Xaml for removal based on package mapping configuration UWP
+[17:36:41 WRN] No version of Microsoft.Toolkit.Uwp.UI.Animations found that supports ["net6.0-windows"]; leaving unchanged
+[17:36:41 INF] Package Microsoft.UI.Xaml, Version=2.4.2 does not support the target(s) net6.0-windows but a newer version (2.8.1) does.
+[17:36:41 INF] Package Microsoft.WindowsAppSDK, Version=1.1.0 does not support the target(s) net6.0-windows but a newer version (1.1.4) does.
+[17:36:41 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.4.336902) needs to be added
+[17:36:42 INF] Adding Microsoft.Windows.Compatibility 6.0.0 helps with speeding up the upgrade process for Windows-based APIs
+[17:36:44 WRN] Unable to find a supported WinUI nuget package for Microsoft.Toolkit.Uwp.UI.Animations. Skipping this package.
+[17:36:45 INF] Running analyzers on PhotoLab
+[17:36:54 INF] Identified 0 diagnostics in project PhotoLab
+[17:36:54 INF] Winforms Updater not applicable to the project(s) selected
+[17:36:54 INF] Analysis Complete, the report is available at D:\Windows-appsample-photo-lab-master\AnalysisReport.sarif
```
-There's quite a bit of internal diagnostic information in the output, but some information is helpful. Notice that the analyze mode indicates that the upgrade will recommend that the project target the `net6.0-windows` target framework moniker ([TFM](/dotnet/standard/frameworks)). A console application would probably get the recommendation to upgrade to TFM `net6.0` directly, unless it used some Windows-specific libraries.
+There's quite a bit of internal diagnostic information in the output, but some information is helpful. Notice that the analysis indicates that the migration will recommend that the project target the `net6.0-windows` target framework moniker (TFM) (see [Target frameworks in SDK-style projects](/dotnet/standard/frameworks)). A console application would probably get the recommendation to upgrade to TFM `net6.0` directly, unless it used some Windows-specific libraries.
+
+For PhotoLab, the output indicates that no changes need to be made to the project before migrating.
-If any errors or warnings are reported, take care of them before you start an upgrade.
+> [!TIP]
+> When you're analyzing your own UWP projects, if any errors or warnings are reported, then we recommend that you take care of them before you move on to the next stage.
-## Run upgrade-assistant
+### The migration stage
-Open a terminal and navigate to the folder where the target project or solution is located. Run the `upgrade-assistant upgrade` command, passing in the name of the project or solution you're upgrading.
+As shown below, to perform the migration stage, you issue the command `upgrade-assistant upgrade`, and pass in the name of the project or solution you want to migrate. In this test drive, we want to migrate `PhotoLab.sln`.
-When a project is provided, the upgrade process starts on that project immediately. If a solution is provided, you'll select which project you normally run, known as the upgrade entrypoint. Based on that project, a dependency graph is created and a suggestion as to which order you should upgrade the projects is provided.
+So, still at a command prompt, and still navigated to the folder where the `.sln` file of the PhotoLab sample is, issue this command:
```console
-upgrade-assistant upgrade .\PhotoLab.sln
+upgrade-assistant upgrade PhotoLab.sln
```
-The tool runs and shows you a list of the steps it will do. As each step is completed, the tool provides a set of commands allowing the user to apply or skip the next step or some other option such as:
-
-- Get more information about the step.
-- Change projects.
-- Adjust logging settings.
-- Stop the upgrade and quit.
-
-Pressing Enter without choosing a number selects the first item in the list.
+> [!TIP]
+> For this test drive, the solution contains just one project. Alternatively, you can pass the name of a project to the tool, instead of the name of a solution. However, if you pass the name of a solution that contains multiple projects, then the tool will ask you to indicate which project is the startup project (the tool calls it the *upgrade entrypoint*). Based on that project, the tool creates a dependency graph, and it suggests an order in which to upgrade the projects.
-As each step initializes, it may provide information about what it thinks will happen if you apply the step.
+The .NET Upgrade Assistant runs and prints out the migration steps it will perform. Take this opportunity to read over the list of steps to get an idea for what's involved in the migration process.
-### Select the entrypoint and project to upgrade
+After the list of steps, the tool prints out a menu of commands for you to choose from. You can apply or skip the next step (for example, the first step is to back up your UWP project). Or you can get more information about the next step, adjust logging settings, or stop the upgrade and quit.
-The first step in upgrading the [PhotoLab UWP Sample app](https://github.com/microsoft/Windows-appsample-photo-lab.git) is choosing which project in the solution serves as the entrypoint project. You may notice that there's only one entrypoint, this is because there's only one project in this solution.
+You can enter a number, and press Enter. Or just press Enter to select the first command in the menu.
-```
-[23:29:49 INF] Loaded 7 extensions
-[23:29:52 INF] Using MSBuild from C:\Program Files\dotnet\sdk\6.0.200\
-[23:29:52 INF] Using Visual Studio install from C:\Program Files\Microsoft Visual Studio\2022\Preview [v17]
-[23:30:01 INF] Initializing upgrade step Select an entrypoint
-[23:30:01 INF] Setting entrypoint to only project in solution: .\source\repos\Windows-appsample-photo-lab\PhotoLab\PhotoLab.csproj
-[23:30:01 INF] Initializing upgrade step Select project to upgrade
-[23:30:04 INF] Initializing upgrade step Back up project
-Upgrade Steps
+As each step begins, the tool might provide information about what will likely happen if you apply the step.
-```
+#### Back up project
-After the entrypoint is determined, the next step is to choose which project to upgrade first. However, in this example, the tool determined that there's only one project within the solution, and it should begin upgrading that project.
+In this step, either accept the default path (just press Enter), or enter a custom path.
-### Upgrade the project
+After the step, press Enter again to continue.
-Once a project is selected, a list of upgrade steps the tool will take is listed.
+When the tool moves on to the next step, it prints out the same set of steps again, with indications of which steps are complete, and which steps are yet to take place.
-> [!IMPORTANT]
-> Based on the project you're upgrading, you may or may not see every step listed in this example.
+After the list of steps, the tool again prints out the menu of commands for you to choose from.
-The following output describes the steps involved in upgrading the project:
-
-```
-[23:30:04 INF] Initializing upgrade step Back up project
-
-Upgrade Steps
-
-Entrypoint: .\source\repos\Windows-appsample-photo-lab\PhotoLab\PhotoLab.csproj
-Current Project: .\source\repos\Windows-appsample-photo-lab\PhotoLab\PhotoLab.csproj
-
-1. [Next step] Back up project
-2. Convert project file to SDK style
-3. Clean up NuGet package references
- a. Duplicate reference analyzer
- b. Package map reference analyzer
- c. Target compatibility reference analyzer
- d. Upgrade assistant reference analyzer
- e. Windows Compatibility Pack Analyzer
- f. MyDotAnalyzer reference analyzer
- g. Newtonsoft.Json reference analyzer
- h. Windows App SDK package analysis
- i. Transitive reference analyzer
-4. Update TFM
-5. Update NuGet Packages
- a. Duplicate reference analyzer
- b. Package map reference analyzer
- c. Target compatibility reference analyzer
- d. Upgrade assistant reference analyzer
- e. Windows Compatibility Pack Analyzer
- f. MyDotAnalyzer reference analyzer
- g. Newtonsoft.Json reference analyzer
- h. Windows App SDK package analysis
- i. Transitive reference analyzer
-6. Add template files
-7. Update Windows Desktop Project
- a. Update WinUI namespaces
- b. Update WinUI Project Properties
- c. Update package.appxmanifest
- d. Remove unnecessary files
- e. Update animations xaml
- f. Insert back button in XAML
-8. Update source code
- a. Apply fix for UA0002: Types should be upgraded
- b. Apply fix for UA0012: 'UnsafeDeserialize()' does not exist
- c. Apply fix for UA0014: .NET MAUI projects should not reference Xamarin.Forms namespaces
- d. Apply fix for UA0015: .NET MAUI projects should not reference Xamarin.Essentials namespaces
- e. Apply fix for [UA306_A1, UA306_A2, UA306_A3, UA306_A4, UA306_B, UA306_C, UA306_D, UA306_E, UA306_F, UA306_G, UA306_H, UA306_I]: Replace usage of Windows.UI.Core.CoreDispatcher, Replace usage of Window.Current.Dispatcher, Replace usage of App.Window.Dispatcher, Replace usage of Window.Dispatcher, Replace usage of Windows.Media.Capture.CameraCaptureUI, Replace usage of Micorsoft.UI.Xaml.Controls.InkCanvas, Replace usage of Microsoft.UI.Xaml.Controls.Maps.MapControl, Replace usage of Microsoft.UI.Xaml.Controls.MediaElement, Replace usage of Windows.Graphics.Printing.PrintManager, Replace usage of Windows.Security.Authentication.Web.WebAuthenticationBroker, Replace usage of Windows.UI.Xaml.Media.AcrylicBrush.BackgroundSource, Replace usage of Windows.UI.Shell.TaskbarManager
- f. Apply fix for UA307: Custom back button implementation is needed
- g. Apply fix for UA309: ContentDialog API needs to set XamlRoot
- h. Apply fix for UA310: Classes that implement IInitializeWithWindow need to be initialized with Window Handle
- i. Apply fix for UA311: Classes that implement IDataTransferManager should use IDataTransferManagerInterop.ShowShareUIForWindow
- j. Apply fix for UA312: Interop APIs should use the window handle
- k. Apply fix for [UA313, UA314]: MRT to MRT core migration, MRT to MRT core migration
- l. Apply fix for [UA315_A, UA315_C, UA315_B]: Windows App SDK apps should use Microsoft.UI.Windowing.AppWindow, Windows App SDK apps should use Microsoft.UI.Windowing.AppWindow, Windows App SDK apps should use Microsoft.UI.Windowing.AppWindow
-9. Move to next project
-
-Choose a command:
- 1. Apply next step (Back up project)
- 2. Skip next step (Back up project)
- 3. See more step details
- 4. Configure logging
- 5. Exit
-```
+> [!TIP]
+> If you want to leave the tool to run unattended without needing to repeatedly interact with it, then you can run the tool in non-interactive mode. To do that, provide the `--non-interactive` command-line option. However, when you run `upgrade-assistant` in (the default) interactive mode, you have control over the changes/upgrades performed on your projects. Whereas using `upgrade-assistant` with `--non-interactive` can leave your project in a broken state. We advise you to use the option at your own discretion. All command-line options for running the tool are documented on the [Upgrade Assistant](https://github.com/dotnet/upgrade-assistant) GitHub repository.
-#### Upgrade the project file
+#### Convert project file to SDK style
-The project is upgraded from the .NET Framework project format to the .NET SDK project format.
+In this step, the project is upgraded from the .NET Framework project format to the .NET SDK project format. Here's some typical output from this step.
-```
-[02:14:51 INF] Applying upgrade step Convert project file to SDK style
-[02:14:52 INF] Converting project file format with try-convert, version 0.9.0-dev
-[02:14:54 INF] Skip minimum dependency check because Windows App SDK cannot work with targets lower than already recommended TFM.
-[02:14:54 INF] Recommending Windows TFM net6.0-windows because the project either has Windows-specific dependencies or builds to a WinExe
-[02:14:56 INF] Converting project .\source\repos\Windows-appsample-photo-lab\PhotoLab\PhotoLab.csproj to SDK style
-[02:14:58 INF] Project file converted successfully! The project may require additional changes to build successfully against the new .NET target.
-[02:15:01 INF] Upgrade step Convert project file to SDK style applied successfully
+```console
+[17:39:52 INF] Applying upgrade step Convert project file to SDK style
+[17:39:52 INF] Converting project file format with try-convert, version 0.4.336902+3799b6849a9457619660a355ca9111c050b0ef79
+[17:39:53 INF] Skip minimum dependency check because Windows App SDK cannot work with targets lower than already recommended TFM.
+[17:39:53 INF] Recommending Windows TFM net6.0-windows because the project either has Windows-specific dependencies or builds to a WinExe
+[17:39:55 INF] Converting project D:\Windows-appsample-photo-lab-master\PhotoLab\PhotoLab.csproj to SDK style
+[17:39:55 INF] Project file converted successfully! The project may require additional changes to build successfully against the new .NET target.
+[17:40:00 INF] Upgrade step Convert project file to SDK style applied successfully
```
-Pay attention to the output of each step. The tool will indicate a message and you may need to make changes manually from this step onwards.
+> [!TIP]
+> When you're migrating your own UWP projects, we recommend that you pay attention to the output of each step. If any errors or warnings are reported, then we recommend that you take care of them before you move on to the next step.
-#### Clean up NuGet references
+#### Clean up NuGet package references
-Once the project format has been updated, the next step is to clean up the NuGet package references.
+In this step (and its potentially many sub-steps), the tool cleans up NuGet package references.
-In addition to the packages referenced by your app, the _packages.config_ file contains references to the dependencies of those packages. For example, if you added reference to package **A** which depends on package **B**, both packages would be referenced in the _packages.config_ file. In the new project system, only the reference to package **A** is required. This step analyzes the package references and removes those that aren't required.
+In addition to the packages referenced by your app, the `packages.config` file contains references to the dependencies of those packages. For example, if you added reference to package **A**, which depends on package **B**, then both packages would be referenced in the `packages.config` file. In the new project system, only the reference to package **A** is required. So this step analyzes the package references, and removes those that aren't required.
-```
-[02:18:32 INF] Initializing upgrade step Clean up NuGet package references
-[02:18:32 INF] Initializing upgrade step Duplicate reference analyzer
-[02:18:32 INF] No package updates needed
-[02:18:32 INF] Initializing upgrade step Package map reference analyzer
-[02:18:32 INF] Marking package Microsoft.NETCore.UniversalWindowsPlatform for removal based on package mapping configuration UWP
-[02:18:32 INF] Adding package Microsoft.WindowsAppSDK based on package mapping configuration UWP
-[02:18:32 INF] Adding package CommunityToolkit.WinUI.UI.Animations based on package mapping configuration UWP
-[02:18:32 INF] Adding package Microsoft.Graphics.Win2D based on package mapping configuration UWP
-[02:18:32 INF] Marking package Microsoft.Toolkit.Uwp.UI.Animations for removal based on package mapping configuration UWP
-[02:18:32 INF] Marking package Microsoft.UI.Xaml for removal based on package mapping configuration UWP
-
-[02:19:04 INF] Applying upgrade step Remove package 'Microsoft.NETCore.UniversalWindowsPlatform'
-[02:19:04 INF] Removing outdated package reference: Microsoft.NETCore.UniversalWindowsPlatform, Version=5.3.3
-[02:19:04 INF] Upgrade step Remove package 'Microsoft.NETCore.UniversalWindowsPlatform' applied successfully
-
-
-[02:20:34 INF] Applying upgrade step Remove package 'Microsoft.Toolkit.Uwp.UI.Animations'
-[02:20:34 INF] Removing outdated package reference: Microsoft.Toolkit.Uwp.UI.Animations, Version=1.5.1
-[02:20:34 INF] Upgrade step Remove package 'Microsoft.Toolkit.Uwp.UI.Animations' applied successfully
-
-[02:21:38 INF] Removing outdated package reference: Microsoft.UI.Xaml, Version=2.4.2
-[02:21:38 INF] Upgrade step Remove package 'Microsoft.UI.Xaml' applied successfully
-
-[02:22:13 INF] Adding package reference: Microsoft.WindowsAppSDK, Version=1.0.0
-[02:22:13 INF] Upgrade step Add package 'Microsoft.WindowsAppSDK' applied successfully
-
-[02:22:13 INF] Adding package reference: Microsoft.WindowsAppSDK, Version=1.0.0
-[02:22:13 INF] Upgrade step Add package 'Microsoft.WindowsAppSDK' applied successfully
-Please press enter to continue...
-
-[02:23:04 INF] Adding package reference: CommunityToolkit.WinUI.UI.Animations, Version=7.1.2
-[02:23:04 INF] Upgrade step Add package 'CommunityToolkit.WinUI.UI.Animations' applied successfully
-
-[02:23:42 INF] Adding package reference: Microsoft.Graphics.Win2D, Version=1.0.0.30
-[02:23:42 INF] Upgrade step Add package 'Microsoft.Graphics.Win2D' applied successfully
-
-[02:23:42 INF] Applying upgrade step Package map reference analyzer
-[02:23:42 INF] Upgrade step Package map reference analyzer applied successfully
-
-[02:24:22 INF] Initializing upgrade step Target compatibility reference analyzer
-[02:24:22 INF] No package updates needed
-[02:24:22 INF] Initializing upgrade step Upgrade assistant reference analyzer
-[02:24:23 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.3.326103) needs to be added
-[02:24:23 INF] Initializing upgrade step Add package 'Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers'
-
-[02:28:38 INF] Applying upgrade step Add package 'Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers'
-[02:28:38 INF] Adding package reference: Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, Version=0.3.326103
-[02:28:38 INF] Upgrade step Add package 'Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers' applied successfully
-[02:28:38 INF] Applying upgrade step Upgrade assistant reference analyzer
-[02:28:38 INF] Upgrade step Upgrade assistant reference analyzer applied successfully
-[02:28:52 INF] Applying upgrade step Add package 'Microsoft.Windows.Compatibility'
-[02:28:52 INF] Adding package reference: Microsoft.Windows.Compatibility, Version=6.0.0
-[02:28:52 INF] Upgrade step Add package 'Microsoft.Windows.Compatibility' applied successfully
-[02:28:52 INF] Applying upgrade step Windows Compatibility Pack Analyzer
-[02:28:52 INF] Upgrade step Windows Compatibility Pack Analyzer applied successfully
-[02:29:06 INF] Initializing upgrade step MyDotAnalyzer reference analyzer
-[02:29:06 INF] No package updates needed
-[02:29:06 INF] Initializing upgrade step Newtonsoft.Json reference analyzer
-[02:29:06 INF] No package updates needed
-[02:29:06 INF] Initializing upgrade step Windows App SDK package analysis
-[02:29:06 INF] No package updates needed
-[02:29:06 INF] Initializing upgrade step Transitive reference analyzer
-[02:29:06 INF] No package updates needed
-[02:29:06 INF] Applying upgrade step Clean up NuGet package references
-[02:29:06 INF] Upgrade step Clean up NuGet package references applied successfully
-```
+Your app is still referencing .NET Framework assemblies. Some of those assemblies might be available as NuGet packages. So this step analyzes those assemblies, and references the appropriate NuGet package.
-Your app is still referencing .NET Framework assemblies. Some of those assemblies may be available as NuGet packages. This step analyzes those assemblies and references the appropriate NuGet package.
+> [!TIP]
+> Again, when you're migrating your own UWP projects, pay attention to the output to see if there's any action for you.
-In this example, a user may also see app specific reference such as Microsoft.Toolkit.Uwp.UI.Animations, `CommunityToolkit.WinUI.UI.Animations` and `Microsoft.Graphics.Win2D`.
+#### Update TFM
-#### Handle the TFM
+The tool next changes the target framework moniker (TFM) (see [Target frameworks in SDK-style projects](/dotnet/standard/frameworks)) from .NET Framework to the suggested SDK. In this example, it's `net6.0-windows`.
-The tool next changes the [TFM](/dotnet/standard/frameworks) from .NET Framework to the suggested SDK. In this example, it's `net6.0-windows`.
-
-```
-[02:29:06 INF] Initializing upgrade step Update TFM
-[02:29:06 INF] Skip minimum dependency check because Windows App SDK cannot work with targets lower than already recommended TFM.
-[02:29:06 INF] Recommending Windows TFM net6.0-windows10.0.19041 because the project either has Windows-specific dependencies or builds to a WinExe
+```console
+[17:44:52 INF] Initializing upgrade step Update TFM
+[17:44:53 INF] Skip minimum dependency check because Windows App SDK cannot work with targets lower than already recommended TFM.
+[17:44:53 INF] Recommending Windows TFM net6.0-windows10.0.19041 because the project either has Windows-specific dependencies or builds to a WinExe
```
-#### Upgrade NuGet packages
+#### Update NuGet Packages
Next, the tool updates the project's NuGet packages to the versions that support the updated TFM, `net6.0-windows`.
-```
-[02:29:06 INF] Initializing upgrade step Update NuGet Packages
-[02:29:06 INF] Initializing upgrade step Duplicate reference analyzer
-[02:29:06 INF] No package updates needed
-[02:29:06 INF] Initializing upgrade step Package map reference analyzer
-[02:29:06 INF] No package updates needed
-[02:29:06 INF] Initializing upgrade step Target compatibility reference analyzer
-[02:29:06 INF] No package updates needed
-[02:29:06 INF] Initializing upgrade step Upgrade assistant reference analyzer
-[02:29:06 INF] No package updates needed
-[02:29:06 INF] Initializing upgrade step Windows Compatibility Pack Analyzer
-[02:29:07 INF] No package updates needed
-[02:29:07 INF] Initializing upgrade step MyDotAnalyzer reference analyzer
-[02:29:07 INF] No package updates needed
-[02:29:07 INF] Initializing upgrade step Newtonsoft.Json reference analyzer
-[02:29:07 INF] No package updates needed
-[02:29:07 INF] Initializing upgrade step Windows App SDK package analysis
-[02:29:07 INF] No package updates needed
-[02:29:07 INF] Initializing upgrade step Transitive reference analyzer
-[02:29:07 INF] No package updates needed
-[02:29:07 INF] Applying upgrade step Update NuGet Packages
-[02:29:07 INF] Upgrade step Update NuGet Packages applied successfully
+```console
+[17:44:53 INF] Initializing upgrade step Update NuGet Packages
+[17:44:53 INF] Initializing upgrade step Duplicate reference analyzer
+[17:44:53 INF] No package updates needed
+[17:44:53 INF] Initializing upgrade step Package map reference analyzer
+[17:44:53 INF] No package updates needed
+[17:44:53 INF] Initializing upgrade step Target compatibility reference analyzer
+[17:44:53 INF] No package updates needed
+[17:44:53 INF] Initializing upgrade step Upgrade assistant reference analyzer
+[17:44:53 INF] No package updates needed
+[17:44:53 INF] Initializing upgrade step Windows Compatibility Pack Analyzer
+[17:44:53 INF] No package updates needed
+[17:44:53 INF] Initializing upgrade step MyDotAnalyzer reference analyzer
+[17:44:53 INF] No package updates needed
+[17:44:53 INF] Initializing upgrade step Newtonsoft.Json reference analyzer
+[17:44:53 INF] No package updates needed
+[17:44:53 INF] Initializing upgrade step Windows App SDK package analysis
+[17:44:53 INF] No package updates needed
+[17:44:53 INF] Initializing upgrade step Transitive reference analyzer
+[17:44:53 INF] No package updates needed
+[17:44:53 INF] Applying upgrade step Update NuGet Packages
+[17:44:53 INF] Upgrade step Update NuGet Packages applied successfully
```
-#### Templates, config, and code files
+#### Add template files
-The next few steps may be skipped automatically by the tool if the tool determines there isn't anything to do for your project.
+> [!TIP]
+> When you're analyzing your own UWP projects, the tool might automatically skip the next few steps if it determines that there isn't anything to do for the particular project.
-Once the packages are updated, the next step is to update any template files. In this example, the tool automatically adds necessary publish profiles, _App.xaml.cs_, _MainWindow.xaml.cs_, _MainWindow.xaml_ etc.
+This step involves update any template , config, and code files. In this example, the tool automatically adds necessary publish profiles, `App.xaml.cs`, `MainWindow.xaml.cs`, `MainWindow.xaml`, and others.
-```
-[02:32:44 INF] Applying upgrade step Add template files
-[02:32:44 INF] Added template file app.manifest
-[02:32:44 INF] Added template file Properties\launchSettings.json
-[02:32:44 INF] Added template file Properties\PublishProfiles\win10-arm64.pubxml
-[02:32:44 INF] Added template file Properties\PublishProfiles\win10-x64.pubxml
-[02:32:44 INF] Added template file Properties\PublishProfiles\win10-x86.pubxml
-[02:32:44 INF] File already exists, moving App.xaml.cs to App.xaml.old.cs
-[02:32:44 INF] Added template file App.xaml.cs
-[02:32:44 INF] Added template file MainWindow.xaml.cs
-[02:32:44 INF] Added template file MainWindow.xaml
-[02:32:44 INF] Added template file UWPToWinAppSDKUpgradeHelpers.cs
-[02:32:44 INF] 9 template items added
-[02:32:44 INF] Upgrade step Add template files applied successfully
+```console
+[17:44:53 INF] Initializing upgrade step Add template files
+[17:44:54 INF] 9 expected template items needed
+[17:49:44 INF] Applying upgrade step Add template files
+[17:49:44 INF] Added template file app.manifest
+[17:49:44 INF] Added template file Properties\launchSettings.json
+[17:49:44 INF] Added template file Properties\PublishProfiles\win10-arm64.pubxml
+[17:49:44 INF] Added template file Properties\PublishProfiles\win10-x64.pubxml
+[17:49:44 INF] Added template file Properties\PublishProfiles\win10-x86.pubxml
+[17:49:44 INF] File already exists, moving App.xaml.cs to App.xaml.old.cs
+[17:49:44 INF] Added template file App.xaml.cs
+[17:49:44 INF] Added template file MainWindow.xaml.cs
+[17:49:44 INF] Added template file MainWindow.xaml
+[17:49:44 INF] Added template file UWPToWinAppSDKUpgradeHelpers.cs
+[17:49:44 INF] 9 template items added
+[17:49:44 INF] Upgrade step Add template files applied successfully
```
-#### UWP specific changes
+#### Update Windows Desktop Project (UWP-specific changes)
-The next step for the tool is to update the UWP app to the new Windows Desktop Project.
+In this step the tool updates the UWP project to the new Windows Desktop project.
> [!IMPORTANT]
-> You may choose to skip the step for back button insertion as per your wish. Inserting back button may cause the UI to behave differently. If this happens, remove the stack panel that is inserted as a parent of the back button and reposition the back button where it seems .
+> You can choose to skip the sub-step for back button insertion if that's best for your project. Inserting back button functionality might cause your UI to behave differently. If that happens, then remove the **StackPanel** that's inserted as a parent of the back button, and reposition the back button where it seems best.
-```
-[02:36:53 INF] Applying upgrade step Update WinUI namespaces
-[02:36:53 INF] Upgrade step Update WinUI namespaces applied successfully
+```console
+[17:56:53 INF] Applying upgrade step Update WinUI namespaces
+[17:56:53 INF] Upgrade step Update WinUI namespaces applied successfully
-[02:38:45 INF] Applying upgrade step Update WinUI Project Properties
-[02:38:46 INF] Upgrade step Update WinUI Project Properties applied successfully
+[17:58:45 INF] Applying upgrade step Update WinUI Project Properties
+[17:58:46 INF] Upgrade step Update WinUI Project Properties applied successfully
-[02:39:11 INF] Applying upgrade step Update package.appxmanifest
-[02:39:11 INF] Upgrade step Update package.appxmanifest applied successfully
+[17:59:11 INF] Applying upgrade step Update package.appxmanifest
+[17:59:11 INF] Upgrade step Update package.appxmanifest applied successfully
-[02:39:11 INF] Applying upgrade step Update package.appxmanifest
-[02:39:11 INF] Upgrade step Update package.appxmanifest applied successfully
+[17:59:11 INF] Applying upgrade step Update package.appxmanifest
+[17:59:11 INF] Upgrade step Update package.appxmanifest applied successfully
-[02:39:37 INF] Applying upgrade step Remove unnecessary files
-[02:39:37 INF] Deleting .\source\repos\Windows-appsample-photo-lab\PhotoLab\Properties\AssemblyInfo.cs as it is not required for Windows App SDK projects.
-[02:39:37 INF] Upgrade step Remove unnecessary files applied successfully
+[17:59:37 INF] Applying upgrade step Remove unnecessary files
+[17:59:37 INF] Deleting .\source\repos\Windows-appsample-photo-lab\PhotoLab\Properties\AssemblyInfo.cs as it is not required for Windows App SDK projects.
+[17:59:37 INF] Upgrade step Remove unnecessary files applied successfully
-[02:40:22 INF] Applying upgrade step Update animations xaml
-[02:40:22 INF] Upgrade step Update animations xaml applied successfully
+[18:00:22 INF] Applying upgrade step Update animations xaml
+[18:00:22 INF] Upgrade step Update animations xaml applied successfully
-[02:40:42 INF] Applying upgrade step Insert back button in XAML
-[02:40:42 INF] Upgrade step Insert back button in XAML applied successfully
-[02:40:42 INF] Applying upgrade step Update Windows Desktop Project
-[02:40:42 INF] Upgrade step Update Windows Desktop Project applied successfully
+[18:00:42 INF] Applying upgrade step Insert back button in XAML
+[18:00:42 INF] Upgrade step Insert back button in XAML applied successfully
+[18:00:42 INF] Applying upgrade step Update Windows Desktop Project
+[18:00:42 INF] Upgrade step Update Windows Desktop Project applied successfully
```
-#### Updating the source code
+#### Update source code
-In this step, the tool will try to migrate your code and perform source specific code changes.
+In this important step, the tool will try to migrate your UWP source code to WinUI 3, performing source-specific code changes.
-Code migration for the PhotoLab sample app includes:
+Code migration for the **PhotoLab** sample app includes:
-- Changes to Content Dialog and File Save picker APIs.
-- Xaml update for Animations package.
-- Showing warning messages and adding TODO comments in _DetailPage.xaml_ and _DetailPage.xaml.cs_ and _MainPage.xaml.cs_ for custom back button.
-- Implementing the back button functionality and adding a TODO comment to customize XAML button.
-- A documentation link can be accessed from the CLI tool to study more about for back button implementation.
+* Changes to Content Dialog and File Save picker APIs.
+* XAML update for the Animations package.
+* Showing warning messages, and adding **Task List** TODOs in `DetailPage.xaml`, `DetailPage.xaml.cs`, and `MainPage.xaml.cs` for custom back button.
+* Implementing the back button functionality and adding a **Task List** TODO to customize XAML button.
+* A link to documentation is provided that you can use to learn more about back button implementation.
-```
-[02:41:34 INF] Applying upgrade step Apply fix for UA307: Custom back button implementation is needed
-[02:41:34 WRN] .\source\repos\Windows-appsample-photo-lab\PhotoLab\MainPage.xaml.cs
+Here's the consolidated output from the next few substeps:
+
+```console
+[18:05:45 INF] Applying upgrade step Apply fix for UA307: Custom back button implementation is needed
+[18:05:45 WRN] D:\VisualStudioProjects\Windows-appsample-photo-lab-master\PhotoLab\MainPage.xaml.cs
TODO UA307 Default back button in the title bar does not exist in WinUI3 apps.
- The tool has generated a custom back button "UAGeneratedBackButton" in the XAML file.
+ The tool has generated a custom back button in the MainWindow.xaml.cs file.
Feel free to edit its position, behavior and use the custom back button instead.
- Read: https://aka.ms/UA-back-button
-[02:41:34 INF] Diagnostic UA307 fixed in .\source\repos\Windows-appsample-photo-lab\PhotoLab\MainPage.xaml.cs
-[02:41:34 WRN] .\source\repos\Windows-appsample-photo-lab\PhotoLab\DetailPage.xaml.cs
+ Read: https://docs.microsoft.com/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/case-study-1#restoring-back-button-functionality
+[18:05:45 INF] Diagnostic UA307 fixed in D:\VisualStudioProjects\Windows-appsample-photo-lab-master\PhotoLab\MainPage.xaml.cs
+[18:05:45 WRN] D:\VisualStudioProjects\Windows-appsample-photo-lab-master\PhotoLab\DetailPage.xaml.cs
TODO UA307 Default back button in the title bar does not exist in WinUI3 apps.
- The tool has generated a custom back button "UAGeneratedBackButton" in the XAML file.
+ The tool has generated a custom back button in the MainWindow.xaml.cs file.
Feel free to edit its position, behavior and use the custom back button instead.
- Read: https://aka.ms/UA-back-button
-[02:41:34 INF] Diagnostic UA307 fixed in .\source\repos\Windows-appsample-photo-lab\PhotoLab\DetailPage.xaml.cs
-[02:41:34 INF] Running analyzers on PhotoLab
-[02:41:37 INF] Identified 4 diagnostics in project PhotoLab
-[02:41:37 WRN] .\source\repos\Windows-appsample-photo-lab\PhotoLab\DetailPage.xaml.cs
+ Read: https://docs.microsoft.com/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/case-study-1#restoring-back-button-functionality
+[18:05:45 INF] Diagnostic UA307 fixed in D:\VisualStudioProjects\Windows-appsample-photo-lab-master\PhotoLab\DetailPage.xaml.cs
+[18:05:45 INF] Running analyzers on PhotoLab
+[18:05:48 INF] Identified 4 diagnostics in project PhotoLab
+[18:05:48 WRN] D:\VisualStudioProjects\Windows-appsample-photo-lab-master\PhotoLab\DetailPage.xaml.cs
TODO UA307 Default back button in the title bar does not exist in WinUI3 apps.
- The tool has generated a custom back button "UAGeneratedBackButton" in the XAML file.
+ The tool has generated a custom back button in the MainWindow.xaml.cs file.
Feel free to edit its position, behavior and use the custom back button instead.
- Read: https://aka.ms/UA-back-button
-[02:41:37 INF] Diagnostic UA307 fixed in .\source\repos\Windows-appsample-photo-lab\PhotoLab\DetailPage.xaml.cs
-[02:41:37 INF] Running analyzers on PhotoLab
-[02:41:39 INF] Identified 3 diagnostics in project PhotoLab
-[02:41:39 INF] Upgrade step Apply fix for UA307: Custom back button implementation is needed applied successfully
-
-[02:45:20 INF] Applying upgrade step Apply fix for UA309: ContentDialog API needs to set XamlRoot
-[02:45:20 INF] Diagnostic UA309 fixed in .\source\repos\Windows-appsample-photo-lab\PhotoLab\DetailPage.xaml.cs
-[02:45:20 INF] Diagnostic UA309 fixed in .\source\repos\Windows-appsample-photo-lab\PhotoLab\MainPage.xaml.cs
-[02:45:20 INF] Running analyzers on PhotoLab
-[02:45:23 INF] Identified 1 diagnostics in project PhotoLab
-[02:45:23 INF] Upgrade step Apply fix for UA309: ContentDialog API needs to set XamlRoot applied successfully
-
-[02:45:52 INF] Applying upgrade step Apply fix for UA310: Classes that implement IInitializeWithWindow need to be initialized with Window Handle
-[02:45:52 INF] Diagnostic UA310 fixed in ..\source\repos\Windows-appsample-photo-lab\PhotoLab\DetailPage.xaml.cs
-[02:45:52 INF] Running analyzers on PhotoLab
-[02:45:54 INF] Identified 0 diagnostics in project PhotoLab
-[02:45:54 INF] Applying upgrade step Update source code
-[02:46:00 INF] Upgrade step Update source code applied successfully
-[02:46:00 INF] Upgrade step Apply fix for UA310: Classes that implement IInitializeWithWindow need to be initialized with Window Handle applied successfully
+ Read: https://docs.microsoft.com/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/case-study-1#restoring-back-button-functionality
+[18:05:48 INF] Diagnostic UA307 fixed in D:\VisualStudioProjects\Windows-appsample-photo-lab-master\PhotoLab\DetailPage.xaml.cs
+[18:05:48 INF] Running analyzers on PhotoLab
+[18:05:51 INF] Identified 3 diagnostics in project PhotoLab
+[18:05:51 INF] Upgrade step Apply fix for UA307: Custom back button implementation is needed applied successfully
+
+[18:06:06 INF] Applying upgrade step Apply fix for UA309: ContentDialog API needs to set XamlRoot
+[18:06:06 INF] Diagnostic UA309 fixed in D:\VisualStudioProjects\Windows-appsample-photo-lab-master\PhotoLab\DetailPage.xaml.cs
+[18:06:06 INF] Diagnostic UA309 fixed in D:\VisualStudioProjects\Windows-appsample-photo-lab-master\PhotoLab\MainPage.xaml.cs
+[18:06:06 INF] Running analyzers on PhotoLab
+[18:06:09 INF] Identified 1 diagnostics in project PhotoLab
+[18:06:09 INF] Upgrade step Apply fix for UA309: ContentDialog API needs to set XamlRoot applied successfully
+
+[18:06:27 INF] Applying upgrade step Apply fix for UA310: Classes that implement IInitializeWithWindow need to be initialized with Window Handle
+[18:06:27 INF] Diagnostic UA310 fixed in D:\VisualStudioProjects\Windows-appsample-photo-lab-master\PhotoLab\DetailPage.xaml.cs
+[18:06:27 INF] Running analyzers on PhotoLab
+[18:06:31 INF] Identified 0 diagnostics in project PhotoLab
+[18:06:31 INF] Applying upgrade step Update source code
+[18:06:31 INF] Upgrade step Update source code applied successfully
+[18:06:31 INF] Upgrade step Apply fix for UA310: Classes that implement IInitializeWithWindow need to be initialized with Window Handle applied successfully
```
-#### Completing the upgrade
+#### Move to next project, and Finalize upgrade
-If there are any more projects to migrate, the tool lets you select which project to upgrade next. When there are no more projects to upgrade, the tool brings you to the "Finalize upgrade" step:
+For PhotoLab, there are no more projects to migrate. But when you're analyzing your own UWP projects, that might not always be the case (in which case the tool would now let you select which project to upgrade next). Since there are no more projects to upgrade, the tool takes you to the **Finalize upgrade** step:
-```
-1. [Next step] Finalize upgrade
-
-Choose a command:
- 1. Apply next step (Finalize upgrade)
- 2. Skip next step (Finalize upgrade)
- 3. See more step details
- 4. Configure logging
- 5. Exit
->
-[02:47:13 INF] Applying upgrade step Finalize upgrade
-[02:47:13 INF] Upgrade step Finalize upgrade applied successfully
+```console
+[18:07:00 INF] Applying upgrade step Finalize upgrade
+[18:07:00 INF] Upgrade step Finalize upgrade applied successfully
+
+[18:07:04 INF] Upgrade has completed. Please review any changes.
+[18:07:04 INF] Deleting upgrade progress file at D:\Windows-appsample-photo-lab-master\.upgrade-assistant
```
-Ideally, after successfully running the tool, the user should be able to F5 and run their new WinUI3 desktop project of PhotoLab app. Once the upgrade is complete, the migrated UWP project looks like the following XML:
+At this point, after most of the migration from UWP app to WinUI 3 app has been done, the resulting `.csproj` file looks like this (with some of the build configuration property groups removed for brevity):
```xml
@@ -511,13 +369,13 @@ Ideally, after successfully running the tool, the user should be able to F5 and
-
-
+
-
+
all
+
@@ -528,16 +386,20 @@ Ideally, after successfully running the tool, the user should be able to F5 and
```
-Notice that the .NET Upgrade Assistant also adds analyzers to the project that assist with continuing the upgrade process, such as the `Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers` NuGet package.
+As you can, the project is now referencing the Windows App SDK, WinUI 3, and .NET 6. Now that **PhotoLab** has been migrated, you can take advantage of all of the new features that WinUI 3 apps have to offer, and grow your app with the platform.
+
+Also, the .NET Upgrade Assistant adds analyzers to the project that assist with continuing with the upgrade process. For example, the **Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers** NuGet package.
+
+## Follow-up manual migration
-Also notice that it's using Windows App SDK, WinUI3, and .NET 6. And now, you can take advantage of all new features that modern apps have to offer and grow your app with the platform.
+At this point you can open the migrated **PhotoLab** solution or project, and see the changes that have been made in the source code. The project does build and run, but it needs a little more work to finish hooking things up before the WinUI 3 version looks and behaves like the UWP version.
-## After upgrading
+See the **Task List** in Visual Studio (**View** > **Task List**) for TODOs that you should action to manually complete the migration.
-After you upgrade your projects, you'll need to compile and test them. Most certainly you'll have more work to do in finishing the upgrade. All TODO comments and action items can be seen on the Task List inside the Visual Studio. To open the Task List, press **View** > **TaskList**. It's possible that the .NET Framework version of your app contained library references that your project isn't actually using. You'll need to analyze each reference and determine whether or not it's required. The tool may have also added or upgraded a NuGet package reference to wrong version.
+It's possible that the UWP (.NET Framework) version of your app contained library references that your project isn't actually using. You'll need to analyze each reference, and determine whether or not it's required. The tool might also have added or upgraded a NuGet package reference to the wrong version.
## Troubleshooting tips
There are several known problems that can occur when using the .NET Upgrade Assistant. In some cases, these problems are with the [try-convert tool](https://github.com/dotnet/try-convert) that the .NET Upgrade Assistant uses internally.
-[The tool's GitHub repository](https://github.com/dotnet/upgrade-assistant#troubleshooting-common-issues) has more troubleshooting tips and known issues.
+But for more troubleshooting tips and known issues, see the [Upgrade Assistant](https://github.com/dotnet/upgrade-assistant) GitHub repository.