You use domain relationships to establish relationships among domain classes in the definition of a domain-specific language. You can create embedding relationships and reference relationships by dragging the appropriate item from the Toolbox in the Domain-Specific Language Designer. For more information, see How to: Add an Embedding Relationship to a Domain-Specific Language Definition and How to: Add a Reference Relationship to a Domain-Specific Language Definition.
Embedding Relationships
In an embedding relationship, elements of the target domain class are embedded in elements of the source domain class. This type of relationship manifests itself in several ways. For example, embedded elements appear under their parents in the explorer of the generated designer. Embedded elements also appear as sub-elements of their parents in the XML representation of the model that contains the related elements. By default, embedded elements are automatically deleted if their parents are. A solid line in the diagram in the Domain-Specific Language Designer indicates an embedding relationship.
Every element in a domain-specific language must be the target of exactly one embedding relationship. This requirement is essential when the model is saved. The only exception is the Root element of a model, whose class is the Root element of the domain-specific language. The embedding links in a model form a tree. Because of this requirement, you must follow certain restrictions when you create embedding relationships in the definition of your domain-specific language:
Every class except for the root class must be the target of at least one embedding relationship.
The source role of the embedding relationship must have a maximum multiplicity of 1. This requirement ensures that the element or elements of the target domain class are not embedded in elements of more than one source class.
If a class is the target of more than one embedding relationship, each relationship must have a multiplicity of 0..1, instead of 1..1, at the source role. This requirement ensures that you are not forced to have more than one parent of different classes.
For more information, see Roles and Multiplicities later in this topic.
Reference Relationships
In a reference relationship, elements of the source domain class reference elements of the target domain class. Referenced elements do not appear in the explorer of the generated designer, but they might appear in the properties of the referring element. The referring element might also appear in the properties of the referenced element. In the XML representation of the model that contains the related elements, a reference to the referenced element appears as a sub-element of the XML element that represents the referring element. Reference links form a directed graph. A dashed line on the diagram in the Domain-Specific Language Designer indicates a reference relationship.
Roles
Each domain relationship has two roles. Each role appears in the designer as a line between a domain class and a domain relationship. For example, the following illustration shows a line between the Family domain class and the FamilyHasPeople domain relationship. This line represents a source role. Similarly, the line between the FamilyHasPeople domain relationship and the Person domain class represents a target role.
注意
This example is based on the domain classes and domain relationships that are defined in Walkthrough: Customizing the Domain-Specific Language Definition.
Domain Relationship
.png "Domain Relationship Overview")
The Name property of a role is the name that is used in programming to navigate from a domain relationship to one of the domain classes that it connects. The PropertyName property of a role is used to navigate from an element to the element or elements that are linked to it by the relationship. The DisplayName property of a role is used in the explorer of thegenerated designer to show relationships between elements and when you generate custom code and templates. By default, the value of the DisplayName property is the same as that of the Name property unless the value of the Name property is camel-cased. In such a case, the string is separated into multiple words. For example, a Name property whose value is NameTextExample gives the DisplayName property a value of Name Text Property.
Multiplicities
Multiplicities specify how many links of a domain relationship can have a particular element playing the role. For example, in the illustration that appears earlier in this topic, the zero to many (0..*) multiplicity setting on the FamilyMembers role specifies that any instance of the Family domain class can have as many links of the FamilyHasPeople relationship connected to it as you want. In contrast, the multiplicity setting of one (1..1) on the Family role specifies that each instance of the Person domain class can have only a single link to the FamilyHasPeople relationship.
In most cases, the number of links that are connected to a given element is the same as the number of elements that are connected through those links. As the example shows, if an instance of the Family domain class has five members, it necessarily has five links to the FamilyHasPeople relationship. However, for many-many relationships, more than one link might connect the same two elements. To control these cases, each domain relationship has an AllowDuplicates property, which you can set to true only if both roles have a maximum multiplicity of many. If this property is set to true, it is valid for a model to have more than one link that connects the same pair of elements. Otherwise, you cannot create such duplicate links.
You configure the multiplicity by modifying the Multiplicity property in the Properties window. The following table describes the settings for this property:
Multiplicity type |
Description |
|---|---|
0..* (Zero to many) |
Each instance of the class on the role that has this multiplicity can have multiple links of this relationship, or each instance can have no links of this relationship. |
0..1 (Zero to one) |
Each instance of the class on the role that has this multiplicity can have no more than a single link of this relationship, or each instance can have no links of this relationship. |
1..1 (One) |
Each instance of the class on the role that has this multiplicity should have a single link of this relationship. You cannot create more than one link of this relationship from any instance of the role class. If validation is enabled, a validation error will appear if any instance of the role class has no link of this relationship. |
1..* (One to many) |
Each instance of the class on the role that has this multiplicity can have multiple links of this relationship, and each instance should have at least one. If validation is enabled, a validation error will appear if any instance of the role class has no link of this relationship. |
See Also
Concepts
Walkthrough: Customizing the Domain-Specific Language Definition
How to: Access a Link and Roles at Both Ends
Domain Relationships in the Generated API
Overview of Derived Classes and Derived Relationships
Domain-Specific Language Designer Terminology Overview
Customizing XML Serialization Behavior in Domain-Specific Language Explorer