HomeBrainDump Build a Domain Specific Language with DSL ...
Build a Domain Specific Language with DSL Tools concluded
Last week, we generated and built a business entity designer by way of introducing you to building a Domain Specific Language with DSL tools. This week, we'll run the designer and look at its features. We'll also learn how to do tasks such as adding a new property, introducing notation for the new property, and more.
Now that the designer is generated and built, let’s take a quick look at some of its features.
Press Ctrl-F5 to run the designer. This will bring up a second instance of Visual Studio with a project open named “BizEntityDebugging”.
Notice that there is a file named “Empty.biz” included in this project. Double-click to open that file in your designer. Your designer will look like this:
To get a feel for how the designer works, drag two Entity shapes from the toolbox onto the blank diagram surface. To do this, left-click on the Entity tool, hold the mouse button down and drag to the documentarea, and release.
Click on the Association tool in the toolbox. Click on the first entity shape you added, then on the second shape to draw an association line between them. The result should look something like this:
Notice that our notation defines a shape which corresponds to an Entity in the domain model, and a connector line which corresponds to an association between entities.
Feel free to explore the target designer a little more at this point. Some things to try:
Double-click on the NewEntity text in the shape header to rename it using in-place editing.
Right-click on the shape header and select Add->Attribute from the context menu to add a new attribute to the shape. Note that according to our notation, attributes on entities are placed in a compartment within the entity shape.
Click on the association line, and set the SourceMultiplicity and/or TargetMultiplicity properties from the property grid. Note that the labels on the diagram lines are updated to match.
When you’re finished, close the designer by selecting File->Close from the main menu. When prompted, do NOT save changes to the “Empty.biz” file, because we are going to modify the domain model in the next task, which will result in a change to the format of this file.
Close the second IDE by selecting File->Exit from the main menu.
Suppose we decide that the current model of the BizEntity domain is inadequate. In this task we will extend the model add a new property to a class in the domain model. In fact, we are going to add a new property to the “Association” relationship. The domain model designer provides the facility to show relationships as though they were themselves classes, in order to be able to add properties to them. You can also create relationships to relationships and inherit from relationships, although we won’t do either in this lab.
Click on the BizEntity.dmd tab to take you back to the domain model designer. At the top of the diagram you should see a brown class called “Association”. It is brown because this is a relationship, not a normal class. Open up the Association shape by clicking on the little “+” sign.
Invoke the View->Toolbox command from the main menu to bring the Toolbox window back into view.
Notice that the “Association” class defines two properties, "SourceMultiplicity” and “TargetMultiplicity”, which you have already seen show up at the ends of association lines in the Business Entity designer.
Left-mouse on the value property tool in the toolbox, drag to the main body of the Association class (the brown part), and release the mouse button. A new property called “Property1” should appear in the flap.
Click on Property1 to select it. You should see that it is selected in the property browser at the lower right of Visual Studio. In this browser, find the Name property under the Misc category, and edit it to read RelationshipType.
Press Enter to commit the change. The new name should be shown on the diagram.
Now we need to modify the notation file so that the new property shows up on the diagram. Double-click on the BizEntity.dsldd file in the Solution Explorer to bring the XML file to the front. Scroll down in the file to find the definition of the connector called “AssociationLink” (line 152).
Note that you may want to close the Visual Studio Toolbox at this point to give the XML editor more room. You can do this by clicking the “X” in the upper right corner of the Toolbox window, located on the left side of the screen.
In this section you will see that within the <decorators> section there are two <connectorText> elements defined. Each of these represents a textual decorator on the connector that is mapped to the Association relationship. You will introduce a new one of these for the new property.
Using copy and paste, duplicate the second <connectorText> element. In the new element, change the name from SourceLabel to TypeLabel and from SourceBottom to TargetTop. Leave the defaultTextId as it is.
The previous step defined a textual decorator in the notation, connected to the target end of the AssociationLink connector, and positioned at the top. Now we must define a mapping from this decorator to our new property. Scroll up the file until you find the connectorMap for the AssociationLink connector (line 18). This has several parts: a <class>, a <connector>, a <sourceMap>, a <targetMap>, and some <textMaps>.
Using copy and paste, duplicate the complete second <textMap> element (8 lines). In the new element, change TargetLabel to TypeLabel, and TargetMultiplicity to RelationshipType. Leave everything else as it is. The changes you should make are indicated in bold red in the XML fragment below. By doing this, you have associated the new decorator with the new property.
Because you have changed the domain model and notation, you must regenerate the code to build the designer. Just as you did earlier, find the Transform All Templates button in the Solution Explorer toolbar, and click it. As before, this command may take a little time to complete. If you get any errors at this point, it may mean that you made a mistake with the instructions for modifying the notation file.
Now build the updated solution, by selecting the Build Solution option from the Build menu.
Now that we’ve modified the domain and the notation, let’s use the updated esigner to build a portion of the Business Entity Diagram shown in the ntroduction to this lab.
Press Ctrl-F5 to run the designer. As before, this will bring up the BizEntityDebugging project in a second instance of Visual Studio.
Double-click on the file named Empty.biz in the Solution Explorer to open it. This wlll bring up the empty design surface as before. We want to build the diagram shown below:
To start, drag an Entity shape from the toolbox onto the design surface. Double-click on the New Entity header text on the shape and rename it to Customer. Press Enter to commit the change.
To indicate that this is a persistent entity, double-click on the text My Type and enter the text Persistent. Press Enter to commit the change.
Right-click on the shape headerarea and choose Add->Attribute from the context menu.
Type in Name as the name of the new attribute, and press Enter to commit the change.
Use steps similar to the above to create the Account Entity, with Credit Line and Amount attributes.
In the toolbox, click on the Association tool. Click first on the Customer entity, and then on the Account entity to create the association between Customer and Account.
Make sure the connector you just added is selected, and press F4 to bring up the property grid. Set the value of the SourceMultiplicity property to 1, to indicate that in our example, each account is associated with a single customer.
Also notice the RelationshipType property that now appears in the property grid. This is a result of adding the new property to the domain model in task 4. Type some text into this property, and notice that it appears on the diagram. This is a result of modifying the designer notation in task 5.
Now that we have built a sample business entity diagram, you may be wondering what you can do with it. In this task we’ll demonstrate how to use the text generation functionality included with the DSL toolkit to generate artifacts from our model. Text generation works via template files, which contain both templatized text to be generated, and logic which controls how that generation happens. Let’s look at an example which takes a .biz file as input, and generates an HTML report over the domain defined in that file.
Right-click on the BizEntityDebugging project in the Solution Explorer, and choose Add->Existing Item… from the context menu.
Set the Files of Type: filter to All Files.
Type c:\dsl\BizEntity.ReportTemplate into the File name: box, and press Add.
Double-click on the newly added BizEntity.ReportTemplate file in the Solution Explorer to open it in the text editor (you may want to close the Toolbox window at this point to give the text editor more room). We will examine the details of this file to see how code generation works.
The first three lines, shown below, set up some parameters for the code generator, we won’t concern ourselves with the details of those here:
The next five lines are standard HTML, these will be generated to the output file as static header text:
<html> <body> <h1>A report on the contents of Empty.biz</h1> <p>For this report to work…</p> <h2>Entities:</h2>
Now things get interesting. Notice the <# and #> tags which delimit sections of the file. Logic which controls text generation in placed within these tags (if you are familiar with ASP pages, this is a similar idea). In this case, the logic is written in C#, but it may be written in Visual Basic .NET as well. To make clearer what’s going on, we’ve grayed out the text to be generated below so you can just focus on the control flow; if you are familiar with C#, you will notice that what’s left are two nested for each loops, the outer one over a collectio n called “Entities” and the inner one over a collection called “Attributes”. As you may have guessed, these collections contain elements instances from the domain model.
<# foreach ( Entity e in this.ER.Entities ) { #> <h3><#=e.Name#></h3> <p>Kind: <#=e.Kind#></p> <#=e.Kind#></p> <# foreach ( Attribute a in e.Attributes ) { #> <p>Attribute: <#=a.Name#> <# } #> <# } #>
Now let’s look at the same section of the file, but focus on the generated text. As in the static header, these lines are HTML, except for the <#= #> tags, which indicate parameters that will be filled in by values from the domain model during generation. Note the use of the properties “Name” and “Kind” to indicate which values from the domain model will be used. Also note the use of the foreach loop iteration variables “e” and “a” to indicate which Entity and Attribute instances are used in the parameterization (these have been bolded for emphasis).
<# foreach ( Entity e in this.ER.Entities ) { #> <h3><#=e.Name#></h3> <p>Kind: <#=e.Kind#></p> <# foreach ( Attribute a in e.Attributes ) { #> <p>Attribute: <#=a.Name#> <# } #> <# } #>
Next, let’s run the template. Click on the BizEntity.ReportTemplate file in the Solution Explorer.
In the Properties window, enter the value TextTemplatingFileGenerator for the Custom Tool property, and press Enter.
Notice that a “+” appears next to the BizEntity.ReportTemplate file in the Solution Explorer. Click on this to reveal the generated file, BizEntity.htm. Right-click on this file and choose View in Browser from the context menu to see it rendered in Internet Explorer.
Notice that the Entities and Attributes defined in the business entity diagram appear in this report. Due to the interaction logic in the template, if we were to add additional Entities or Attributes, and re-run text generation, those additional items would appear in the report.
HTML artifacts are not the only type that can be generated. In this task we will see how to generate source code artifacts as well (as you may have guessed, the source code for business entity designer was generated from the .dsldd and .dmd files in this manner). As an example, we will generate some simple Windows Forms-based classes that might be used in the UI of an application supporting the business process defined in a business entity diagram.
Right-click on the BizEntityDebugging project in the Solution Explorer, and choose Add->Existing Item… from the context menu.
Type c:\dsl\EntityForm.cstemplate into the File name: box, and press Add.
Add the file c:\dsl\Program.cstemplate to the project in the same manner
Click on the EntityForm.cstemplate file in the Solution Explorer.
In the Properties window, enter the value TextTemplatingFileGenerator for the Custom Tool property, and press Enter.
Click on the Program.cstemplate file in the Solution Explorer.
In the Properties window, enter the value TextTemplatingFileGenerator for the Custom Tool property, and press Enter.
Code should be generated for both templates when the Custom Tool property is set. To regenerate the code, you can click on the Transform All Templates button in the Solution Explorer toolbar (circled in red below).
Set up the BizEntityDebugging solution to launch the BizEntityDebugging project. Right-click on the solution node in the Solution Explorer, and choose the Properties command.
Expand the Configuration Properties node in the Property Pages dialog box, and select the Configuration node. Check the Build checkbox.
Press OK on the Property Pages dialog box.
Press F5 to build and run the BizEntityDebugging project. You should see two forms pop up. Note that the title of each form corresponds to an entity defined in the business entity diagram, and there are editable text boxes corresponding to the attributes defined on each entity.
By now you may be running out of time for this lab, but if you still have a few extra minutes, there are a couple things you can do:
Examine the .cstemplate files and the resulting generated code. Note that the template files look similar to the .ReportTemplate file we examined in Task 7, except that the text to be generated is C# code rather than HTML.
Open the Entity.biz file and modify the diagram by adding more entities or attributes. Save the diagram and invoke Transform All Templates to see the effects of these changes on the generated artifacts.
Summary
In this lab, you explored how the Microsoft DSL Tools for Visual Studio 2005 can be used to build a visual designer with code generation. You learned more about the files that are used to define the concepts and notation for a Domain Specific Language, and the process that takes these files and generates a complete Visual Studio designer for that language. You learned some of the options for defining different aspects of the concepts and notation, and how the notation is mapped to the concepts. You ran the generated designer, and learned how to generate code and reports from the models that you created with it.
BrainDump 
Build a Domain Specific Language with DSL Tools
