Understanding the DSL Code

ConnectionBuilders.cs

A connection builder is a class that creates relationships. It is the code behind a connection tool. This file contains a pair of classes for each connection tool. Their names are derived from the names of the domain relationship and connection tool: RelationshipBuilder, and ConnectorToolConnectAction.

(In the component solution example, one of the connection builders is called ConnectionBuilder, This is a coincidence, because the domain relationship is named Connection.)

The relationship is created in the RelationshipBuilder.Connect() method. The default version verifies that the source and target model elements are acceptable, and then instantiates the relationship. For example:

CommentReferencesSubject(sourceAccepted, targetAccepted);

Each builder class is generated from a node in the Connection Builders section in DSL Explorer. One Connect method can create relationships between one or more pairs of domain classes. Each pair is defined by a Link Connect Directive, which you can find in DSL Explorer under the builder node.

For example, you could add to one connection builder Link Connect Directives for each of the three types of relationship in the sample DSL. This would provide the user with a single connection tool. The type of relationship instantiated would depend on the types of the source and target elements selected by the user. To add Link Connect Directives, right-click a builder in DSL Explorer.

To write custom code that runs when a specific type of domain relationship is created, select the appropriate Link Connect Directive under the builder node. In the Properties window, set Uses Custom Connect. Rebuild the solution, and then supply code to correct the resulting errors.

To write custom code that runs whenever the user uses this connection tool, set the Is Custom property of the connection builder. You can supply code that decides whether a source element is permitted, whether a specific combination of source and target is permitted, and what updates should be made to the model when a connection is made. For example, you could allow a connection only if it would not create a loop in the diagram. Instead of a single relationship link, you could instantiate a more complex pattern of several inter-related elements between the source and target.

Diagram.cs

Contains the class that defines the diagram. It is derived from Diagram.

To make the color and some other style features variable at run time, right-click the class on the DSL Definition diagram and point to Add Exposed.

In addition, this file contains the FixupDiagram rule, which responds when a new element is added to the model. The rule adds a new shape and links the shape to the model element.

DomainClasses.cs

Implementations of domain classes that you have defined, including abstract classes and the model root class. They are derived from ModelElement.

Each domain class contains:

• A property definition and a nested handler class for each domain property. You can override OnValueChanging() and OnValueChanged(). For more information, see Domain Property Value Change Handlers.

  In the example DSL, the Comment class contains a property Text and a handler class TextPropertyHandler.

• Accessor properties for the relationships in which this domain class participates. (There is no nested class for role properties.)

  In the example DSL, the Comment class has accessors that access its parent model through the embedding relationship ComponentModelHasComments.

• Constructors. If you want to override these, set Has Custom Constructor on the domain class.

• Element Group Prototype (EGP) handler methods. These are necessary if the user can merge (add) another element onto instances of this class. Typically the user does this by dragging from an element tool or another shape, or by pasting.

  In the example DSL, an Input Port or Output Port can be merged onto a Component. Also, Components and Comments can be merged onto the model. The

  The EGP handler methods in the Component class allow a Component to accept Ports, but not Comments. The EGP handler in the root model class accepts Comments and Components, but not Ports.

DomainModelResx.resx

This contains strings such as the descriptions of domain classes and properties, property names, toolbox labels, standard error messages, and other strings that could be displayed to the user. It also contains tool icons and images for image shapes.

This file is bound into the built assembly, and provides the default values of these resources. You can localize your DSL by creating a satellite assembly that contains a localized version of the resources. That version will be used when the DSL is installed in a culture matching the localized resources. For more information, see Deploying Domain-Specific Language Solutions.

HelpKeywordHelper.cs

Provides functions that are used when the user presses F1.

PropertiesGrid.cs

This file contains code only if you have attached a Custom Type Descriptor to a domain property. For more information, see Customizing the Properties Window.

Serializer.cs

A serializer class for each domain class, relationship, shape, connector, diagram, and model.

Many of the features of these classes can be controlled by the settings in DSL Explorer under Xml Serialization Behavior.

ToolboxHelper.cs

Sets up the toolbox by installing element group prototypes into the element tools. Copies of these prototypes are merged with the target elements when the user runs the tool.

You could override CreateElementPrototype() to define a toolbox item that creates a group of several objects. For example, you could define an item to represent objects that have sub-components. After changing the code, reset the experimental instance of Visual Studio to clear the toolbox cache.

Constants.cs

GUIDs.

DocView.cs

YourDslDocView manages the window in which the diagram appears. For example, you could embed the diagram inside a windows Form:

Add a User Control file to the DslPackage project. Add a Panel in which the diagram can be displayed. Add buttons and other controls. In the code view of the form, add the following code, adjusting the names to your DSL:

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Drawing;
using System.Data;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using Microsoft.VisualStudio.Modeling;
using Microsoft.VisualStudio.Modeling.Shell;
namespace Company.EmbedInForm
{
  public partial class UserControl1 : UserControl
  {
    public UserControl1()
    {
      InitializeComponent();
    }
    
    private DiagramDocView docView;
    public UserControl1(DiagramDocView docView, Control content)
      : this()
    {
      this.docView = docView;
      panel1.Controls.Add(content);
    }
    private void button1_Click(object sender, EventArgs e)
    {
      ExampleModel modelRoot = this.docView.CurrentDiagram.ModelElement as ExampleModel;
      foreach (ExampleElement element in modelRoot.Elements)
      {
       listBox1.Items.Add(element.Name);
      }
    }
  }
  internal partial class EmbedInFormDocView
  {
    private ContainerControl container;
    /// <summary>
    /// Return a User Control instead of the DSL window. 
    /// The user control will contain the DSL window.
    /// </summary>
    public override System.Windows.Forms.IWin32Window Window
    {
      get
      {
        if (container == null)
        {
          // Put the normal DSL Window inside our control
          container = new UserControl1(this, (Control)base.Window);
        }
        return container;
      }
    }
  }
}

GeneratedVSCT.vsct

Locates the standard menu commands on menus, such as the diagram context menu, the Edit menu, and so on. The code for the commands is in CommandSet.cs. You can relocate or modify the standard commands, and you can add your own commands. For more information, see Writing User Commands and Actions.

ModelExplorerToolWindow.cs

Defines the window in which the model explorer is displayed. Handles the selection of items in the explorer.

Source.extension.vsixmanifest

To customize this file, edit the .tt file.

This file controls how the DSL is packaged into a Visual Studio Integration Extension (VSIX). For more information, see Deploying Domain-Specific Language Solutions.