Project and Package References in the new csproj format

Microsoft has recently released the new version of the build tools for .NET Core. As previously announced, the new build system will be MSBuild-based (oh project.json, we hardly knew ye), although it will be a substantial improvement over the traditional csproj format (e.g. support for multiple targets, nuget support, no need to list files…). Going back to XML, well, stinks, and MSBuild/csproj is definitely no great fun - if you’ve ever tried debugging your build process by passing /v:Detailed (or heavens forbid, /v:Diagnostic) you know exactly what I mean. But MSBuild does provide much more flexibility and extensibility, has a long history, and is better for interacting with other project types.

There’s one unfortunate point about the new csproj format, though. project.json doesn’t make any sort of distinction between package dependencies (i.e. nuget) and project dependencies - they’re just dependencies. If the build can find your dependency as a project - based on source directories defined in global.json - it’s a project dependency, otherwise it’s a package dependency. The new csproj, in contrast, makes a clear distinction between <PackageReference> and <ProjectReference> nodes. Why is that important? Because one of the nice features of project.json is the ability to easily switch between the two - say you’re debugging some project which has a dependency. Want to poke in that dependency’s code? Just clone it, reference it from your global.json and bam - you’ve just imported the dependency into your solution. This capability will be lost with the new csproj, which will require tedious manual changes to be made.