Getting Started With Domain-Specific Languages

9/2/13 Getting Started with Domain-Specific Languages

msdn.microsoft.com/en-us/library/ee943825.aspx 1/14

Getting Started with Domain-SpecificLanguages

This topic explains the basic concepts in defining and using a domain-specific language (DSL).

If you are new to DSLs, we recommend that you work through the DSL Tools Lab, which you can find in this

site: Visualizaton and Modeling SDK

What can you do with a Domain-Specific Language?

A domain-specific language is a notation, usually graphical, that is designed to be used for a particular

purpose. By contrast, languages such as UML are general-purpose. In a DSL, you can define the types of

model element and their relationships, and how they are presented on the screen.

When you have designed a DSL, you can distribute it as part of a Visual Studio Integration Extension (VSIX)

package. Users work with the DSL in Visual Studio:

The notation is only part of a DSL. Together with the notation, your VSIX package includes tools that users

can apply to help them edit and generate material from their models.

One of the principal applications of DSLs is to generate program code, configuration files, and other

artifacts. Especially in large projects and product lines, where several variants of a product will be created,

generating many of the variable aspects from DSLs can provide a large increase in reliability and a very

rapid response to requirements changes.

The rest of this overview is a walkthrough that introduces the basic operations of creating and using a

domain-specific language in Visual Studio.

Visual Studio 2012 4 out of 4 rated this helpful

http://go.microsoft.com/fwlink/?LinkID=186128



domain-specific language in Visual Studio.

Prerequisites

To define a DSL, you must have installed the following components:

Visual Studio http://go.microsoft.com/fwlink/?LinkId=185579

Visual Studio SDK http://go.microsoft.com/fwlink/?LinkId=185580

Visual Studio Visualization and Modeling SDK http://go.microsoft.com/fwlink/?LinkID=186128

Creating a DSL Solution

To create a new domain-specific language, you create a new Visual Studio solution by using the Domain-

Specific Language project template.

To create a DSL solution

1. On the File menu, point to New, and then click Project.

2. Under Project types, expand the Other Project Types node, and click Extensibility.

3. Click Domain-Specific Language Designer.

http://go.microsoft.com/fwlink/?LinkId=185579

http://go.microsoft.com/fwlink/?LinkId=185580




4. In the Name box, type FamilyTree. Click OK.

The Domain-Specific Language Wizard opens, and displays a list of template DSL solutions.

Click each template to see a description,

The templates are useful starting points. Each of them provides a complete working DSL, which you

can edit to suit your needs. Ordinarily, you would choose the template nearest what you want to

create.

5. For this walkthrough, choose the Minimal Language template.

6. Enter a file name extension for your DSL in the appropriate wizard page. This is the extension that

files containing instances of your DSL will use.

Choose an extension that is not associated with any application in your computer, or in any

computer where you want to install the DSL. For example, docx and htm would be

unacceptable file name extensions.

The wizard will warn you if the extension that you have entered is being used as a DSL.

Consider using a different file name extension. You can also reset the Visual Studio SDK

Experimental instance to clear out old experimental designers. Click Start, click All Programs,

Microsoft Visual Studio 2010 SDK, Tools, and then Reset the Microsoft Visual Studio 2010

Experimental instance.

7. Inspect the other pages and then click Finish.

A solution is generated that contains two projects. They are named Dsl and DslPackage. A diagram

file opens that is named DslDefinition.dsl.

Note

Most of the code that you can see in the folders in the two projects is generated from

DslDefinition.dsl. For this reason, most modifications to your DSL are made in this file.

The user interface now resembles the following picture.

This solution defines a domain specific language. For more information, see Overview of the Domain-

Specific Language Tools User Interface.

http://msdn.microsoft.com/en-us/library/bb126469.aspx



Specific Language Tools User Interface.

The important parts of the DSL solution

Notice the following aspects of the new solution.

Dsl\DslDefinition.dsl This is the file that you see when you create a DSL solution. Almost all the

code in the solution is generated from this file, and most of the changes that you make to a DSL

definition are made here. For more information, see Working with the Working with the DSL Definition

Diagram.

Dsl project This project contains code that defines the domain-specific language.

DslPackage project This project contains code that allows instances of the DSL to be opened and

edited in Visual Studio.

Running the DSL

You can run the DSL solution as soon as you have created it. Later, you can modify the DSL definition

gradually, running the solution again after each change.

To experiment with the DSL

1. Click Transform All Templates in the Solution Explorer toolbar. This regenerates most of the source

code from DslDefinition.dsl.

Note

Whenever you change DslDefinition.dsl, you must click Transform All Templates before you

rebuild the solution. You can automate this step. For more information, see How to Automate

Transform All Templates.

2. Press F5, or on the Debug menu, click Start Debugging.

The DSL builds and is installed in the experimental instance of Visual Studio.

An experimental instance of Visual Studio starts. The experimental instance takes its settings from a

separate subtree of the registry, where Visual Studio extensions are registered for debugging

purposes. Normal instances of Visual Studio do not have access to extensions registered there.

3. In the experimental instance of Visual Studio, open the model file named Test from Solution

Explorer.

- or -

Right-click the Debugging project, point to Add, and then click Item. In the Add Item dialog box,

select the file type of your DSL.



http://msdn.microsoft.com/en-us/library/ff521399.aspx



The model file opens as a blank diagram.

The toolbox opens and displays tools appropriate to the diagram type.

4. Use the tools to create shapes and connectors on the diagram.

a. To create shapes, drag from the Example Shape tool onto the diagram.

b. To connect two shapes, click the Example Connector tool, click the first shape, and then click

the second shape.

5. Click the labels of the shapes to change them.

Your experimental Visual Studio will resemble the following example:

The Content of a Model

The content of a file that is an instance of a DSL is called a model. The model contains model elements and

links between the elements. The DSL definition specifies what types of model elements and links can exist

in the model. For example, in a DSL created from the Minimal Language template, there is one type of

model element, and one type of link.

The DSL definition can specify how the model appears on a diagram. You can choose from a variety of

styles of shapes and connectors. You can specify that some shapes appear inside other shapes.

You can view a model as a tree in the Explorer view while you are editing a model. As you add shapes to

the diagram, the model elements also appear in the explorer. The explorer can be used even if there is

no diagram.

If you cannot see the Explorer in the debugging instance of Visual Studio, on the View menu point to

Other Windows, and then click <Your Language> Explorer.

The API of your DSL

Your DSL generates an API that allows you to read and update models that are instances of the DSL. One

application of the API is to generate text files from a model. For more information, see Design-Time Code

Generation by using T4 Text Templates.

http://msdn.microsoft.com/en-us/library/dd820620.aspx



Generation by using T4 Text Templates.

In the Debugging solution, open the template files with extension ".tt". These samples demonstrate how

you can generate text from models, and allow you to test the API of your DSL. One of the samples is

written in Visual Basic, the other in Visual C#.

Under each template file is the file that it generates. Expand the template file in Solution Explorer, and

open the generated file.

The template file contains a short segment of code that lists all the elements in the model.

The generated file contains the result.

When you change a model file, you will see corresponding changes in generated files after you

regenerate the files.

To regenerate text files after you change the model file

1. In the experimental instance of Visual Studio, save the model file.

2. Make sure that the file name parameter in each .tt file refers to the model file that you are using

for experiments. Save the .tt file.

3. Click Transform All Templates in the toolbar of Solution Explorer.

- or -

Right-click the templates that you want to regenerate and then click Run Custom Tool.

You can add any number of text template files to a project. Each template generates one result file.

Note

When you change the DSL definition, the sample text template code will not work, unless you update it.

For more information, see Generating Code from a Domain-Specific Language and Writing Code to

Customise a Domain-Specific Language.

Customizing the DSL

When you want to modify the DSL definition, close the experimental instance and update the definition in the

main Visual Studio instance.

Note

After you have modified the DSL definition, you might lose information in the test models that you have

created by using earlier versions. For example, the debugging solution contains a file that is named

Sample, which contains some shapes and connectors. After you start to develop your DSL definition, they

will not be visible, and they will be lost when you save the file.






will not be visible, and they will be lost when you save the file.

You can make a wide variety of extensions to your DSL. The following examples will give you an impression

of the possibilities.

After each change, save the DSL definition, click Transform All Templates in Solution Explorer, and then

press F5 to experiment with the changed DSL.

Rename the Types and Tools

Rename the existing domain classes and relationships. For example, starting from a Dsl Definition created

from the Minimal Language template, you could perform the following renaming operations, to make the

DSL represent family trees.

To rename domain classes, relationships and tools

1. In the DslDefinition diagram, rename ExampleModel to FamilyTreeModel, ExampleElement to

Person, Targets to Parents, and Sources to Children. You can click each label to change it.

2. Rename the element and connector tools.

a. Open the DSL Explorer window by clicking the tab under Solution Explorer. If you cannot see

it, on the View menu point to Other Windows and then click DSL Explorer. DSL Explorer is

visible only when the DSL Definition diagram is the active window.

b. Open the Properties window and position it so that you can see DSL Explorer and

Properties at the same time.

c. In DSL Explorer, expand Editor, Toolbox Tabs, <your DSL>, and then Tools.

d. Click ExampleElement. This is the toolbox item that is used to create elements.

e. In the Properties window, change the Name property to Person.

Notice that the Caption property also changes.

f. In the same manner, change the name of the ExampleConnector tool to ParentLink. Alter



f. In the same manner, change the name of the ExampleConnector tool to ParentLink. Alter

the Caption property so that it is not a copy of the Name property. For example, enter

Parent Link.

3. Rebuild the DSL.

a. Save the DSL Definition file.

b. Click Transform All Templates in the toolbar of Solution Explorer

c. Press F5. Wait until the experimental instance of Visual Studio appears.

4. In the Debugging solution in the experimental instance of Visual Studio, open a test model file.

Drag elements onto it from the toolbox. Notice that the tool captions and the type names in DSL

Explorer have changed.

5. Save the model file.

6. Open a .tt file and replace occurrences of the old type and property names with the new names.

7. Make sure that the file name that is specified in the .tt file specifies your test model.

8. Save the .tt file. Open the generated file to see the result of running the code in the .tt file. Verify

that it is correct.

Add Domain Properties to Classes

Add properties to a domain class, for example to represent the years of birth and death of a Person.

To make the new properties visible on the diagram, you must add decorators to the shape that displays

the model element. You must also map the properties to the decorators.

To add properties and display them

1. Add the properties.

a. In the DSL Definition diagram, right-click the Person domain class, point to Add, and then

click Domain Property.

b. Type a list of new property names, such as Birth and Death. Press Enter after each one.

2. Add decorators that will display the properties in the shape.

a. Follow the gray line that extends from the Person domain class to the other side of the

diagram. This is a diagram element map. It links the domain class to a shape class.

b. Right-click this shape class, point to Add, and then click Text Decorator.

c. Add two decorators with names such as BirthDecorator and DeathDecorator.

d. Select each new decorator, and in the Properties window, set the Position field. This

determines where the domain property value will be displayed on the shape. For example,



determines where the domain property value will be displayed on the shape. For example,

set InnerBottomLeft and InnerBottomRight.

3. Map the decorators to the properties.

a. Open the DSL Details window. It is usually in a tab next to the Output window. If you cannot

see it, on the View menu, point to Other Windows, and then click DSL Details.

b. On the DSL definition diagram, click the line that connects the Person domain class to the

shape class.

c. In DSL Details, on the Decorator Maps tab, click the check box on an unmapped decorator.

In Display Property, select the domain property to which you want it mapped. For example,

map BirthDecorator to Birth.

4. Save the DSL, click Transform All Templates, and press F5.

5. In a sample model diagram, verify that you can now click the positions you chose and type values

into them. In addition, when you select a Person shape, the Properties window displays the new

properties Birth and Death.

6. In a .tt file, you can add code that obtains the properties of each person.



Define New Classes

You can add domain classes and relationships to a model. For example, you could create a new class to

represent towns, and a new relationship to represent that a person lived in a town.

To make the different types distinct on a model diagram, you can map the domain classes to different

kinds of shape, or to shapes with different geometry and colors.

To add and display a new domain class

1. Add a domain class and make it a child of the model root.

a. In the DSL Definition diagram, click the Embedding Relationship tool, click the root class

FamilyTreeModel, and then click in an empty part of the diagram.

A new domain class appears, that is connected to the FamilyTreeModel with an embedding

relationship.

Set its name, for example Town.

Note

Every domain class except the root of the model must be the target of at least one

embedding relationship, or it must inherit from a class that is the target of an

embedding. For this reason, it is frequently convenient to create a domain class by using

the Embedding Relationship tool.

b. Add a domain property to the new class, for example Name.

2. Add a reference relationship between Person and Town.

a. Click the Reference Relationship tool, click Person and then click Town.

Note

Reference relationships represent cross-references from one part of the model tree to



Reference relationships represent cross-references from one part of the model tree to

another.

3. Add a shape to represent towns on the model diagrams.

a. Drag a Geometry Shape from the toolbox to the diagram and rename it, for example

TownShape.

b. In the Properties window, set the Appearance fields of the new shape, such as Fill Color and

Geometry.

c. Add a Decorator to display the name of the town, and rename it NameDecorator. Set its

Position property.

4. Map the Town domain class to the TownShape.

a. Click the Diagram Element Map tool, then click the Town domain class, and then the

TownShape shape class.

b. In the Decorator Maps tab of the DSL Details window with the map connector selected,

check NameDecorator and set Display Property to Name.

5. Create a connector to display the relationship between Person and Towns.

a. Drag a Connector from the toolbox to the diagram. Rename it and set its appearance

properties.

b. Use the Diagram Element Map tool to link the new connector to the relationship between

Person and Town.

6. Create an element tool for making a new Town.

a. In DSL Explorer, expand Editor then Toolbox Tabs.

b. Right-click <your DSL> and then click Add New Element Tool.

c. Set the Name property of the new tool, and set its Class property to Town.

d. Set the Toolbox Icon property. Click [...] and in the File name field, select an icon file.

7. Create a connector tool for making a link between towns and people.

a. Right-click <your DSL> and then click Add New Connector Tool.



a. Right-click <your DSL> and then click Add New Connector Tool.

b. Set the Name property of the new tool.

c. In the ConnectionBuilder property, select the builder that contains the name of the Person-

Town relationship.

d. Set the Toolbox Icon.

8. Save the DSL Definition, click Transform All Templates, and then press F5.

9. In the experimental instance of Visual Studio, open a test model file. Use the new tools to create

towns and links between towns and persons. Notice that you can only create links between the

correct types of element.

10. Create code that lists the town in which each person lives. Text templates are one of the places

where you can run such code. For example, you could modify the existing Sample.tt file in the

Debugging solution so that it contains the following code:

When you save the *.tt file, it will create a subsidiary file that contains the list of people and their

residences. For more information, see Generating Code from a Domain-Specific Language.

Validation and Commands

You could develop this DSL further by adding validation constraints. These constraints are methods that you

can define, that make sure that the model is in a correct state. For example, you could define a constraint to

make sure that the birth date of a child is later than that of its parents. The validation feature displays a

<#@ template inherits="Microsoft.VisualStudio.TextTemplating.VSHost.ModelingTextTransformation" debug="true" #>

<#@ output extension=".txt" #>

<#@ FamilyTree processor="FamilyTreeDirectiveProcessor" requires="fileName='Sample.ftree'" #>

<#

foreach (Person person in this.FamilyTreeModel.People)

{

#>

<#= person.Name #><#if (person.Town != null) {#> of <#= person.Town.Name #> <#}#>

<#

foreach (Person child in person.Children)

{

#>

<#= child.Name #>

<#

}

}

#>




make sure that the birth date of a child is later than that of its parents. The validation feature displays a

warning if the DSL user tries to save a model that breaks any of the constraints. For more information, see

Validation in a Domain-Specific Language.

You can also define menu commands that the user can invoke. Commands can modify the model. They can

also interact with other models in Visual Studio and with external resources. For more information, see How

to: Modify a Standard Menu Command in a Domain-Specific Language.

Deploying the DSL

To allow other users to use the domain-specific language, you distribute a Visual Studio Extension (VSIX) file.

This is created when you build the DSL solution.

Locate the .vsix file in the bin folder of your solution. Copy it to the computer on which you want to install it.

On that computer, double-click the VSIX file. The DSL can be used in all instances of Visual Studio on that

computer.

You can use the same procedure to install the DSL on your own computer so that you do not have to use

the experimental instance of Visual Studio.

For more information, see Deploying Domain-Specific Language Solutions.

Removing old Experimental DSLs

If you have created experimental DSLs that you no longer want, you can remove them from your computer

by resetting the Visual Studio Experimental instance.

This will remove from your computer all experimental DSLs and other experimental Visual Studio extensions.

These are extensions that have been executed in debugging mode.

This procedure does not remove DSLs or other Visual Studio extensions that have been fully installed by

executing the VSIX file.

To reset the Visual Studio Experimental instance

1. Click Start, click All Programs, Microsoft Visual Studio 2010 SDK, Tools, and then Reset the

Microsoft Visual Studio 2010 Experimental instance.

2. Rebuild any experimental DSLs or other experimental Visual Studio extensions that you still want to

use.

See Also

Concepts

Understanding Models, Classes and Relationships





Getting Started With Domain-Specific Languages

Documents

Transcript of Getting Started With Domain-Specific Languages