How to: Add Element Merge Directives

Article
11/16/2012

An element merge directive specifies what happens when one model element is added to another model element. There are two kinds of merge directive, a process merge directive and a forward merge directive. A process merge directive specifies that the element to be merged, also known as the indexing element, is linked to the target element by a domain relationship. A forward merge directive specifies that the indexing element is forwarded to a different target element. Merge directives can be set on domain classes, domain relationships, shapes, connectors, and diagrams.

You can add custom code to merge directives. By using the Uses custom accept option, you can write code to determine whether a particular instance of the indexing element should be merged into the target element. By using the Uses custom merge option, you can write code to customize the merge itself. For example, you may want to set fields in the target element when an indexing element has been merged. By using the Applies to subclasses option, you can program the merge to apply not only to the indexing element but also to its subclasses.

Adding a Process Element Merge Directive

A process merge directive adds a domain relationship between a target element and an indexing element. An example of a process merge directive is the Comment merge directive in the ComponentModel domain class in the Component Model solution template. The Comment merge directive specifies that a ComponentModelHasComments embedding relationship is created when a Comment domain class is merged with a ComponentModel domain class. The DSL Details window displays the following domain path: ComponentModelHasComments.Comments

Note

Whenever you create an embedding relationship between two model elements on the diagram, a process element merge directive is created.

The following procedure shows how to add a process element merge directive that adds an ExampleElementHasComments embedding relationship to the ExampleElement domain class.

To add a process element merge directive to the ExampleElement domain class

Create a Minimal Language solution.

For more information about how to open a Domain-Specific Language Tools solution, see Walkthrough: Creating a Domain-Specific Language Solution.
Display the diagram by opening DslDefinition.dsl.
Add a domain class and name it Comment.
Create an embedding relationship between the ExampleElement domain class and the Comment domain class by clicking Add new Domain Relationship at the root of the model in the DSL Explorer and then filling in the source and target roles.

Note

If you draw the relationship on the diagram, the element merge directive is set up automatically.
In the DSL Explorer, right-click the ExampleElement domain class (under the Domain Classes node), and then click Add New Element Merge Directive.

A node named Element Merge Directive is added under the Element Merge Directives node of ExampleElement.
Select the new node and open the DSL Details window.

The DSL Details - Merge Directive window appears.
In the Indexing class list, select Comment.
Select Process merge by creating links at paths.
In the <add path> box, select the path of the Comment domain class. This path should resemble ExampleElement HasComments.Comments.
Select Uses custom accept to specify custom code.

If you select this option, a method named CanMergeComments will appear in the generated ExampleElement.CanMerge method. You must implement this method to determine whether a given instance of the Comment class should be accepted for merging into the ExampleElement class.

In Solution Explorer, create a folder in the Dsl project and name it CustomCode (or another name). Add a class file that has the following code, and change the namespace name to a name that is appropriate for you.

using DslModeling = global::Microsoft.VisualStudio.Modeling;
namespace YourNamespace
{
    public partial class ExampleElement
    {
        protected bool CanMergeComment(DslModeling::ProtoElementBase rootElement, DslModeling::ElementGroupPrototype elementGroupPrototype)
        {
            //if there are no other comments, add it
            If (this.Comments.Count == 0)
               return true;
        }
    }
}

Select Uses custom merge to specify that you want to create custom code for the merge.

If you select this option, the path is ignored, and you must implement the ExampleElement.MergeRelate and ExampleElement.MergeDisconnect methods in the partial class that you added earlier. In the following example, when a Comment is added to an ExampleElement.Comments collection, the Comment.Date domain property is set to the current date. If a Comment is deleted, the link is also deleted.

    private void MergeRelate(DslModeling::ModelElement sourceElement, DslModeling::ElementGroup elementGroup)
    {
        Comment comment = sourceElement as Comment;
        if (comment != null)
        {
            // add to the collection. 
            this.Comments.Add(comment);

            comment.Date = DateTime.Now.ToString();
        }
    }
    private void MergeDisconnect(DslModeling::ModelElement sourceElement)
    {
        Comment comment = sourceElement as Comment;
        if (comment != null)
        {
            foreach (DslModeling::ElementLink link in global::YourNamespace.ExampleElementHasComments.GetLinks((global::YourNamespace. ExampleElement)this, comment))
            {
                //Delete the link
                link.Delete(global::YourNamespace.ExampleElementHasComments.ExampleElementDomainRoleId, global::YourNamespace.ExampleElementHasComments.CommentDomainRoleId);
            }
            return;
        }
    }

Select Applies to subclasses so that any subclasses of Comment can be merged automatically with ExampleElement.

Adding a Forward Merge Directive

A forward merge directive changes the target of a domain relationship between an indexing element and a target element. Instead of embedding Class A in Class B, a forward merge directive can embed Class A to the parent of Class B. For example, ports are embedded to components, but cannot be embedded to other ports. You can create a forward merge directive that embeds a port to the component of another port.

You can create a forward merge directive in the Component Model solution. If you compile and run the original solution, you should see that users can drag any number of Input Port or Output Port elements from the Toolbox to a Component element, but they cannot drag a port to an existing port. The Unavailable pointer alerts them that this move is not enabled. However, you can create a forward merge directive so that a port that is inadvertently dropped on an existing Input Port is forwarded to the Component element.

To create a forward merge directive

Create a Domain-Specific Language Tools solution by using the Component Model template.
Display the DSL Explorer by opening DslDefinition.dsl.
In the DSL Explorer, expand Domain Classes.
The ComponentPort abstract domain class is the base class of both InPort and OutPort. Right-click ComponentPort and then click Add New Element Merge Directive.

A new Element Merge Directive node appears under the Element Merge Directives node.
Select the Element Merge Directive node and open the DSL Details window.
In the Indexing class list, select ComponentPort.
Select Forward merge to a different domain class.
In the path selection list, expand ComponentPort, expand ComponentHasPorts, and then select Component.

The new path should resemble this one:

ComponentHasPorts.Component/!Component
Save the solution, and then transform the templates by clicking the rightmost button on the Solution Explorer toolbar.
Build and run the solution. A new instance of Visual Studio appears.
In Solution Explorer, open Sample.mydsl. The diagram and the ComponentLanguage Toolbox appear.
Drag an Input Port from the Toolbox to another Input Port. Next, drag an OutputPort to an InputPort and then to another OutputPort.

You should not see the Unavailable pointer, and you should be able to drop the new Input Port on the existing one. Select the new Input Port and drag it to another point on the Component.

Change History

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

Share via

How to: Add Element Merge Directives

Adding a Process Element Merge Directive

To add a process element merge directive to the ExampleElement domain class

Adding a Forward Merge Directive

To create a forward merge directive

See Also

Other Resources

Change History

Additional resources