Migrating a project.json .net core project to the latest csproj format can be a bit of a minefield. There are a few gotchas and even best practices that you likely did when using a project.json based project that will actually make the migration to csproj fail.
But first, why should you not upgrade :
- Your team is not ready to use Visual Studio 2017 (e.g. no licenses). csproj based projects can only be opened in Visual Studio 2017, they cannot be opened in Visual Studio 2015
- Your team is using another IDE such as Jetbrains Ryder that does not have support (Or complete support yet) for csproj based projects.
If those aren’t you, then it is really a no brainer to upgrade your project to the latest .net core tooling.
One important thing to note is that tooling is not the same as the .net core version. Tooling refers to things like project.json vs csproj and how the .net core CLI works. It does not refer to the version of .net core (1.0 or 1.1). Updating the tooling does not change the version of the actual .net core runtime!
Preparation
You should go ahead and download the latest .net core SDK. If this is your first time doing this you should first read this article on how to run two versions of the .net core SDK side by side. This is really important if you intend to work on both project.json and csproj projects on the same machine for some time as you could end up not being able to open projects without the right global.json setup.
On the project you wish to migrate, check the root of your project/solution for a global.json file. This file is used to determine which SDK to use but annoyingly can cause havoc when you are trying to migrate. The reason being when you wish to migrate, you want to be able to run the migrate command using the latest tooling, but the global.json may point to an older version. If you try to migrate with this going on you will see the following error message :
D:\src\MigrateExample>dotnet migrate --help No executable found matching command "dotnet-migrate"
Take a backup of the global.json and delete it from the root folder.
Using the Command Line
The command we are going to run from the command line is “dotnet migrate“. If we move our command line to the solution directory and run it, it will recursively move down into our projects and migrate them all to the csproj format.
D:\src\MigrateExample>dotnet migrate Project MigrateExample.Web migration succeeded (D:\src\MigrateExample\MigrateExample.Web). Summary Total Projects: 1 Succeeded Projects: 1 Failed Projects: 0
It really is as simple as that!
Remember to create a global.json file in the root of our directory specifying what tooling version we are now on. This is actually an un-needed step realistically, but if you upgrade your tooling again on your machine you will want this project to be unaffected. It’s also handy when setting up a new developers machine to be able to remember which version of the SDK you actually need!
Rolling Back
There is no CLI command to “migrate down” a .net core project, but you can rollback manually. Inside each project directory you will find a backup folder with your original project.json file. You can pull this out and replace the csproj files with your project.json files again. Remember that after moving back to project.json, you will need to create/update your global.json file with the correct SDK versioning so it is able to be opened by Visual Studio 2015 again.
