Walkthrough: Customizing the Domain-Specific Language Definition

In this walkthrough, you customize a domain model for a domain-specific language. You update the FamilyTree domain-specific language, which you should have created already by using the steps in Walkthrough: Creating a Domain-Specific Language Solution.

Nota

When you install Domain-Specific Language Tools, you also install samples such as the FamilyTree sample on which this walkthrough is based. For more information, see Family Tree Sample.

Prerequisites

To complete this walkthrough, you must:

• Install Visual Studio 2008.

  Nota

  For a list of the editions that Domain-Specific Language Tools supports, see Supported Visual Studio Editions for Domain-Specific Language Tools.

• Install Visual Studio 2008 SDK.

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

Updating the Domain-Specific Language Definition

When you update a domain-specific language definition (DslDefinition.dsl in the Dsl project), you perform several tasks in different areas of the designer. You begin by updating the Classes and Relationships swimlane. To start this walkthrough, you open DslDefinition.dsl and make the following modifications.

To update the domain-specific language definition

1. Open the FamilyTree solution that you created in Walkthrough: Creating a Domain-Specific Language Solution.

2. In Solution Explorer, open DslDefinition.dsl in the Dsl project.

3. In the Domain-Specific Language Designer, 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, you also change the DisplayName property because these two properties are tracking properties. For more information, see Overview of Tracking Properties.

   Nota

   If the Properties window does not appear, press F4.

4. Double-click the name of the ExampleElement domain class, and type Person.

5. Double-click the name of the FamilyHasElements domain relationship, and type FamilyHasPeople.

   Every instance of the FamilyHasPeople domain relationship is a link between an instance of the Family domain class and an instance of the Person domain class. The FamilyHasPeople domain relationship is also an embedding relationship. This means that the links form a tree of paths by which each object can be uniquely identified.

   As in any domain relationship, the FamilyHasPeople domain relationship has a pair of roles. These roles represent the properties of the two ends of each role. Each role appears in the designer as a line between a domain class and a domain relationship. For example, the line between the Family domain class and the FamilyHasPeople domain relationship represents a source role, and the line between the FamilyHasPeople domain relationship and the Person domain class represents a target role. For more information about domain relationships and roles, see Overview of Domain Relationships.

6. Click the source role (between the FamilyHasPeople domain relationship and the Family domain class).

7. In the Properties window, double-click the role's Name property, and type FamilyMember.

8. Double-click the PropertyName property, and type FamilyMember.

9. Click the target role (between the FamilyHasPeople domain relationship and the Person domain class).

10. In the Properties window, double-click the role's Name property, and type Family.

11. Double-click the PropertyName property, and type Family.

12. Double-click the name of the PersonReferencesTargets domain relationship (between the Person domain class and itself), and type ParentChild.

    The ParentChild domain relationship is a reference relationship. This means that its links form cross-references across the tree of embedding links.

13. Click the source role for the ParentChild domain relationship. In the Properties window, double-click the Name property, and type Parent. Double-click the PropertyName property, and type Children.

14. Click the target role for the ParentChild domain relationship. In the Properties window, double-click the Name property, and type Child.

15. Click the expand/collapse chevrons in any appearance of the Person domain class.

    The header for the list of domain properties for the Person domain class appears.

16. If necessary, 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 String Name property.

17. Right-click the Domain Properties header, and click Add new Domain Property.

    Nota

    You can also add a domain property to a domain class by browsing to the domain class in DSL Explorer (which appears next to Solution Explorer next to the designer surface), right-clicking the domain class, and clicking Add New Domain Property.

18. In the Properties window, double-click the Name property, and type Birth.

19. Double-click the Type property, click the down arrow for that property, and click Int32.

20. In the Person domain class, right-click the Domain Properties header, and click Add new Domain Property.

21. In the Properties window, double-click the Name property, and type Death.

22. Double-click the Type property, click the down arrow for that property, and click Int32.

Updating the Shapes Definitions

The next step is updating the shapes definitions. This reflects how domain classes and domain relationships appear in the generated designer.

To update the shapes definitions

1. In the Diagram Elements swimlane, double-click the name of the ExampleShape geometry shape, and type PersonShape.

   The Diagram Elements swimlane defines the visual presentation of the model as shapes and connectors on the screen.

2. Double-click the name of the Example Connector connector, and type ParentChildConnector.

3. Right-click the Decorators header on the PersonShape geometry shape, and click Add New Text Decorator.

4. Right-click the name of the decorator that you just added, click Edit, and then type BirthYearDecorator.

5. On the View menu, point to Other Windows, and click DSL Details.

6. Click the line between the Person domain class and the PersonShape geometry shape.

   This line represents the mapping relationship between those two elements.

7. In the DSL Details window, click the Decorator Maps tab.

8. Under Decorators, select the BirthYearDecorator check box.

9. Under DisplayProperty, click Birth.

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

10. Close the DSL Details window.

Updating the Toolbox Definitions

In the next step, you update the Toolbox definitions. This will complete your customization of the domain-specific language definition.

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

1. In DSL Explorer, expand the Editor element, expand the Toolbox Tabs element, expand the FamilyTree element, and then expand the Tools element.

2. Click the ExampleElement tool. In the Properties window, double-click the Name property, and type Create Person.

3. Click the ExampleRelationship tool. In the Properties window, double-click the Caption property, and type Connect Parent to Child. Double-click the Name property, and type ParentChild.

4. Click Transform All Templates on the Solution Explorer toolbar.

   Nota

   When you create a project, the system automatically generates the default text templates. When you generate a text template, you will see a message warning you not to run text templates from untrusted sources. If you do not want this message to appear again, select the Do not show this message again check box, and click OK. Otherwise, click OK.

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

   Nota

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

Exercising the Language

The next step is to open the domain-specific language in a new instance of Visual Studio 2008 called the experimental build. For more information, see Experimental Build. In a domain-specific language, this instance represents the integrated development environment of the language user and runs in the experimental registry hive. (The language is available in the registry hive only until you create and run an installer. For more information, see Deploying Domain-Specific Language Solutions.)

To exercise the language

1. On the Build menu, click Rebuild Solution.

2. On the Debug menu, click Start Debugging.

   The experimental build opens the Debugging solution, which contains an empty test file.

3. In the experimental build, double-click Test.ftree in Solution Explorer.

   A designer opens for the FamilyTree language that you created.

4. Drag a Create Person element from the Toolbox to the diagram surface.

5. Double-click the name of the Person element, and type Mother.

6. In the Properties window, double-click the Birth property, and type 1921.

7. Drag a Create Person item from the Toolbox to the diagram surface.

8. Double-click the name of the Person shape that you just created, and type Grandfather.

9. In the Properties window, double-click the Birth property, and type 1944.

10. In the Toolbox, click Connect Parent to Child.

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

    This establishes the Parent relationship.

    Important Note:
    A child’s birth date must be more recent than those of its parents. To prevent users from entering invalid data, you can add validation to the model in Walkthrough: Adding Validation to a Domain Model.

12. 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.

See Also

Concepts

Family Tree Sample

Walkthrough: Creating a Domain-Specific Language Solution

Working with Domain Models Programmatically

Domain-Specific Language Designer Terminology Overview