Walkthrough: Customizing the Domain-Specific Language Definition

Article
11/16/2012

This walkthrough teaches how to customize the FamilyTree domain-specific language that is created in Walkthrough: Creating a Domain-Specific Language Solution.

Prerequisites

Complete the steps in Walkthrough: Creating a Domain-Specific Language Solution.

Updating the Domain Model

The following procedure shows how to change the domain model.

To update the domain-specific language definition

Open the FamilyTree solution that you created by completing Walkthrough: Creating a Domain-Specific Language Solution.
In Solution Explorer, open DslDefinition.dsl in the Dsl project.
In the DSL Explorer, double-click the name of the ExampleModel domain class and type Family.

This action changes the Name property, which appears in the Properties window. If you change the Name property, the value of the DisplayName property typically is also changed to match. However, if you have previously changed the DisplayName property so that it does not match the Name property, the DisplayName property will not be changed.

Note

If the Properties window does not appear, press F4.
Double-click the name of the ExampleElement domain class and type Person.
Double-click the name of the FamilyHasElements domain relationship and type FamilyHasPeople.

Instances of the FamilyHasPeople domain relationship are links between instances of the Family domain class and instances of the Person domain class. The FamilyHasPeople domain relationship is an embedding relationship. This means that the Person element is embedded, or nested, under the Family element.

The FamilyHasPeople domain relationship has two roles, one on each side. The line between the Family domain class and the FamilyHasPeople domain relationship represents the source role, and the line between the FamilyHasPeople domain relationship and the Person domain class represents the target role. For more information about domain relationships and roles, see Domain Relationships.
Select the source role (between the FamilyHasPeople domain relationship and the Family domain class). It has a Property Name value of Elements. This is the identifier that is displayed on the diagram. In the Properties window, set the Property Name value to People.
Select the target role (between the FamilyHasPeople domain relationship and the Person domain class). It has a Property Name value of Family.
The domain relationship named PersonReferencesTargets is a reference relationship. This means that it links elements from different places in the model.

Select the source role on the diagram (the one to the left of the PersonReferencesTargets relationship). In the Properties window, set the Property Name value to Children.

The name of the domain relationship becomes PersonReferencesChildren.

Select the target role on the diagram (the one to the right of domain relationship). In the Properties window, set the Property Name value to Parents.
Change the name of the domain relationship to ParentsHaveChildren.
Click the expand/collapse chevrons in one of the Person domain classes on the diagram.

The header for the list of domain properties for the Person domain class appears. You may have to click the plus sign (+) next to the Domain Properties header to display the list of properties.

The list of properties for the Person domain class appears. It includes the Name property.
Right-click Domain Properties, and then click Add new Domain Property.
In the Properties window, type Birth for the value of the Name property.
Select the Type property, click the down arrow for that property, and select Int32.
In the Person domain class, right-click the Domain Properties header, and then click Add new Domain Property.
In the Properties window, type Death for the value of the Name property.
Select the Type property, and then select Int32.

Updating the Shapes Definitions

Shapes definitions define the appearance of domain classes and domain relationships in the generated designer.

To update the shapes definitions

In the Diagram Elements swimlane, double-click the name of the ExampleShape geometry shape, and then change it to PersonShape.

The Diagram Elements swimlane defines the visual presentation of the model as shapes and connectors on the screen.
Change the name of the Example Connector connector to ParentChildConnector.
Right-click the Decorators header on the PersonShape geometry shape, and then click Add New Text Decorator.
Right-click the name of the decorator that you just added, click Edit, and then type BirthYearDecorator.
On the View menu, point to Other Windows, and then click DSL Details.
Select the line between the Person domain class and the PersonShape geometry shape.

This line represents the mapping relationship between those two elements.
In the DSL Details window, click the Decorator Maps tab.
Under Decorators, select BirthYearDecorator.
Under DisplayProperty, click Birth.

This step guarantees that the BirthYearDecorator text decorator of the PersonShape geometry shape displays the Birth property in the model.
Close the DSL Details window.

Updating the Toolbox Definitions

Now, update the Toolbox definitions to complete the customization of the domain-specific language definition.

To update the Toolbox definition and complete the domain-specific language definition

In the DSL Explorer, expand the Editor node, expand the Toolbox Tabs node, expand the FamilyTree node, and then expand the Tools node.
Select the ExampleElement tool. In the Properties window, select the Name property and type Person.
Select the ExampleRelationship tool. In the Properties window, select the Name property and type ParentsHaveChildren.
Save the file, and then on the Solution Explorer toolbar, click Transform All Templates.

The system regenerates the code for the solution, and saves Designer.dsl.

Note

For information about the XML format of definition files, see The DslDefinition.dsl File

Exercising the Language

The next step is to build and run the domain-specific language designer in a new instance of Visual Studio so that you can test it. This instance of Visual Studio runs in the experimental registry hive and represents the integrated development environment (IDE) of the language user. (The language is available in the experimental registry hive only until you create and run an installer. For more information, see Deploying Domain-Specific Language Solutions.)

To exercise the language

On the Build menu click Rebuild Solution.
On the Debug menu, click Start Debugging.

The experimental build of Visual Studio opens the Debugging solution, which contains an empty test file.
In the experimental build, double-click Test.ftree in Solution Explorer.

A designer opens for the FamilyTree language that you created.
Drag a Person element from the Toolbox to the diagram surface.
Double-click the name of the Person element and type Mother.
In the Properties window, double-click the Birth property and type 1921.
Drag another Person element from the Toolbox to the diagram surface.
Double-click the name of this Person element and type Grandfather.
In the Properties window, double-click the Birth property and type 1944.
In the Toolbox, click Connect Parent to Child.

In the designer, click the Grandfather shape, and then click the Mother shape.

This establishes the Parent relationship.

Important Note:
In the real world, the birth date of a child must be more recent than those of the parents. To prevent users from entering invalid data, you can add validation to the model by completing Walkthrough: Adding Validation to a Domain Model.

Save the solution, and then close the experimental build.

Next Steps

You can add validation to the Family Tree domain model by following the steps in Walkthrough: Adding Validation to a Domain Model.

Change History

Date	History	Reason
July 2008	Rewrote and refactored project.	Content bug fix.