Adding a "New item" in a DSL Tools target designer
We've had some comment on our newsgroup about an issue with the "Add new item" functionality in a target designer using the new March release of the DSL tools. Thanks to our determined customers Kim, Jean-Marc and Eric for rooting this out.
I thought it might be interesting to write up a bit of an "anatomy of a bug" piece and also to take a peek at some futures in the area that the bug surfaces in.
The scenario is this:
You've created a new designer and you hit "Debug/Start" to bring up the experimental IDE containing your target designer. In the new experimental IDE you go to the Solution Explorer and choose "Add new item" from the context menu of the project. This now gives you a choice to add an item called "MyDSL1" where your DSL is called MyDSL. You'd expect this to add a new empty MyDSL language file to your project.
However in the March release, when you select this you get an error along the lines of:
"Unable to load 'C://..mydocuments/project/MyDSL.MyExtension' due to the following reasons: The data at the root level is invalid. Line 1, position 1"
If you go and look at the file that has been added you'll see it consists of a single letter "A".
To fix the bug in your generated project, go to the file <MyExtension>.<MyExtension> in the Templates folder of the Designer project. Edit the file so its length is less than 5 bytes. (If you're experiencing the bug then it will probably be six bytes long). Its fine for the file to be empty. Then rebuild your designer.
Now just what is that all about - why hasn't the file got some nice XML in it that encodes the concept of "empty file"? To explain this we have to step back a bit to look at the state of serialization in the designers we generate in the current CTP - on the way we'll take a sneak peek at where we intend to go in this area.
Our current generated designers use a serialization format that can best be described as "temporary".
To give a concrete example, if my domain model talks about fruit then I'd expect to see XML tags going something like:
<apple variety="Cox's Orange Pippin">
rather than
<element type="orange" id="nastyGuid" some="other implementation-looking-stuff">
<attribute name="variety" value="Cox's Orange Pippin" id="nastyGuid2" some="other implementation-looking-stuff" />
</element>
Unfortunately today, our implementation leans towards the latter and the XML format combines the following undesirable characteristics:
- It is tightly coupled to the detail of the domain model and as such is fragile to slight changes in that model.
- It is tightly coupled to the implementation technology in our libraries.
- It is nowhere near comfortably human-readable.
So as you can probably guess we're aiming to move towards the simpler style of serialization including facilities to manage the impact of change in domain models on serialization.
However we won't get to this happy position for a few CTP releases yet, so let's get back to the original problem.
At the time the DSL Wizard is run, we have no idea what will constitute a valid but empty domain model so we can't use that as sensible content for a new empty model item from "Add new item". Instead we chose to use a blank file and have the designer populate it programmatically when it is launched. We then ran into the problem that many of our internal tools and the installer creation tool we're currently using don't like blank files. So we compromised on using any file that is less than 5 bytes long as a "Mock" empty file for the time being - any true XML serialization file is going to be more than 5 bytes. We populated the pseudo-empty files with a single letter "A".
This (slightly hacky) technique worked around the issues with our tools satisfactorily until we could update them, but unfortunately a bug crept into the DSL Wizard for our March release which adds an extra 3 bytes onto the length of the <MyExtension>.<MyExtension> file in the templates folder of the Designer project. It is now 6 bytes in length and consequently is no longer treated as an empty file.
How unlucky is that? Of course, Murphy wrote his Law specifically to target the combination of bugs and hacks so luck doesn't come into it.