Microsoft Domain-Specific Language Tools from a Developer's Perspective

Domain-Specific Languages (DSLs) are an architectural hotspot. Microsoft supports DSLs within the Software Factory Initiative and provides a means to incorporate them into the software development process via the Visual Studio 2005 SDK, which has been officially released, lately. Although there is quite some information available on the topic, for the most part, DSLs remain an abstract architectural concept. Now Dr. Mike James is looking at the Visual Studio Domain-Specific Language tools taking the perspective of a developer.

Domain-Specific Languages are small, targeted languages focusing on specific concerns in software development. They are used to model entities or processes of a specific domain in a language that uses symbols or expressions common to that domain. Thus they differ from generic modeling languages as UML, which provide an abstract, one-for-all notation. Another difference is that UML is often used as (but definitively not restricted to) a means of documenting analysis or design deliverables, whereas DSLs serve as both a modeling tool and a code generator. 
In his article James complains that

[...] the documentation, examples, white papers and even the video introductions are truly awful. They all spend far too much time on the “fluff” and mostly ignore the most obvious questions that a programmer new to the DSL tools is likely to have. Most of the examples are too complex and appear to involve “magic” – instructions such as “now paste the following XML into a new file” without any explanation of where the XML came from or what it does is hocus-pocus as far as the beginner is concerned. Rather than spending a few thousand words on explaining how you can change the colour of a diagram shape, this article concentrates on the missing element in the documentation – how to use DSL Tools to actually generate some code from a custom diagram. Once you know how to do this then the documentation starts to make a little more sense.

James explains that the Microsoft DSL Tools "takes a graphical approach to DSL construction". In the beginning the process of creating a DSL is centered around the DSL Designer, which is used to design and generate the DSL as well as designing models adhering to the DSL that are used to generate code. The Designer-Designer concept is a bit confusing at first, but makes sense when you finally got the idea. The complete DSL design consists of a two phase process:

1. Define a graphical notation for diagrams that adhere to the grammar of your DSL. Simply put you have to design the graphical shapes, connectors and underlying meta-model (including textual properties) that make up your language.
2. Write code templates, which use the information stored in an instance (diagram) of your DSL to generate suitable code.

In the article James provides a Hello-World example DSL based on the MinimalLanguage template installed with the SDK. He does not waste any time on explaining how diagram shapes can be added or how model elements are connected to graphical shapes. Instead he elaborated on the code generation process.
Code generation is based on TextTemplate (.tt) files. These templates contain both code that is directly generated (copied) to the target and meta-code, which accesses the model and is used for dynamic generation. According to James the mixture of code and meta-code is very confusing. In addition the concept that there is an (undocumented) Meta-Class-Structure, which the Model Elements of the created DSL are based on, does not really help to make things any easier.

There is virtually no documentation of the class structure, only very specific examples that really don’t help. The only solution I’ve found to the documentation problem is to read the generated code files in the DSL Designer. For example, if you open the file DomainClasses.cs in the original project you will find the definition for the classes [that make up your model].

At the moment DSL Tools are difficult to use and the initial learning curve is very steep so you don’t seem to get very much back for the investment. The visual designers are fairly easy to use, even if they are overflowing with new jargon and a high degree of what appears to be accidental obfuscation. However, the code generation methodology suffers from all of the problems that code generators, or software factories, have always suffered from – meta-code. The problem is you have a horrible mix of code that is rendered “as-is” and code that is executed on the way to generating more code. This combination is inherently difficult to understand and difficult to keep under control. We really need some radically new ideas.