Today we’re excited to introduce a tool we’ve been working on to help you upgrade your .NET Framework-based applications to .NET 5 called the .NET Upgrade Assistant. The .NET Upgrade Assistant is a .NET global command-line tool that gives you a guided experience for incrementally upgrading your applications. It brings an existing tool called try-convert together with step-by-step instructions and recommendations. This means you can instead focus your upgrading time on the more specific changes to your application and the application model rather than on the repetitive tasks across the projects in your solution.
Currently in preview, the .NET Upgrade Assistant determines which projects need to be upgraded and recommends the order they should be upgraded in. The tool automates more tasks in the upgrade process that you would normally do manually like upgrading to the new SDK-style project format, re-targeting them to .NET 5 and updating NuGet package dependencies. The tool also provides you with recommendations and fixes for project files, configuration, and source code. The difference between this tool and others is that you can see the recommendations every step of the way and you can choose what and how your code is upgraded.
The tool supports multiple project types. It’s ready to help you upgrade your ASP.NET MVC, Windows Forms, and WPF apps, in addition to console apps and libraries. We’ll add more project types in later previews.
Why did we build this?
We heard from customers that they want to upgrade, but it’s currently too time consuming with our current set of porting tools, particularly for large ASP.NET applications. Companies typically want to move to .NET Core / .NET 5 so they can host applications on Linux and benefit from performance gains to cut hosting and compute costs. When companies are planning their modernization strategies, often the costing is started by taking one application through the upgrade process as a proof of concept. If that takes too long, then the cost of upgrading everything is too high. The .NET Upgrade Assistant aims to cut the time considerably and automate away more of the manual work.
We worked closely with Optimizely (Episerver) to upgrade their large ASP.NET application portfolio and built this tool with their close collaboration. Their solutions include content management, e-commerce and digital marketing platforms. With their help we refined how the .NET Upgrade Assistant works and added extensibility points so that they could hook their own upgrade guidance and code patterns into the assistant. This makes it easier for their customers to also upgrade their solutions as well. You can read more on their website.
How does it work?
We recommend first becoming familiar with the overall upgrading process and determine upgrade feasibility. Once you’ve done that, you’re ready to install the .NET Upgrade Assistant and to start upgrading your projects to .NET 5. If you point it at a solution, it will analyze your dependencies and determine the order of projects to upgrade. Here’s what it will do.
- Backup your projects. Ensuring you have a backup (and your code is in source control), means you can easily rollback to a working state if you need to at any point. Remember, once the tool is finished running, it will be partially upgraded to .NET 5. You’ll still need to make some manual changes.
- Update the projects to be SDK-style projects. .NET 5 uses a simplified and different project file format compared to .NET Framework. This step uses the try-convert tool that was installed as part of the pre-requisites to move all your projects over to the new SDK-style project format. Prior to the .NET Upgrade Assistant, you would have had to determine yourself, the best order to upgrade your projects based on their dependencies. Imagine you had 20 projects in a solution. You would have had to build a dependency graph to understand the dependencies between the projects, figure out the best order to upgrade them, and then run the
try-converttool against each project. The tool, particularly at this step, saves you so much time and effort, especially if you have very large solutions with a lot of projects in it. - Update the target framework (Update TFM). At this step, the tool will re-target your projects to target .NET 5.0. Read more about target frameworks.
- Update NuGet packages in your projects. Here, NuGet package dependencies are updated to versions that are compatible with .NET 5.0. There are a few rules that are applied to make these updates:
- It removes package references that appear to be transitive so that only top-level dependencies are included in the csproj.
- If a referenced NuGet package isn’t compatible with the target NET version and a newer version of the NuGet package is, the package automatically updates the version to the first major version that will work.
- It will replace NuGet references based on specific replacement packages listed in configuration files.
- Additional packages are now added and referenced, such as the Windows Compatibility Pack for Windows apps. For ASP.NET Framework apps, some packages are removed that aren’t need anymore (e.g. structuremap.web and Autofac.Mvc5). The .NET Upgrade Assistant analyzer package is added here too, which will help fix specific parts in your code that aren’t compatible in .NET 5 in the following steps. These analyzers are specific to project types and provide you with compile time feedback for anything the tool couldn’t update.
- Add template files. For some application models like ASP.NET apps, common template files (like
Program.csandStartup.cs) are missing in older framework app versions, so they are added at this step and simple updates are also made based on recognizedweb.configorapp.configvalues. - Update C# source. Now that all your projects have been upgraded to .NET 5 and references upgraded when the tool could help, it’s time to make some specific fixes to the C# code. Right now, the tool offers a set of ASP.NET analyzers, which will apply fixes for known patterns that where in .NET Framework that have .NET 5 equivalents. You can pick and choose the analyzers you want to run on your code or run all of them to catch any usages of older .NET Framework patterns. Some examples for ASP.NET include:
- Apply fix for AM0001: ASP.NET Core projects should not reference ASP.NET namespaces
- Apply fix for AM0002: HtmlString types should be replaced with Microsoft.AspNetCore.Html.HtmlString
- Apply fix for AM0003: ActionResult types should come from the Microsoft.AspNetCore.Mvc namespace
The team will add analyzers for more project types in upcoming previews.
- Move to next project. If your solution includes multiple projects, this is where you’d move on to working on the next project that was recommended in the beginning.
Remember, that the tool is not intended to completely upgrade .NET Framework applications to .NET 5. Manual changes will still need to be made because these require knowledge of the app and how it’s intended to function. We recommend that once you’re finished in the tool, you head back to Visual Studio and attempt to build your code. Look for warnings in the Error List window of Visual Studio to help you identify other parts of your code that might not be supported in .NET 5. You should also check any NuGet packages that might have been updated as sometimes there are breaking changes and you may need to revert to an older version.
You can find documentation and samples on using the .NET Upgrade Assistant in the repo. Also, you can watch my session from .NET Conf: Focus on Windows last week where I walked through the process with Windows desktop apps.
Give us feedback
The .NET Upgrade Assistant is open source on GitHub and we’re currently taking feedback. We’ll be open for code contributions very soon. Head on over to https://github.com/dotnet/upgrade-assistant to try out the tool and engage with the team.
Happy upgrading!
What is a “transitive dependency” in a “Update NuGet Packages” step. Thanks for clarifying, especially with regard to the consequences.
Can i upgrade a WPF project made with Visual Basic language?
I recently migrated a small application my company has to .NET5. I used the upgrade assistant, making each of the projects an SDK style and was up and running. I could build the application in VS and run it without any issues. However when it came time to update the installer package and try installing it on another machine it crashes. I included the "net5.0-windows" sub folder that is now part of the applications output....
Gave me the transitive references error and died.
Is there any way to use this tool without retargetting to .NET 5?
Until there’s support for viewing and exporting SSRS reports in .NET 5, we have to stick with .NET Framework.
Using Hans van Bakel’s “migrate-2019” tool, I can convert most projects to the new SDK-style format without changing the target framework. It would be a shame if the “official” tool didn’t support doing the same.
The underlying tool that the Upgrade Assistant uses to port project files is called try-convert and it has the flag
--keep-current-tfmsthat you can optionally specify. For your scenario it’s currently better to use try-convert just for these SSRS projects.Command line? What is this – the 1980s? At least come into the 21st century of productivity with a GUI to complement a command line.
Hi Jeff - The team does desire to be able to bring a UI into a future preview release. We felt it was important to get the fundamentals working before focusing on building a UI. We also want to be able to assist more in the upfront planning of an upgrade by doing some pre-analysis of an application's dependencies. If you have any others thoughts or ideas to share with us, we'd love to hear...
Are there any plans for this to work with .NET Framework projects written in VB.NET? Not every project is written in C#. It’s been a bit of a nightmare trying to port existing VB.NET stuff to .NET5 but only as much as will have been for a C# programmer. This tools look very promising but surely must support all of the Roslyn types? Please??
Hi Rik, I was told at DevConf they will add VB.NET support to the tool. I’m also waiting for it!
Hi Rik and Sergio – We’re currently working to unblock the tool being run on VB.NET apps, but we uncovered some limitations. You can see where our progress is via this issue: https://github.com/dotnet/upgrade-assistant/issues/265.
I really do not know to thank you, I had a small (solution with 3 projects) but really old project (done in 2010) I installed the tool and I followed the steps, and I did not believe my eyes, the upgrade was done completely automatically after the tool steps are done, I did not have to edit a line, I build it and it succeeded, boom, Thank you so much, great work.
Problem with .NET 5/Core is that it forces you to re-write your app. Backward compatibility OR automatic upgrade is a MUST. Not allowing that shows serious lack of understanding among the leaders/drivers of the entire .NET project about how businesses actually make decisions -- that business drivers do not care about new tech buzz which in the end, produces the same end results from a business point of view. Async features are...
Pretty well said. I know hindsight is easy but you're right, this tool should have been there from the start and maybe even before (i.e. when .NET5 was in alpha\beta). It's been, um, painful trying to convert old stuff to this new format.
What I would say is that if you can invest the time/money, it's probably worth it longer-term since that's probably the best way to have a one code fits all scenario. But as...
Does this tool scan every DLL/assembly referenced by the .NET Framework project, to see if that assembly might be calling SDKs/APIs that no longer exists or are deprecated/unsupported in .NET Core?
Also it should check if that third-party assembly is doing calls to unmanaged libraries using PInvoke, that might not exist on other OSes..