How to: Navigate Links

A link connects two model elements. A link is an instance of a domain relationship type that you define in your DSL Definition. Links are themselves represented by model elements, and can have their own properties. There are two categories of links: embedding links and reference links. Typically, but not always, reference links are presented on a diagram as connectors between node shapes, and embedding links are represented by a node shape being contained inside a shape or diagram that represents its parent.

In program code, you can navigate across a link between the model elements that it connects, and you can obtain the properties of the link itself. You can also navigate to or from any connector or shape that presents the link on a diagram.

The following examples assume the DSL Definition in the Minimal Language project template. You might find it helpful to create a DSL solution from that template and refer to the DSL Definition while reading these examples.

Example

Navigating using role properties. When you define a domain relationship, you automatically define properties on the two domain classes at each end of the relationship. You can use these properties to create, read and update the links between relationships. Where you have defined the role to have a multiplicity of 0..1 or 1..1, the property has the type of the class at the opposite end of the relationship. For other multiplicities, the role property is a collection.

// Assume we have this instance:
ExampleElement e1 = ...;

// The relationship ExampleModelHasElements has a role "ExampleModel".
// Use the role property to navigate the relationship:
ExampleModel model = e1.ExampleModel; 

// ExampleElementReferencesTargets has a 0..* role "Targets":
foreach (ExampleElement target in e1.Targets) { ... }

// You can use extensions from System.Linq on the collections:
var spaceTargets = e1.Targets.Where(target => target.Name.Contains(' '));
var targetsOfTargets = e1.Targets.SelectMany(target => target.Targets);

In the DSL Definition diagram, the name of the role property is the label displayed above the role line at each side of a relationship rectangle. When you select the role line, it is appears as Property Name in the Properties window.

If in the DSL Definition, you set the Is Property Generator property on the role to false, then you cannot navigate the relationship using the role property.

Navigating using the domain relationship class. If a role property is not available, you can still traverse the link using methods on the relationship class.

// Traverse a link of the ExampleModelHasElements relationship
// - same result as e1.ExampleModel :
ExampleModel model2 = ExampleModelHasElements.GetExampleModel(e1);
// Same result as e1.Targets:
foreach (ExampleElement target in ExampleElementReferencesTargets.GetTargets(e1)) { }

Accessing the link element. Each link between two model elements is itself represented by a model element. You can access these link elements. In the DSL Definition, you can define properties on the domain relationship class. You can then assign values to the properties in each link.

ExampleModel model2 = ExampleModelHasElements.GetExampleModel(e1);
foreach (ExampleElement target in 
         ExampleElementReferencesTargets.GetTargets(e1)) { }

foreach (ExampleElementReferencesTargets outgoingLink in 
          ExampleElementReferencesTargets.GetLinksToTargets(e1))
{
  // Let's assume a property defined on this domain relationship:
  string linkPropertyValue = outgoingLink.ExampleLinkProperty;
        
  // Get from the link to one end or the other:
  ExampleElement otherEnd = outgoingLink.Target;
  ExampleElement e11 = outgoingLink.Source; // == e1
}
ExampleElement e2 = ...;
ExampleElementReferencesTargets linkFromE1ToE2 = 
      ExampleElementReferencesTargets.GetLink(e1, e2);
// If you have set AllowsDuplicates to true for the relationship,
// there can be more than one link between any pair of elements:
foreach (ExampleElementReferencesTargets aLinkFromE1ToE2 in 
      ExampleElementReferencesTargets.GetLinks(e1, e2))
{ ... }

See Also

Tasks

How to: Find Elements in the Store

Other Resources

Domain-Specific Language Tools Glossary

Change History

Date	History	Reason
	Rewritten.	Customer feedback.