Upgrade to CMS 12, usage of upgrade-assistant-extensions

As you might now, there is an upgrade-assistant tool that can help the migration from an ASPNET project to an ASPNET core project, see upgrade-assistant with source. The tool will convert ASPNET projects to new .csproj style, change target framework and update packages. It then also contains some Roslyn analyzers and code fixers that changes some common code (like changing namespaces containing System.Web or replacing code like HttpContext.Current).

There is also an optimizely extension EPiSourceUpdater to the upgrade-assistant tool that includes code analyzers/codefixers that are specific to CMS/Commerce projects. The extension is being continuolsy updated so make sure you download the latest package from the Relase section.

Targeting net5

We are currently working on net6 support for CMS and Commerce but until that is released the upgrade need to target net5. The upgrade-assistant tool itself has been upgraded to net6 and that is what is used if you install the tool using dotnet cli. It seems that some of the built-in code analyzers/fixes will not apply if the project being upgraded is targeting net5, so my recommendation (until CMS support net6) is to instead of installing the upgrade-assistant tool, clone the upgrade-assistant repo and build it locally. The CLI tool is targeting both net5 and net6 so you can then run the executable from the net5 output folder. 

Step 1

Clone the upgrade-assistant repo and build it as described here

Step 2

Download latest CMS/Commerce extension package from here and unzip it to some location. 

Step 3

Open a cmd prompt and navigate to the output location of the cli build from step 1. Typically, <checkout location>\artifacts\bin\Microsoft.DotNet.UpgradeAssistant.Cli\Debug\net5.0

Step 4

To specify that the project you are upgrading should target net5 you need to run the following in the command prompt

set DefaultTargetFrameworks__LTS=net5.0

Step 5

Now you can execute the upgrade-assistant tool from the command prompt like:

Microsoft.DotNet.UpgradeAssistant.Cli upgrade <path_to_your_project_to_update> --extension <path_to_unzipped_cms_extension> --target-tfm-support LTS --ignore-unsupported-features

Expectations

You should not expect an fully converted project after the conversion. But the tool should convert many "standard" things so you can concentrate on the code parts that are specific to your project. A good start after the conversion of the tool is to review the .csproj file and see what packages that are referenced there. If you open the project in Visual Studio and expand the node 'Dependencies' under the project then Visual Stuido will display warnings for dependencies that are not compatible with net5. Then you need to review the packages one by one to figure out if there is a corresponding package that is net5 compatible. If there is then you update the dependency, if not then you can temporarly remove (for example outcomment in .csproj) the dependency. Then after all dependecies are resolvable you can compile the project to find the errors. Then there will likley be an iterative process of fixing errors and compiling. But hopefully since you have run the tool many of the "standard" errors you would have seen if you would not have run the tool is fixed and the remaining ones are specific to your project. 

Happy upgrading!