A Guide to Using the .NET Upgrade Assistant

Older .NET Framework applications often use outdated APIs, 3rd-party libraries or technologies. They don’t have direct replacements in modern .NET versions. This might come at the cost of security vulnerabilities, slower performance, high infrastructure costs, and a damaged user experience. 

Businesses can upgrade .NET applications with specific tools such as .NET Upgrade Assistant. It helps developers migrate their applications to modern .NET versions. The tool assists in the migration process by automating many of the steps. This helps reduce manual effort and minimize potential errors. Let’s explore it in more detail. 

Types of Applications That .NET Upgrade Assistant Can Migrate

The .NET Migration Assistant can migrate the following types of applications:

• ASP.NET applications 
• Windows Forms applications
• Windows Presentation Foundation (WPF) applications
• Console applications
• Class libraries 
• Azure Functions
• UWP to Windows App SDK (WinUI)
• Xamarin.Forms to .NET MAUI

Some of these applications can be upgraded to newer .NET versions with minimal changes. But some will need third-party libraries and APIs replaced. 

The application might not have a direct migration path to .NET Core or .NET 6+. In this case, developers will need to rewrite parts of the application or explore alternatives like Blazor or gRPC.

Supported .NET Upgrades

Microsoft .NET Upgrade Assistant supports different upgrade paths. It defines which versions of .NET Framework or .NET Core can be upgraded to newer .NET versions. Also, the tool provides different levels of automation for each migration. 

Here’s the list of key upgrade paths supported by .NET Upgrade Assistant:

• .NET Framework (4.6.2, 4.7, 4.8, etc.) to modern .NET versions. But some APIs and dependencies might need a manual approach.
• .NET Core (3.1) to .NET 6+. This is recommended as .NET Core 3.1 is end-of-life. 
• UWP to WinUI 3. WinUI 3 offers modern controls and features to create new desktop applications. 
• Previous .NET version to the latest .NET version. Especially, .NET 5 should be migrated to newer versions as it is out of support. 
• Xamarin Forms to .NET MAUI. .NET MAUI is the new cross-platform UI framework. 

However, some technologies don’t have a direct migration path. For example, there is no direct upgrade for ASP.NET Web Forms. This requires rewriting the UI with Blazor. Or remoting and AppDomains technologies are not available in .NET Core/.NET 6+ at all. 

How to Get the .NET Upgrade Assistant

There are two ways to install .NET Upgrade Assistant:

• Using the extension from Visual Studio inside Visual Studio. In this case, developers don’t need to leave the IDE.
• Installing .NET Global Tool in the upgrade-assistant NuGet package. In this case, ensure you have the .NET SDK as global tools require. If there are any issues, make sure it is up to date. 

CLI Tool vs. Visual Studio Extension

As stated above, .NET Migration Assistant is available in two forms: as a VS extension and as a Command-Line interface (CLI) tool. They have the same purpose. Both tools help developers upgrade their .NET projects to newer versions. But there are some differences between them:

• Interface

The .NET Upgrade Assistant in VS IDE has a graphical user interface. And the CLI tool runs through the command line. This offers a text-based interface.

• Installation

To install .NET Upgrade Assistant in VS, developers simply need to go to its marketplace. With the CLI Tool, they install the Assistant using the command ‘dotnet tool install -g upgrade-assistant’. 

• Workflow

While the VS extension is integrated into the IDE, the CLI tool provides flexibility to work outside Visual Studio. This is suitable for CI/CD pipelines and server environments.

• Automation

VS extension can offer more point-and-click options for less technical users. And the CLI tool might allow for easier automation and scripting of upgrade processes. 

• Accessibility

Visual Studio extension is limited to Windows and Visual Studio users. The CLI tool extends access to any platform that supports .NET. It works on macOS and Linux.

• Updates

To update the VS extension, developers need Visual Studio’s extension manager. Updating the CLI tool requires the command ‘dotnet tool update -g upgrade-assistant’.

Both versions of .NET Upgrade Assistant offer similar features. But developers can choose between them based on their preferences for the working environment and the needs of the upgrade process. 

How to Upgrade a Project

Let’s explore how to upgrade a project using both forms of .NET Upgrade Assistant. 

Upgrade in Visual Studio

To upgrade a project in Visual Studio, ensure you have .NET SDK installed. Also, don’t forget to back up your code before starting the process. 

Then, follow these steps:

1. Open a project in VS.
2. In the Solution Explorer, right-click on the project you want to upgrade.
3. Select “Upgrade” from the context menu. 
4. In the Upgrade tab, choose the appropriate upgrade options based on the project type. 
5. Select “Upgrade project to a newer .NET version” if presented with this option.
6. Choose “In-place project upgrade” when prompted for the upgrade method. Then click “Next”. 
7. Select the target framework and click “Next”. 
8. Review the components to upgrade and click “Upgrade selection”. 
9. Wait for the upgrade process to complete. The tool will upgrade your project file and code to accommodate changes and use newer features.
10. When the upgrade is finished, review the list of processed items and their status.
11. Troubleshoot issues or warnings that the .NET Upgrade Assistant might highlight.

Upgrade from the CLI

To upgrade a project using the .NET Upgrade Assistant CLI tool, you should do the following:

1. Install .NET Upgrade Assistant. Open a command prompt and run:

dotnet tool install -g upgrade-assistant

If it is already installed, make sure you have the latest version.

2. Find your project or solution file in the directory.
3. Run the upgrade command:

upgrade-assistant upgrade

4. The tool will start in interactive mode. Use the arrow keys to select the project you want to upgrade and press Enter. 
5. Choose the target .NET version.
6. Follow the on-screen prompts to proceed with the upgrading process. The tool will walk you through various steps: backing up the project, updating the file, adding or updating package references, updating the C# language version, and applying code fixes for breaking changes.  
7. Review the changes and address issues or warnings. 
8. Build and test your upgraded project to ensure it works as needed. 

And remember to back up your code before starting!

Upgrading Enterprise Projects

.NET Upgrade Assistant is useful for many projects. But it has limitations when it comes to enterprise-level applications. 

The tool doesn’t work properly with large enterprise codebases. It might miss critical issues or offer changes that don’t make sense. The system can be too sophisticated for it. And numerous dependencies can cause problems in its performance efficiency. 

Enterprise applications might require even architectural changes when moving to newer .NET versions. But .NET Upgrade Assistant doesn’t help with this. 

Furthermore, some enterprises might use older technologies like ASMX or ASP.NET Web Forms. And .NET Upgrade Assistant doesn’t fully support them. 

As Softacom, we are experienced in migrating .NET projects. We prioritize minimizing disruption during software transition. We create a modular approach that helps ensure that all business operations continue running without interruptions. Reach out to us. Let’s collaborate to update your .NET software.