project.json is going away and it's a good thing

Published 5/11/2016 6:56:00 AM
Filed under .NET

During the last community standup of the ASP.NET core team Damien announced that
project.json is going away. This spurred a discussion on twitter that
left me with the feeling that this is a bad thing.

I think my fellow tweeps are wrong on this matter and here's why.

Damien announced during the community standup of may 10th
that the project.json file is going away. Damien also explained why.

Why is the project.json going away?

The project.json file is very different from what we are used to in .NET.
The file contains everything you need to get dependencies from nuget. It also
contains information on how to compile the application. It's a mix of packages
and project settings if you will.

There are a couple of good things to this. You can edit it using a text editor
and manipulate it using the commandline utilities provided by ASP.NET Core / .NET CLI.
Also, it doesn't list every file in the project which makes things very easy to manage.
It certainly is more compact than the csproj files we are used to today.

However, supporting the project.json file takes a lot of effort. All the tools that you
are familiar with today use the MSBuild based build tooling and don't support project.json
all that well. In fact Visual Studio uses xproj files as a stunt double for the project.json
file. This is rather weird and I always thought that Microsoft is making it a little too
hard for themselves doing this.

Damien didn't explicitly state that this was one of the problems they had. But from
what I gather it is at least part of the problem. Because Microsoft is going to automatically
convert that xproj file into a csproj file from RTM onward.

Another problem is that tools like Xamarin studio use MSBuild files instead of the project.json
file. And frankly MSBuild is still a great tool and there are a lot of companies that have
many hours and huge amounts of money invested in MSBuild. That would all be out the window when
Microsoft forces everyone over to project.json

But csproj is evil!

Yes, csproj files today are evil. I know, they list every single file in the project folder
that needs to be compiled by MSBuild. Also, it is very bloated to a point where people don't
even bother to read what's actually in the file.

Those two things are bad. project.json provided a solution to those two problems.
Are they throwing that away? No, they don't!

MSBuild is actually perfectly capable of creating itemgroups that refer to files
using so called globbing patterns. It's just that Visual Studio doesn't use this kind
of solution to list the files in the project. So the problem is not with MSBuild or the csproj file.
It is with Visual Studio and Damien promised that this will be fixed once they start to move
from the project.json file to a csproj file.

Also, they are going to clean up the csproj file as a whole and remove all the additional stuff
that is in there that you don't need. That should give us a file that is much more compact than
it is today.

Finally they will also make sure that you can still edit the csproj file using the commandline
utilities provided by ASP.NET Core and the .NET CLI. This should help everyone who is developing
from Mac or Linux too.

The one thing that isn't going away of course is the fact that csproj files are XML files.
I think this isn't necessarily a problem, but I guess we like JSON better these days.
I would go as far to say that JSON is the new XML. And if you think about it in that way, it's
actually not that bad at all.

When will this happen?

The project.json file move is something that isn't going to happen in RC2. The RC2 release
is almost completed, so there's no time to make this change. The team is planning to
move from project.json to csproj files gradually.

The RTM release will have a csproj file and a project.json file. The project.json file
will contain less stuff than it does now. Most of the project settings will have moved
over to the csproj file. The nuget packages however will remain in the project.json file.

Visual Studio will automatically create the csproj file for you and move the stuff from
the project.json file into this new project file. I don't know about the other tools, but
I guess they are going to something similar from Visual Studio code.

From what I understand now is that they will probably rename the project.json file to something like
nuget.json. But this is still open right now.

After the RTM release is done, the team will start to work on moving the dependencies away
from project.json. Again, the exact migration path isn't clear at the moment.

The essence of all this is that the project.json will not be gone over night. Also, the tooling
will help you ease the pain of moving from project.json to a csproj file.


To make a long story short: project.json is going away, but we get back a
csproj that is much better than it used to be.

With the new csproj you get a compact build file that you can extend yourself.
You can still integrate grunt tasks into build, but this time you can even write more complex
stuff than that using MSBuild targets and custom itemgroups.

I personally feel that the move from project.json to the new and improved csproj file is a good thing.
And I hope you find that too after reading this post.

For those who would like to see the community standup. Find it right here: