msbuild.md

Thoughts on project files

I missed last night's ASP.NET Community Standup on account of being shattered after a long day and falling asleep. Then I checked Twitter on the train this morning and discovered that the .NET world had, apparently, been burned to the ground by marauding Microsofties (again). It seemed to have something to do with project files, JSON vs XML, and suchlike.

Finally, lunchtime happened and I could watch the recording of the standup, and I got to understand what everyone was on about. In case you've missed it:

The TL;DR history

1. In the beginning, there was make, and Gates did not own make, so Gates said "Let there be MSBuild" and there was MSBuild.
2. And MSBuild used the *.*proj files from Visual Studio as its inputs, which were formed of terrible XML, and verily it was impossible to use without a Visual Studio license.
3. And Gates looked upon the Visual Studio revenues and saw that they were good.
4. And much time passed, and Gates ascended into a Foundation, and the peoples of the Earth began to worship false software development ecosystems.
5. Like Node.js.
6. And the acolytes at the Church of Gates observed attendances were down, and sought to bring the lost sheep back into the fold.
7. Then Lo! a multitude of Scotts gathered unto themselves seven-times-seven likeminded people, and stormed the Temple of GitHub, and freed the Source Code, that the people might partake of it and embrace it and do Pull Requests.
8. And the New Code did not use XML, because everybody knows that XML is old and shit, and yea, verily, JSON is where it is at.
9. But the acolytes of the New Code did wander in the desert for many years, searching for the Promised Land of Milk and Honey and GoLive Licenses.
10. At one point they thought they could see it over the next hill.
11. And there was much rejoicing.
12. But, alas, it was a mirage, and you shouldn't use it in production.
13. Thus after 40 days and 40 nights, the Acolytes of the New Code did stand up and say "Let us New ALL THE THINGS", and it was so.
14. And when all the things had been made new, a Scott wrote a letter unto the people of Corinth, saying: "we are working to merge the capabilities of .xproj/project.json and .csproj project systems into a single project system based on MSBuild".
15. And the people did respond "WAT?"
16. And the Head Acolyte did clarify that the project.json was not The One True Way.
17. And that The One True Way did, in fact, have quite a lot of XML in it after all.
18. And there was much wailing, and gnashing of teeth, and rending of clothes, and tearing of hair, and stuff.

My initial reaction

My more considered reaction

Look, I'm not happy about this, I hate XML as much as anyone, especially XML with Schema in it, but I don't think it's as bad as everyone's making out. Probably. It seems like they're planning to keep the JSON format for NuGet package references, and the whole thing of having to put all the files that were part of the project into the project file instead of, you know, the directory, seriously, how hard is this stuff has gone away, because it turns out that MSBuild could handle globs all along and it was just Visual Studio that was stupid.

And the command line tooling is going to be able to do all the complicated stuff, or something, so it doesn't really matter that trying to make a tiny change to the .csproj file in a text editor is going to be like digging through broken glass in a rusty bucket of vinegar looking for an angry sea urchin.

It's this last thing that seems to have people upset, this idea that we should be maintaining project files by hand-editing them, but is that really better? Do you install NPM packages by editing package.json? No, you npm install --save.

The fact is, we've gone from DNX, which just used Roslyn to compile a bunch of C# files into an in-memory assembly at runtime, to .NET Core, which produces an on-disk assembly (and can even AoT-compile that to a native, statically-linked binary that requires no external runtime). Doing that requires a lot more metadata about architectures and environments and what-have-you, and yes, you could encode all of that in JSON, but it would be big, complicated JSON and not that much more fun to edit, if we're honest.

And that's the other thing: as a human-readable file format, JSON is better than XML, but it's worse than almost everything else. It doesn't even allow comments! It's an accidental format, absent-mindedly unleashed upon the world by a JavaScript developer who worked out a way to turn objects into strings that could be turned back into object using the built-in eval function. And then it turned out you shouldn't do that anyway, because security. The only reason it's become so popular as a configuration format is Node.js, which speaks JSON natively.

(Personally, if I were creating a new build system from scratch, today, I'd use TOML, like Rust.)

Maybe, now that MSBuild itself is open source, as well as the Roslyn Project System, these things will be extensible; if not, then they're surely replaceable.

Final thought

After watching the relevant part of the standup video again, I am remaining cautiously optimistic that any parts of a project's configuration for which hand-editing does make sense—for example, packaging or runtime configuration—will be kept out of the XML project files and managed separately.

Please.

Genius! 👍

Very much this. Who exactly wants to put their hand up and admit they were looking forward to hand-editing JSON files, anyway? If there is a problem, it's solution files. Now those bastards really are hard to edit.

Me. I've been hand-editing JSON files since the very beginning, I use VS Code where you basically have to do that, and Vi where you DO have to do that. I am NOT going to hand edit csproj XML files, I don't care how pretty they are. The fact that I no longer have to use bloated inefficient VS was a major plus for .NET Core. Now I need to deal with it's rubbish project formats because it's vomiting on the build system even when I'm not using VS/MSBuild?

No. No, I really don't think so.

Sorry, I know that for a small document, with a good editor, JSON is loads easier. My question probably ought to have been "who wants to edit the equivalent of csproj files, regardless of the language?". A massive document that you can't fit in your brain is going to be tough to edit in your head, either way. VS is a big beast, for sure, but that's a product of having lots of features for lots of different languages all in one place, working together.

It's Hobson's Choice, at the end of the day. Besides, if the biggest problem with .NET Core is that there's an XML project file format that a few people internet had a hissy fit over, then I'd say that's a roaring success and those people might want to a) ask themselves if they could do better in the same time, and b) think of their blood pressure.

There's no saying it won't come back in the future once the actual framework is stable enough for people to be writing software and forming opinions on what the new project format should look like as they go along.