Is the Tide Turning on project.json?

by Mike-EEE

Wat Want? ^

I am not exactly a fan of the new project.json initiative underway between the Visual Studio and ASP.NET Core rewrite.  In fact, I have been so concerned with it that I have created a vote to change this very issue along with other latent misgivings in the Visual Studio project system.

Wat Wrong? ^

The JSON specification simply does not support comments within its documents, a fact (read: oversight) that seems to have escaped the ASP.NET Core team in their analysis of JSON the format of choice to serialize their new project initiative.

So… Wat? ^

Recently someone posted a very sane and reality-based Tweet stating that JSON files should NOT be used for configuration, schemas, etc. Hallelujah!  I am not some mad man wandering alone in this wilderness after all.

 Xml? ^

In response to that tweet, other MSFT developers have jumped in and have tried to defend the questionable — and inexplicable from the Microsoft IP perspective, as I explain in a bit — decision to pursue JSON over other formats.  In fact, a good number of developers (as you can see from the vote I am promoting here) prefer other formats such as XML, the mature serialization technology to represent their data.

Now, there are many data formats out there, and that is something that should definitely be accounted for in future versions of tooling.  However, none of these formats are as powerful and native to Microsoft developers as Xaml.

XAML?! ^

Yes, Xaml. A Microsoft-created, supported, and mature serialization and object-description language used in basically every major Microsoft group with the exception of … well, ASP.NET and .NET Core.  To start with here, Xaml stands for eXtensible Application Markup Language.  Why, from the sounds of it, defining a new project structure is perfect for this!  In fact, you can define an entire application in Xaml if you are so inclined (see: the A in Xaml).  Xaml can be used to describe any POCO you wish, not just user interface elements.

The moment you realize you can use Xaml for more than just User Interfaces

The moment you realize you can use Xaml for more than just User Interfaces

As any example, you can see this screenshot of the Console Application — yes, a Console Application described in Xaml —  that is used here at Developer Wins! to build the weekly vote reports deployed every Friday morning:

Xaml-Described Console Application

Xaml-Described Console Application

It is a small jump from here to see that Xaml can be used to support a new project structure altogether (and the effort would be minimal, considering the vast resources that have been placed in the new project.json structure already).  Again, the tooling is already in place and is mature.

To summarize, Xaml is:

  • An eXtensible Application Markup Language (bears repeating)
  • Class-driven schema model (no need to create “yet another artifact” to describe the item you are describing — the class that you have already created is the schema.)
  • Extremely powerful serialization model
  • A Microsoft property and invention
  • Designer-friendly
  • Mature (nearly a decade old)

Value IP (Intellectual Property) ^

Much like how the Windows Platform group is harming the value of its owns developers by building a backwards bridge from iOS into Windows, the ASP.NET Core group is ultimately harming Microsoft’s IP portfolio by choosing another external document format standard over one that already works within its technological capabilities.  Don’t get me wrong (too late, I know, haha!), I am all for adopting open standards, and the ASP.NET group — along with the Edge group — have done a remarkable job in doing just that.  However, in this case, this certainly requires some additional review and consideration, especially when the way that they are utilizing a document format is violating the very standards they are trying to uphold.

Scheduling and Effort ^

Finally, the last consideration here is scheduling and effort.  Look at all the effort being placed into this new project system and the serious overlap of existing functionality with existing MSBuild and *proj files.  Look at all the effort put into the new tooling for intellisense and schema.  If Xaml was leveraged instead, minimal effort would have been put into update the tooling to play with the new bits (this is talking from the Visual Studio IDE and not Visual Studio Code perspective), and we would probably get less blog posts about how schedules are slipping.

Show Your Support ^

If you agree with me and would like to see Microsoft reconsider its current path in its project.json initiative, please show your support here:

  • Miguel Alho

    The first set of project.json files (around / until) Beta6 supported comments. It wouldn’t be a bad thing to re-support them, even if is is (slightly) unstandard.

    • Thank you for the comment, Miguel. From what I understood, they *do* support comments in project.json? To be honest I have not followed the play-by-play as I have not been a big fan (obviously) of the direction, and the fact that the there is deviation from the standard (or even adopting a standard that does not meet obvious/expected requirements) was enough for me to freak out and start the vote. 🙂

      Either they support comments and they break the standard or don’t support comments and break developer experience. No win situation, which is why I would like to see Xaml (again, a MSFT tech that allows comments along with a vast variety of awesomeness) adopted (or at the very least supported!) instead.

  • Nikos

    Simply solved with either http://json5.org/ or even http://hjson.org/

    • A new standard for the “standard”? So confusing. 😛 As you (hopefully) know with software, nothing is simply solved! We still have the problem that over half of MSFT technologies and groups are dependent on XML/Xaml. In fact, all groups/tech outside of ASP.NET/web rely on it. So now we are context-switching between different file formats, one which is mature and has great tooling around it, and the other that is in development and has another year or so before fully viable. I wish it was simple, but it’s messy anyway you slice it for the foreseeable future.

  • Shederman

    XAML is an AWFUL idea for a project file format. I’m trying to think of anything worse, but really struggling. XAML is designed to be used only for tools, not human editors. When I’m editing a build file on a build server I really don’t want to have to install a bunch of tools just so they can wade through the XAML rubbish spewing through the file.

    Project files should be concise and small. XAML fits neither category. It’s only advantage is that it’s self-documenting, but well-known project file formats don’t NEED self-documenting capabilities.

    • Sounds like you have not had a lot of experience in XAML, then… it is designed for both human readable (XML origins) *AND* designer tooling. It is a serializing mechanism with conceptual entities that you do not find in other serializers such as markup extensions.

      And I am in agreement with you that the TFS build server Xaml design is terrible. That has given a TERRIBLE name for Xaml. WPF on the other hand has done wonders for it. Unfortunately, that has resulted in being what everyone considers its only use, but it can be used for ANY object definition — and designer-friendly, to boot. 🙂

      I should also say that my hand-crafted Xaml files tend to be on the minimalistic side, but you are correct in that it is not as terse as JSON. But even today we see projects such as OmniXaml making efforts to decrease the footprint of the necessary markup:

      https://github.com/SuperJMN/OmniXAML

      • Shederman

        Yes, I don’t have much experience using XAML. I avoid any opportunity to use XML based formats except when absolutely necessary. I’ve paid my dues on XML, I’ve drunk the Kool-Aid, and been poisoned by it.

        WPF, well I’ve avoided that BECAUSE of XAML. I get that you like XAML, and good for you. But you’re taking your hammer and saying it’s good for my nails, and I’m saying it’s really, really not.

        I’m not trying to convince you to use json for everything, I’m trying to point out that not everyone agrees with you about the wonders of XAML. They have good reasons for their position, just as you have good reasons for yours.

        Personally, for project files, I think that the best option would be a code-based option like Scala or Gulp uses.

        • LOL well not just my hammer and nails, but pretty much all of MSFT and every single tech that has come out of it whose name is not ASP.NET. 🙂

          The point of a designer-friendly format is that it ultimately saves time and money when working with it. When we speak of projects, what happens when you right-click your project and select properties? There’s a whole UI that is presented to you. But guess what? It’s very arbitrary and set in stone (it’s not even based in WPF, I don’t think?). Wouldn’t it be great to customize and extend that UI with ease? Xaml makes this very possible.

          A code-based format is expensive to maintain. I as a business owner now have to hire a resource at a higher rate than one at a lower rate that can simple manage data (xaml/xml/json, what have you). The goal w/ using a data-based format is to ease the devops/ALM cycle. I am not going to hire a coder to do this, this is a poor use of skill (and money).

          BTW, don’t you think that .INI would be the WORST format for a project file? 🙂

          • Shederman

            Yeah, but I don’t use a designer. I don’t right click and view properties, I edit the underlying file for preference. I don’t WANT an editor that takes ages to load, I want a light weight code editor that gets out of my way. I’m loving VS code + command line. I don’t even open VS anymore.

            Out of interest, not because I’m really carrying a candle for a code based project format, but why would a code-based format be expensive? I mean, they’re a developer already, right? They’re writing code in C#/F# already? Not trying to punt code based project files really, just interested.

            Shew, I dunno INI is definitely near the top of the bad list yeah. I’m loath to say worst, people are just so darn inventive in coming up with rubbish 😉

          • Haha, well the bottom line here (for me) is that there are two camps now in our development ecosystem: web application developers and native application developers and each have their own way of doing things and each hate the others’ approach. 😛 I am hoping MSFT sees this and comes up with a solution that caters to both sides effectively.

            As for code-based solutions being expensive. We’re not talking in development but when the application is deployed and is in the field (devops). If I require a resource that knows C#/F#/JavaScript to manage and maintain the application (let’s say $75-100/hr as a resource cost) vs. a solution that has its configuration tied to a nice UI with checkboxes and text forms to manage/set configuration ($35-50/hr, maybe even less), organizations and companies are going to gravitate the cheaper-to-maintain application that requires cheaper resources and less effort/skill. This is the trick of ALM/devops development: the long-term cheaper solution ultimately wins, especially when you scale out the number of applications in concurrent deployment. 🙂 You can’t (easily) build a designer around code, but you can (easier/easily) build a designer around data formats. Hopefully that makes sense. And thanks for the dialogue!

          • Shederman

            Yeah, I think your two camps observation is spot on. The question MS needs to ask themselves is if they only want the one camp. They’ve already faced huge defections over the past few years, and .NET Core was part of the attempt to staunch the bleeding.

            Decisions like this do not help.

            Okay, yeah, we tend to do zero config solutions using Consul and Zookeeper, so those cost issues don’t really present.

          • It’s a bit of a mess, I agree! And thanks for sharing those products. I will check them out.

            FWIW, I am not sure if you are aware, but this site’s premiere vote is all about making a comprehensive .NET client model that ultimately combines those two camps (in a standards-compliant, interoperable way):
            https://visualstudio.uservoice.com/forums/121579-visual-studio-2015/suggestions/10027638-create-a-ubiquitous-net-client-application-develo

          • FWIW, I have created an issue within the MSBuild mothership that deals with this issue. Please feel free to add your vote/reaction/feedback here: https://github.com/Microsoft/msbuild/issues/613

            Thanks again for the in-your-face-yet-civil dialogue!