Porting eBook: add upgrade references

docs/architecture/modernize-desktop/example-migration.md

@@ -68,6 +68,9 @@ Or:
 try-convert -w "<path to your solution>"
 ```
 
+> [!NOTE]
+> The try-convert tool is run automatically as part of the [.NET Upgrade Assistant tool](https://aka.ms/dotnet-upgrade-assistant). Consider running the full Upgrade Assistant and not just Try Convert.
+
 After the tool attempts the conversion, reload your files in Visual Studio to run and test. There's a possibility that Try Convert won't be able to perform the conversion due to the specifics of your project. In that case, you can refer the below steps.
 
 #### Migrate manually

docs/architecture/porting-existing-aspnet-apps/additional-migration-resources.md

@@ -27,6 +27,7 @@ Because .NET Core is an open-source project, many issues are discovered, reporte
   - [Docs](https://github.com/dotnet/docs)
   - [Docs Samples](https://github.com/dotnet/samples)
   - [Try Convert](https://github.com/dotnet/try-convert)
+  - [.NET Upgrade Assistant tool](https://aka.ms/dotnet-upgrade-assistant)
 - [.NET Architecture Reference Apps](https://github.com/dotnet-architecture)
   - [eShopModernizing](https://github.com/dotnet-architecture/eShopModernizing)
   - [eShopOnWeb](https://github.com/dotnet-architecture/eShopOnWeb)
@@ -52,6 +53,7 @@ You'll find many other ways to connect with .NET developers on the [.NET Communi
 ## References
 
 - [Overview of porting from .NET Framework to .NET Core](../../core/porting/index.md)
+- [.NET Upgrade Assistant tool](https://aka.ms/dotnet-upgrade-assistant)
 - [Migrate from ASP.NET to ASP.NET Core](../../core/porting/index.md)
 - [.NET Community Resources](https://dotnet.microsoft.com/platform/community)
 

docs/architecture/porting-existing-aspnet-apps/example-migration-eshop.md

@@ -17,6 +17,8 @@ The initial version of the project is shown in Figure 4-1. It's a fairly standar
 
 **Figure 4-1.** The *eShopModernizing* MVC sample project structure.
 
+This chapter demonstrates how to perform many of the upgrade steps by hand. Alternatively, you can use the [.NET Upgrade Assistant tool](https://aka.ms/dotnet-upgrade-assistant) to perform many of the initial steps, like converting the project file, changing the target framework, and updating NuGet packages.
+
 ## Run *ApiPort* to identify problematic APIs
 
 The first step in preparing to migrate is to run the *ApiPort* tool. The tool identifies how many .NET Framework APIs the app calls and how many of these have .NET Standard or .NET Core equivalents. Focus primarily on your own app's logic, not third-party dependencies, and pay attention to `System.Web` dependencies that will need to be ported. The ApiPort tool was introduced in the last chapter on [understanding and updating dependencies](/understand-update-dependencies.md).
@@ -844,6 +846,7 @@ Rather than relying on config files for its settings, WCF clients and other .NET
 ## References
 
 - [eShopModernizing GitHub repository](https://github.com/dotnet-architecture/eShopModernizing)
+- [.NET Upgrade Assistant tool](https://aka.ms/dotnet-upgrade-assistant)
 - [Your API and ViewModels Should Not Reference Domain Models](https://ardalis.com/your-api-and-view-models-should-not-reference-domain-models/)
 - [Developer Exception Page Middleware](/aspnet/core/fundamentals/error-handling#developer-exception-page)
 - [Deep Dive into EF Core HasData](/archive/msdn-magazine/2018/august/data-points-deep-dive-into-ef-core-hasdata-seeding)

docs/architecture/porting-existing-aspnet-apps/incremental-migration-strategies.md

@@ -15,11 +15,13 @@ Consider the challenge of migrating a large ASP.NET 4.5 app. One approach is to
 
 One recent addition to the .NET ecosystem that helps with interoperability between different .NET frameworks is [.NET Standard](https://dotnet.microsoft.com/platform/dotnet-standard). .NET Standard allows libraries to build against the agreed upon set of common APIs, ensuring they can be used in any .NET app. .NET Standard 2.0 is notable because it covers most base class library functionality used by most .NET Framework and .NET Core apps. Unfortunately, the earliest version of .NET with support for .NET Standard 2.0 is .NET Framework 4.6.1, and there are a number of updates in .NET Framework 4.8 that make it a compelling choice for initial upgrades.
 
-One approach to incrementally upgrade a .NET Framework 4.5 system layer-by-layer is to first update its class libraries to .NET Framework 4.8. Then, modify these libraries to be .NET Standard class libraries. Use multi-targeting and conditional compilation, if necessary. This step can be helpful in scenarios where app dependencies require .NET Framework and cannot easily be ported directly to use .NET Standard and .NET Core. Since .NET Framework libraries can be consumed by ASP.NET Core 2.1 apps, the next step is to migrate some or all of the web functionality of the app to ASP.NET Core 2.1 (as described in the [previous chapter](choose-net-core-version.md)).
+One approach to incrementally upgrade a .NET Framework 4.5 system layer-by-layer is to first update its class library dependencies to .NET Framework 4.8. Then, modify these libraries to be .NET Standard class libraries. Use multi-targeting and conditional compilation, if necessary. This step can be helpful in scenarios where app dependencies require .NET Framework and cannot easily be ported directly to use .NET Standard and .NET Core. Since .NET Framework libraries can be consumed by ASP.NET Core 2.1 apps, the next step is to migrate some or all of the web functionality of the app to ASP.NET Core 2.1 (as described in the [previous chapter](choose-net-core-version.md)). This is a "bottom up" approach, starting with low level class library dependencies and working up to the web app entry point.
 
 Once the app is running on ASP.NET Core 2.1, migrating it to ASP.NET Core 3.1 in isolation is relatively straightforward. The most likely challenge during this step is updating incompatible dependencies to support .NET Core and possibly higher versions of .NET Standard. For apps that don't have problematic dependencies on .NET Framework-only libraries, there's little reason to upgrade to ASP.NET Core 2.1. Porting directly to ASP.NET Core 3.1 makes more sense and requires less effort.
 
-By the time the app is running on .NET Core 3.1, migrating to the current .NET 5.0 release is relatively painless. The process primarily involves updating the target framework of your project files and their associated NuGet package dependencies. While there are several [breaking changes to consider](../../core/compatibility/5.0.md), most apps don't require significant modifications to move from .NET Core 3.1 to .NET 5.0. The primary deciding factor in [choosing between .NET Core 3.1 and .NET 5.0 is likely to be support](choose-net-core-version.md).
+By the time the app is running on .NET Core 3.1, migrating to the current .NET 5 release is relatively painless. The process primarily involves updating the target framework of your project files and their associated NuGet package dependencies. While there are several [breaking changes to consider](../../core/compatibility/5.0.md), most apps don't require significant modifications to move from .NET Core 3.1 to .NET 5. The primary deciding factor in [choosing between .NET Core 3.1 and .NET 5 is likely to be support](choose-net-core-version.md).
+
+Instead of a "bottom up" approach, another alternative is to start with the web app (or even the entire solution) and use an automated tool to assist with the upgrade. The [.NET Upgrade Assistant tool](https://aka.ms/dotnet-upgrade-assistant) can be used to help upgrade .NET Framework apps to .NET Core / .NET 5. It automates many of the common tasks related to upgrading apps, such as modifying project file format, setting appropriate target frameworks, updating NuGet dependencies, and more.
 
 ## Migrating slice by slice
 
@@ -32,6 +34,7 @@ Some specific guidance on how to follow this strategy using IIS is covered in [C
 - [What is .NET Standard?](https://dotnet.microsoft.com/platform/dotnet-standard)
 - [Introducing .NET 5](https://devblogs.microsoft.com/dotnet/introducing-net-5/)
 - [Migrate from ASP.NET Core 3.1 to 5.0](/aspnet/core/migration/31-to-50)
+- [.NET Upgrade Assistant tool](https://aka.ms/dotnet-upgrade-assistant)
 
 >[!div class="step-by-step"]
 >[Previous](choose-net-core-version.md)

docs/architecture/porting-existing-aspnet-apps/migration-considerations.md

@@ -11,7 +11,7 @@ The most fundamental question teams must answer when it comes to porting their a
 
 ## Is migration to .NET Core appropriate?
 
-Let's start with some of the reasons why you might want to move to .NET Core. There are quite a few, so don't consider this list exhaustive.
+Let's start with some of the reasons why you might want to move to .NET Core (or .NET 5). There are quite a few, so don't consider this list exhaustive.
 
 ### Cross-platform support
 

docs/architecture/porting-existing-aspnet-apps/understand-update-dependencies.md

@@ -17,16 +17,24 @@ After identifying the sequence in which the app's individual projects must be mi
 
 Large apps typically involve multiple projects, and most projects other than the ASP.NET MVC web project are likely to be class libraries. Class libraries tend to be the easiest to port between .NET platforms, especially compared to ASP.NET projects, which are among the most difficult (and typically need to be re-created).
 
-Teams can consider the [try-convert tool](https://github.com/dotnet/try-convert) for migrating class libraries to .NET Core. The try-convert tool analyzes a .NET Framework project file and attempts to migrate it to the .NET Core project file format, making any modifications it can safely perform in the process. This tool won't work on an ASP.NET project, but can help speed up the process of migrating class libraries.
+Teams can consider the [try-convert tool](https://github.com/dotnet/try-convert) or the [.NET Upgrade Assistant tool](https://aka.ms/dotnet-upgrade-assistant) for migrating class libraries to .NET Core. These tools analyze a .NET Framework project file and attempt to migrate it to the .NET Core project file format, making any modifications it can safely perform in the process. The tools may require some manual assistance to work with ASP.NET projects, but can usually help speed up the process of migrating class libraries.
 
-The try-convert tool is deployed as a .NET Core command line tool. It only runs on Windows, since it's designed to work with .NET Framework apps. You can install it by running the following command from a command prompt:
+The try-convert and Upgrade Assistant tools are deployed as .NET Core command line tools. They only run on Windows, since they're designed to work with .NET Framework apps. You can install try-convert by running the following command from a command prompt:
 
 ```dotnetcli
 dotnet tool install -g try-convert
 ```
 
 Once you've successfully installed the tool, you can run `try-convert` in the folder where the class library's project file is located.
 
+Install the .NET Upgrade Assistant with the following command (after installing try-convert):
+
+```dotnetcli
+dotnet tool install -g upgrade-assistant
+```
+
+Run the tool with the command `upgrade-assistant <project>` in the folder where the project file is located.
+
 ## Update NuGet package dependencies
 
 Analyze your use of third-party NuGet packages and determine if any of them don't yet support .NET Standard (or do support it but only with a new version). It can be helpful to [update NuGet packages to use `<PackageReference>` syntax using Visual Studio's converter tool](/nuget/consume-packages/migrate-packages-config-to-package-reference), so that top-level dependencies are visible. Next, check whether the current or later versions of these packages support .NET Core or .NET Standard. This information can be found on [nuget.org] or within Visual Studio for each package.
@@ -45,6 +53,7 @@ The next chapter digs into details of how to migrate from ASP.NET MVC and Web AP
 
 ## References
 
+- [.NET Upgrade Assistant tool](https://aka.ms/dotnet-upgrade-assistant)
 - [try-convert tool](https://github.com/dotnet/try-convert)
 - [apiport tool](https://github.com/microsoft/dotnet-apiport)