Introducing the .NET Upgrade Assistant Preview

Cathy Sullivan

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.

  1. 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.
  2. 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-convert tool 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.
  3. 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.
  4. 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.
  5. Add template files. For some application models like ASP.NET apps, common template files (like Program.cs and Startup.cs) are missing in older framework app versions, so they are added at this step and simple updates are also made based on recognized web.config or app.config values.
  6. 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.

  7. 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 to try out the tool and engage with the team.

Happy upgrading!


Discussion is closed. Login to edit/delete existing comments.

  • Max Mustermueller 0

    And why would I want to do this? .NET Framework is preinstalled on every Windows machine. I can ship a tiny 20kb executable and it “just works”. When porting to .NET5 all I can do is either trust the intelligence of end user to install the requirements (which we all know won’t be a good idea) or to include the WHOLE .NET5 runtime with my 20kb executable. And I have to do this for ALL of my programs just to make sure they all “just work”.

    If .NET (5) is really meant to be a replacement in the long run. Go ahead and make it default in every Windows machine. Or give us a proper AOT which has been requested a billion of times before. Native code don’t need a freaking 150mb runtime to be included. Or make the trim feature somehow useful. It trims a 80mb singlefile WPF application down to 56mb at max.

    Developing in Delphi I can have a GUI application less than 10mb that guarantees to “just work” everywhere at any time.

    • saint4eva 0

      Why not continue with Delphi if it works for you?

      • Sylvester Alelele 0

        I think Max should be allowed his Assessment!

        He can develop with Delphi and also do things on Visual Studio: we are programmers after all.

        Many of us have held out moving to .Net core/.net 5 either because we do not think it is stable yet or many of the workloads we want to use are not fully supported for the Languages that we use in house.

        I think there is need for better more all-rounded support and tooling for all of the products in Visual Studio. For example, if you are a Visual Basic developer, you are in for a tough ride in the .net core world, so I am not thinking of Upgrading any of our existing production apps to .Net 5 at the moment. It would be a disaster for us!

    • Jorge Morales Vidal 0

      If you have a better experience with other frameworks or libraries, just stick with them. Nobody forces you to migrate to .NET 5, as you said, .NET Framework is already part of Windows.

      • Sylvester Alelele 0

        Again, Max should be allowed to express his requirements.

        Everyone knows that staying on .Net Framework simply means that you have marked your application for death as they will be no further improvements to .Net Framework. So if you have any huge workload on .Net Framework, you would want to upgrade to the next version of .Net which is .Net 5/6.

        I imagine it is a huge effort creating .Net core/5/6 and maintaining it and I admire the achievement of the engineers who toiled hard to build it! But they must be regard for those who have invested so heavily in .Net Framework and who have huge projects to port so that companies are not locked into a constant cycle of re-writing huge applications.

        Performance issues also matter. Max has a point!

    • Paweł Bielecki 0

      We’re in the same boat. I brought up this issue with Windows/.NET last year ( and it was dismissed.

    • Corne Smiesing 0

      If you want your application running on linux you have to upgrade

  • Michael Taylor 0

    Unfortunately unless you already have try-convert installed to the correct version you cannot currently install it as given here. It may work for some people but not others but I cannot install it nor can the person who created the ticket.

    • Beth MassiMicrosoft employee 0

      Thanks for filing an issue, Michael! We’re in preview and rely on bug reports like these to make the experience better.

      • Michael Taylor 0

        The issue was identified as an authenticated NuGet feed. This is common in environments when using Azure DevOps Artifacts. The underlying issue seems to be with dotnet itself and the issue tracking that works is marked as fixed even though people are still having issues. The recommendation of using a custom nuget.config when calling dotnet or adjusting your NuGet sources (and restoring them back) after you’re done is too much work.

        I would recommend the instructions be updated to specify that the --ignore-failed-sources parameter can be added to the dotnet tool install command line to have authenticated feeds that fail to be ignored. This allows the tool to be installed.

        • Cathy SullivanMicrosoft employee 0

          Hi Michael – Someone who was also experiencing install issues added a workaround to the issue and was able to get it installed. Can you see if that works for you?

          Thanks! Cathy

          • Michael Taylor 0

            I already updated the Github issue with my own workaround using the parameter I specified. It is installed now thanks.

  • Paulo Pinto 0

    While I appreciate the effort put into this command line tool, where are the Visual Studio wizards?

    .NET seems to be loosing the focus on Visual Studio based tooling, everything gets introduced as UNIX like tooling, if I wanted to be stuck with command line tools I would be using GNU/Linux with C or something like that.

    I decided to invest into .NET due to the wonderful tooling and wizards provided to Visual Studio users, and we seem not to be the focus of product team any longer, it is all about VS Code and command line tools.

    • Jason Baginski 0

      Same.. Every day I’m dismayed at the fever in which things seem to be moving backwards. I get it, .NET should no longer be associated with Microsoft as it is it’s own thing now. It just makes me sad and I don’t have enough hours in the day to fight with it when the existing works so damned well.

    • Beth MassiMicrosoft employee 0

      Hi Paulo,

      I understand the want for a UI. This is the first preview of the tool and we want to make sure it can perform the upgrade tasks for project types well before we explore that. I suggest you file an issue the repo so the team can track your feedback. As for a “wizard”, that’s not the goal. There isn’t going to be a 100% predictable way of upgrading everything. There will always be code left that you will need to manually address as only you know the intent.

    • Rubens Martins 0

      This is a joke, right? Do you know the consequences of being stuck to IDE functionality?

      The best thing you could hope is to have decoupled software and development environment in a configurable manner.

  • Rich Mercer 0

    I don’t need this tool to tell me that my Azure Functions aren’t (and likely won’t be) fully supported on .NET 5. Many of us will be forced to wait for .NET 6 and LTS by the sounds of it after being let down by Functions support.

  • Jerzy Rozmyslowicz 0

    In other words it will not work, just “try to convert” and see for bunch of errors

    • Jorge Morales Vidal 0

      It is not magic, .NET Framework and .NET Core/.NET 5 have a different code base, features and APIs, so don’t expect a migration free of errors. There will always be a manual work to do, that is expected. See it as an opportunity to learn the new stuff .NET 5 brings.

  • Tudor Turcu 0

    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..

  • Mickey . 0

    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 a perfect example. They force the coder to change his/her coding just because .NET (Windows?) fails to efficiently use threads or uses too many resources to start another thread or is unable to allocate resources efficiently when something needs to wait for a slower resource.

    The vast number of projects created using any platform, are not complex projects, and they remain simple projects during their entire lifetime in business. DI, another example, which appears to be forced upon coders, complicates simple things, in the name of implementing yet more “software patterns”.

    Building an upgrade tool, which is just a preview, after several versions of the New .NET, is probably too little too late for most businesses, which have already lost faith in .NET.

    It seems clear that .NET evolution is driven by simply coders/coding, and NOT business in mind; business(s) which have to pay for the costs of re-write, each time, Microsoft coders create a new version which requires re-write.

    For many people in IT that I know, enough is enough, and they have started looking at other options. If businesses have to re-write apps, if we have to have yet another long learning curve, the, it might as well be for any new platform. Why not look at all new platforms, especially the ones which are backward compatible, and do not keep coming out which new changes/new versions so often? Businesses need stability/predictability, NOT new buzzwords.

    In my 25 years in IT, much of it at C-level positions, I have always hired people with business sense (ability to manage business processes efficiently) to run IT domains, so that we do not get carried away with every new tech buzz word, which does little little for business, but overcomplicates things.

    This new tool, which is just a preview, solves no real issues which businesses will encounter. You should have come out with this tool BEFORE launching the first version of this New .NET.

    Remember, IT is a cost-center in most companies.

    • Rik Dryden 0

      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 you say, IT is a cost-centre and it would need a major forward-looking investment for a lot of folks to take this up with an eye for the future.

  • Hakan Fostok 0

    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.

  • Rik Dryden 0

    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??

    • Sérgio Terenas 0

      Hi Rik, I was told at DevConf they will add VB.NET support to the tool. I’m also waiting for it!

  • Jeff Jones 0

    Command line? What is this – the 1980s? At least come into the 21st century of productivity with a GUI to complement a command line.

    • Cathy SullivanMicrosoft employee 0

      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 from you. Thanks!

Feedback usabilla icon