Changes to Project.json

This post was written by Scott Hunter.

Last week we announced the schedule for RC2 / RTM of .NET Core and ASP.NET. Now that we have shipped RC2 I want to give more details on the .NET Core tooling moving from .xproj / project.json to .csproj / MSBuild.


When the ASP.NET team started building ASP.NET 5 (now ASP.NET Core) one of the key goals was to design it so it was very easy to create and develop on Windows, Mac and Linux. This led to the creation of the .xproj/project.json based project system. Some of the key features were:

  • No listing of files in the project file
  • Easily modify project definition without an IDE
  • Can produce a Nuget package directly from the project
  • Cross compile a project to multiple target frameworks
  • Easily switch package reference with project source

As we continued to the project we kept expanding the role of .NET Core:

  • .NET Core became the platform for Universal Windows Applications (UWP)
  • .NET Core evolved with a new cross platform tool chain for building Console and Class Libraries
  • Microsoft acquired Xamarin enabling .NET developers to build iOS and Android apps

How does this affect project.json? One of the key tenets of .NET as a platform is we want our developers to be able to share code across all of the .NET application models (WinForms, WPF, UWP, ASP.NET, iOS, Android, etc.). This presented a series of problems, while project.json was great for building web applications and class libraries, it did not allow unification of the other app models.

We had two choices. One was to move all .NET projects to use project.json. This would require us doing tooling work that touches all of the project types in Visual Studio, Xamarin and our partners like Unity. We would have to expand project.json to support all the build scenarios required by each of these project types and provide a migration story. Another choice was to build bridges so an .xproj project can reference a .csproj project and a .csproj project can reference an .xproj project in Visual Studio and Xamarin Studio. The bridge has challenges as well, for example when a customer creates a project they would now have to choose an .xproj or a .csproj, which just adds more choices and complexity.

After looking at our choices, it was apparent that it would be easier to move .NET Core projects to .csproj/MSBuild so all .NET projects use the same tooling and build system.

But at the same time we don’t plan to give up the benefits of project.json. We plan to enhance .csproj to support the missing functionality:

  • No listing of files in the project system
  • CLI tool for doing any operations on the project file, for most scenarios you would not edit the file
  • Build packages directly from the project
  • Multi-targeting

And because all of .NET uses the same tooling, we can then look at enhancing MSBuild. We will solicit feedback from customers and the community on supporting JSON instead of XML, having our tooling not generate overly verbose files and more. And because everything uses the same tooling, these enhancements could work on all .NET projects.

The first wave of this change will happen in the Visual Studio “15” RTM: when opening any .NET Core project in Visual Studio, it will automatically convert from .xproj to .csproj, moving the assets from the project.json file into configuration files and the .csproj file. We will also provide a tool for converting applications using the .NET command line tools as well.

The next wave will happen after Visual Studio “15” and will be focused on furthering improving the project and build experience.

Developing in the Open

.NET Core and ASP.NET Core are the first .NET projects that we have fully developed in the open. Traditionally you would not see all the changes as the team is experimenting to build the best product. We are trying to find the right balance of transparency between GitHub, the community standup and even this blog.  Moving forward we will try and announce major changes via the blog first as we can provide more context on what is changing and why.

What’s Next

Next week we will blog about the .NET Standard which is how we plan to make it easier to share code across .NET projects.

Scott Hunter – .NET Team