Converting From project.json To csproj

Today’s header image was created by Warren Tobias, the original source for the image is available here

It’s Time to Celebrate!

This week, the eagerly awaited, Visual Studio 2017 was released.

Not only that, there was a live streamed event to announce all of the latest changes to:

• The Visual Studio line up (including VS 2017, Visual Studio for Mac and Visual Studio Code)
• VSTS, TFS and related tools
• .NET Standard, Framework, Core, Xamarin and Mono

To name only a few things.

In this post I though I’d write about something that we all need to be able to do with our .NET Core projects going forward: migrate from project.json to csproj/MSBuild format.

I’ll simplify that to csproj for the rest of this article

I’m about to drop a little history on you, but if you want to skip it and go straight to migrating project.json to csproj, then click here.

csproj, project.json, and MSBuild

When .NET Core was first released, the default project format was a json file. This file contained all of the information that the .NET Core complier (called Roslyn) needed to know to compile the project, things like:

• metadata
• compilation options
• dependencies and tools

You can read about all of the project.json options here

A real example of a project.json file looks like this:

This is actually from one of my GitHub projects

Compare this, for example, to a current .NET Framework csproj file (which is an XML file):

Again, from one of my GitHub projects. Even though this is an old project, the csproj file has the same format as one targeting .NET Framework 4.6.1 

I don’t know about you, but I find the project.json file easier to read.

So Why The Difference?

Digging into the way back machine:

I didn’t need to dig that far, .NET Core hasn’t been around that long yet.

Back when .NET Core was first being developed, the ASP.NET and the .NET teams weren’t working together. The ASP.NET team where working on .NET Core, which would run on the .NET team’s new .NET API surface.

Incidentally, this is why the .NET community standups are called the ASP.NET Community Stand Ups

The ASP.NET team took this opportunity to re-build the project format from the ground up, as .NET Core was seen as a new beginning for .NET.

Which has been echo’d by many of the ASP.NET team in interviews and on podcasts; they’ve talked about not having to support some of the decisions made while designing the earlier versions of the .NET Framework in .NET Core

Once the open source community got their hands on the .NET Core betas and early releases, work started on the next generation of web applications using it. Most developers liked the new project format, and celebrated it for being simpler and it’s support for auto-complete.

Let’s be honest here, XML has never really been that easy to read

While the Release Candidate was being planned, it was decided that .NET Core would have to support MSBuild.

MSBuild is a series of tools which allow DevOps folks to automate the building and deployment of .NET projects.

If you’ve ever used Octopus Deploy or Cake, then you should be very familiar with MSBuild

MSBuild does not support the new project.json format, which put a lot of people off. Especially those who wanted to convert their already established .NET Framework projects to .NET Core. Starting a new .NET Core application wasn’t an issue, but not many enterprise solutions or big business applications were going to be re-written from the ground up.

Only the companies who where truly invested in .NET Core have done that. Especially since .NET Core and the tooling around it wasn’t very stable at the beginning

Because of this the .NET Standard team decided to retire the project.json format and give .NET Core support for the backward compatible csproj format. But not only that, the decision was made to simplify the format.

As we’ll see in a moment

How Do I Convert My Project?

Everything we’ve done so far, has been in the terminal, mainly because the tooling hasn’t been the most stable. But now that Visual Studio 2017 has moved out of Release Candidate and has shipped with version 1.0 of the .NET Core tooling, we can start working with that.

I’ve tried to convert a few projects with VS 2017 RC and have had mixed success so far. But that’s what you get with an RC, I guess

Either way, the first thing that you’ll want to do is update the version of the SDK that you have installed. If you’ve installed Visual Studio 2017, then that’s already been taken care of for you.

However, the latest version of the SDK is available for download here.

Terminal

From the terminal we need to confirm that we have the latest version of the .NET Core SDK installed:

Obviously, the version numbers are going to change as Microsoft adds releases new versions of the .NET Core SDK, but the version I’m using as I write this post is: 1.0.0-rc4-004771.

Next we need to check that the version of the .NET Core SDK we have installed has the migrate command – which is used to convert to the new csproj format.

On a Unix like operating system (MacOs or one of the supported Linux distributions), you can do this:

Whereas, on a Windows machine you will have to run the following command:

Both of these commands should return the following:

Which shows that our install of the .NET Core SDK supports the new csproj format and can convert from project.json to it.

Now we need to cd into the root of the project and run the following command:

A Worked Example

Ok, “worked example” is probably not the right phrase, but stick with me here.

I’ve pulled commit 6402447aec of dwCheckApi

The latest version is already a csproj project 😛

and we’ll convert it to a csproj project right now.

We need to cd into the src directory and run the following command:

And you should get output which matches the following:

If try to build the application, you’ll get a bunch of errors. I got 439 errors, and the first time I did this I was worried that I’d broken my application beyond repair.

Thank goodness for source control, huh?

But, as any developer worth their salt will tell you, always read the error messages. So let’s take a look at the very first one.

You’ll have to scroll quite far to get to the first one

Here’s the most important part of the error message:

Assets file ‘/Users/GaProgMan/Code/dwCheckApi/src/obj/project.assets.json‘ not found. Run a NuGet package restore to generate this file

So all we need to do is restore packages

Even if you’ve previously restored packages for the project, because there are changes brought about by migrating to csproj

and rebuild. Let’s do that now:

and it’ll build just fine, producing output similar to this:

Visual Studio 2017

Migrating using Visual Studio 2017 is easier than using the terminal (especially for those who prefer to use a GUI), and it’s a case of opening a project.json project after which a wizard will guide you through migrating to the new format.

During the keynote at the recent Visual Studio launch event

Which you can rewatch here

Beth Massi gave a demonstration on how to migrate a project to the new csproj format.

At the above link, if you jump to 35:30, you’ll see Beth showing how it’s done with an xproj solution.

The short version is that you just open the xproj file with Visual Studio 2017 and it starts a migration wizard.

Visual Studio just calls the dotnet migrate command on your source, in this wizard

– Beth Massi

This does require you to have worked on your project in Visual Studio 2015 (as xproj is it’s default format for .NET Core projects).

Worked Example

The project format in commit 6402447aec of dwCheckApi was project.json without an xproj file (because I had been working exclusively in VS Code with the command line).

If your project does not have an xproj file, I recommend that you use the command line tools (mentioned above) to migrate your project, then open the MSBuild version with Visual Studio 2017.

However, here are the steps that you need to take with an xproj project.

First, open the project with Visual Studio 2017

Then we want to find the xproj file, opening this file will show the migration wizard.

When the migration is complete, the csproj project will be loaded into Visual Studio 2017 and all packages restored.

The new csproj

Let’s take a quick look at the new csproj format to see how it’s changed from our project.json.

First the project.json for the project we just migrated (dwCheckApi):

And now the hot new sexiness that is .NET Core’s csproj file

I worry about you sometimes, Jamie

It’s not immediately as easy to read as the project.json

In my opinion, anyway

But, it’s more concise and has fewer lines (even with the empty lines inserted).

A Quick Note About Visual Studio Code

If you open a freshly migrated project in VS Code, and try to run it you’ll see a few strange things.

Clicking on the run button will cause the command pallet to extend and give you some choices.

Choosing .NET Core will produce a file similar to this:

There are a few issues with this file (I’ve highlighted them), and we’ll come back to them in a moment.

Now if you hit the run button again…

We’ll need to configure a task runner to be able to debug this application, so let’s do that.

I chose .NET Core, but you should chose whatever suits your project.

Once that’s done, you’ll have a tasks.json. Here’s mine for .NET Core:

launch.json

Now then, we had issues with our launch.json. To see what they are go ahead and click the run button again.

What’s happened here is that the first two configuration entries in out launch.json have badly formatted entries.

Here’s the file again (with the issues highlighted):

The problem with these lines are the two following parts:

• <target-framework>
• <project-name.dll>

Neither of these are valid entires for the launch.json.

What we need to do is replace them with valid strings. It’s pretty simple really, we need to do is look at our csproj for our target framework and the assembly name strings.

We’ll use these strings in place of the <target-framework> and <project-name.dll> strings in the launch.json. So, in the case of dwCheckApi, we want to alter the launch.json to read like this:

I’ve highlighted the fixed lines

Clicking run one last time, should build and run the application for you.

How cool is that?

Conclusion

Moving forward, all .NET Core projects will have to be csproj ones (in order to benefit from all of the features of the new versions of the SDK, anyway).

Migrating to csproj is relatively painless, as long as you’re aware of some of the potential edge cases and issue areas ahead of time.