Converting C# projects to the new SDK format
As technology evolves, new changes are brought into life. Most of these technologic evolvements, help mankind in doing or understanding the existing work easier. Certain changes would have greater visibility and advantages, while some would have lesser visibility but have the same magnitude of advantages.
One such analogy for this would be - acquiring a new Integrated Development Environment (IDE) for an existing programming language. This is supposed to address the vast majority of the problems in developing an application and providing a user-friendly platform for developing it. The above process will have greater visibility and impact on a large number of people. But, say, for example, an existing IDE modifies the way it stores the preference, thereby making it easier for the users to understand. This will offer significant advantages but will not have the same visibility as the first instance.
In this article, we are going to look into something similar to the second instance. Something that has happened behind the scenes in the .Net industry - Converting C# projects to new SDK format. Before we look into this, we are going to explain a few terms related to this topic.
Table of Contents
- What is csproj file?
- What is project.json file?
- Features of new csproj file
- Converting from old csproj to new csproj
- Conclusion
What is csproj file?
Files with .csproj as file extension denotes the C# language-based project file. Csproj is XML based files and can be opened in any text editor. They follow the MSBuild XML schema. Csproj file contains the list of class files that are referenced in the project and also the system assemblies that are being referenced inside the project.
Csproj files are autogenerated by Microsoft visual studio on creating a new C# based project. There will be as many .csproj files as the number of projects that are created.
Csproj files are used by the compiler to build the code by referencing the details such as the content to reference while building platform information and version information.
What is project.json file?
With the introduction of the .net core, a new way to refer the packages has been provided by Microsoft. Project.json also known as the package management format was brought into the picture.
Project.json file was used for maintaining project metadata, compilation information, and the dependencies. As the file extension suggests, it is of JSON file format. The main advantage of project.json is the readability of the file.
But when it got rolled out with ASP. Net core 1, users were having concerns with the project.json file as it is not supported by MSBuild, which would make large monolithic apps difficult to migrate. So, with the advent of Microsoft visual studio 2017 and .Net core 2, the project.json file was retired and moved to a much cleaner and leaner version - csproj format project metadata file.
Features of new csproj file
From .Net core 2.0, the new formatted csproj file was introduced. Below are a few of the major features of the new csproj file -
Human readable
The old csproj file had the GUIDs within the file for referencing which has been removed in the new csproj file.
File Globbing
In the old csproj file format, there was a need to list all the class files that are being used inside the project. Only the listed files in the csproj will be included for build and compilation. The new csproj file has the option to use wildcards to include all the files in a directory in a single stroke, which makes it easier for the developers.
Avoids merge conflicts
This is interrelated with file globbing. In a team of multiple developers, if every one of them adds a new class file, then the old csproj file leads to ‘merge’ conflicts and it has to be resolved manually. Thanks to the wildcard usage in the new csproj file, now it possible to help the developers to add the file without worrying about the merge conflicts.
All in one place
With the new csproj file format which slightly adopts this from the project.json file, all the package references, dependencies, and inclusion are all integrated into the same file.
Converting from old csproj to new csproj
In this section, let's see how to convert the older csproj to the 2017 version of csproj files. The below commands can be used to migrate from 2015 or a lower version to the 2017 version.
Step 1
Ensure that the .net core installed is version 2.1 or above. To check that, open run (win key + r), then type the below command -
dotnet --version
Check the version and install the latest version of .net core from the Microsoft website if required.
Step 2
To migrate the old project file, install a tool globally in the local machine, which would facilitate the migration of the project.
dotnet tool install --global Project2015To2017.Migrate2019.Tool
Step 3
Identify and find the path of the code which holds the csproj file in the older version. Once identified, use the below command and replace the path with either the path of the solution or the csproj which has to be migrated.
dotnet migrate-2019 wizard path
On executing the above command, an interactive wizard starts and asks options for backup before doing the critical conversion steps.
In the above step, we have used the keyword ‘wizard’, which is responsible for running the interactive conversion wizard. And in case if we need to convert the file without having the interactive wizard, then replace ‘wizard’ with ‘migrate’ in the above command and execute the same.
Also, if there is a need to analyze the project file for issues, then in the above command replace ‘wizard’ with ‘analyze’, which would analyze and signal issues in the project file without performing the actual conversion.
Conclusion
The new SDK based csproj files are leaner, easily maintainable, and saves a lot of time. Also, it is compatible to operate with .net framework based projects. Though the changes are in maintaining a file, it helps the developers to achieve the desired functionality in a hassle-free way.