How to: Edit and Customize Graph Documents

  • Article

In Visual Studio Ultimate, you can focus on key relationships and areas of a directed graph edit by editing the nodes and links. This is especially useful when the graph shows large amounts of information. For example, you can identify major components in an existing software system and the relationships between them. You can then share and discuss those areas of focus with your team members. For information about generating graphs from code, see How to: Generate Dependency Graphs for .NET Code.

To highlight areas of interest, you can select and filter nodes, apply predefined styles to nodes and links, and organize nodes into groups. You can customize the graph even further by editing the graph's Directed Graph Markup Language (DGML) file. For example, you can edit the DGML elements in the file to specify custom styles, assign properties and categories to nodes and links, or link nodes to items, such as documents, URLs, and other .dgml files. For more information about DGML elements, see Understanding Directed Graph Markup Language (DGML).

Note

Visual Studio cleans up any unused DGML elements and attributes by deleting them when you save the .dgml file. It also creates node elements automatically when you manually add new links. When you save the .dgml file, any attributes that you added to an element might rearrange themselves in alphabetical order.

You can edit a graph in the following ways:

  • Select nodes

  • Hide or show nodes

  • Show or hide links

  • Change the style of the graph

  • Change the style of nodes and links

  • Copy styles from one graph to another graph

  • Organize nodes into groups

  • Assign properties to nodes and links

  • Assign categories to nodes and links

  • Link items to nodes

  • Create aliases for commonly-used paths

Select Nodes

To

Perform these steps

Select nodes from specific categories

  1. Right-click the graph, and then click Show Advanced Selection.

  2. In the Selection box, under Categories, click the categories that you want.

To create and assign a custom category, see Assign Categories to Nodes and Links.

Select nodes with specific properties or property values

  1. Right-click the graph, and then click Show Advanced Selection.

  2. In the Selection box, under Properties, click the properties that you want. To select specific property values, expand the property.

Add related nodes to selected ones

Right-click the selected nodes, point to Selection, and then choose one of the following:

  • To add nodes that link directly to the selected node, click Select Incoming.

  • To add nodes that link directly from the selected node, click Select Outgoing.

  • To add nodes that link directly to and from the selected node, click Select Both.

  • To add all nodes that link to and from the selected node, click Select All Connected.

  • To add all children of the selected node, click Select Children.

Select all unselected nodes

Right-click the selected nodes, point to Selection, and then click Invert.

Hide or Show Nodes

Hiding nodes on the graph removes them from appearing on the graph and participating in any layout algorithms.

To

Perform these steps

Hide selected nodes

  1. Select the nodes that you want to hide.

  2. Right-click the selected nodes or the graph, point to Selection, and then click Hide.

Hide nodes with certain categories or properties

  1. To display the Selection box, right-click the graph surface, and then click Show Advanced Selection

  2. In the Selection box, click the categories or properties that you want.

  3. Right-click the graph surface, point to Selection, and then click Hide.

Hide unselected nodes

  1. Select the nodes that you do not want to hide.

  2. Right-click the selected nodes or the graph, point to Selection, and then click Hide Unselected.

Show all hidden nodes

Right-click the graph, point to Selection, and then click Unhide All.

To hide nodes by editing the .dgml file

  1. Right-click the graph surface, and then click View DGML.

    Visual Studio opens the graph's .dgml file.

  2. In the <Node/> element, add the following attribute to hide the node:

    Visibility="Hidden"

    For example:

    <Nodes>
   <Node Id="MyNode" Visibility="Hidden"/>
</Nodes>

You can control the amount of detail on a graph by specifying the kinds of links that you want to see. The graph shows two kinds of links: direct links between nodes and cross-group links, which are hidden by default. Cross-group links are all the individual links that connect nodes across different groups.

When groups are collapsed, the graph aggregates all the cross-group links into single links between groups. When groups are expanded, you can select nodes inside the group, and new cross-group links appear and show the actual dependencies inside that group.

  1. If the graph toolbar is not visible, on the View menu, point to Toolbars, and then click Directed Graph.

  2. Select a task from the following table:

    To

    Click

    Show all cross-group links at all times

    Show All Cross-Group Links

    Show only those links cross-group links that are connected to selected nodes

    Show Cross-Group Links On Selected Nodes

    Hide all cross-group links at all times

    Hide All Cross-Group Links

    Hide all links (or show all links)

    Hide All Links

    To show all links, click Hide All Links again to turn off this mode.

Change the Style of the Graph

You can change the background color and border color of the graph by editing the graph's .dgml file. To change the style of nodes and links, see Change the Style of Nodes and Links.

To change the style of the graph

  1. Right-click the graph surface, and then click View DGML.

    Visual Studio opens the graph's .dgml file.

  2. In the <DirectedGraph> element, add any of the following attributes to change its style:

    To change the

    Add the following attribute

    Background color

    		 
    Background="ColorNameOrHexadecimalValue"

    Border color

    		 
    Stroke="StrokeValue"

    For example:

    <DirectedGraph Background="Green" xmlns="https://schemas.microsoft.com/vs/2009/dgml" >
   ...
   ...
</DirectedGraph>

You can change the icons on nodes and the colors of nodes and links. You can use predefined colors and icons, or you can specify custom ones by editing the graph's .dgml file. For more information, see Apply Custom Styles to Nodes and Links.

For example, you can choose a color to highlight nodes and links that have a certain category or property. This lets you identify and focus on specific areas of the graph.

To apply a predefined color or icon to nodes with a certain category or property

  1. If the Legend box is not visible, right-click the graph, and then click Show Legend.

  2. In the Legend box, see if the node category or property appears in the list.

  3. If the list does not include the category or property, click Add, point to Node Category or Node Property, and then select the category or property.

    Note

    To create and assign a category to a node, see Assign Categories to Nodes and Links. To create and assign a property to a node, see Assign Properties to Nodes and Links.

  4. In the Legend box, click the drop-down list next to the category or property.

  5. Use the following table to select the style that you want to change:

    To change the

    Select

    Background color

    Background

    Outline color

    Stroke

    Text color

    Foreground

    Icon

    Icons

  6. In the picker dialog box, choose one of the following:

    To apply a

    Follow these steps

    Set of colors (or icons)

    Click the Select color (icon) set drop-down list, and then click a set of colors (or icons).

    To revert to the default color (or icon), in the Select color (icon) set drop-down list, click None.

    Specific color (or icon)

    Click the category or property value drop-down list, and then select a color (or icon).

  7. When you are finished, click OK.

    Note

    You can rearrange, delete, or temporarily inactivate styles in the Legend box. For more information, see Modify the Legend Box.

  1. If the Legend box is not visible, right-click the graph, and then click Show Legend.

  2. In the Legend box, see if the category or property appears in the list.

  3. If the list does not include the category or property, click Add, point to Link Category or Link Property, and then select the category or property.

    Note

    To create and assign a category to a link, see Assign Categories to Nodes and Links. To create and assign a property to a link, see Assign Properties to Nodes and Links.

  4. In the Legend box, click the drop-down list next to the category or property.

  5. Use the following table to select the style that you want to change:

    To change the

    Select

    Arrowhead color

    Background

    Outline color

    Stroke

  6. In the Color Set Picker box, choose one of the following:

    To apply a

    Follow these steps

    Set of colors

    Click the Select color set drop-down list, and then click a set of colors.

    To revert to the default color, in the Select color set drop-down list, click None.

    Specific color

    Click the type or property value drop-down list to select a color.

  7. When you are finished, click OK.

    Note

    You can rearrange, delete, or temporarily inactivate styles in the Legend box. For more information, see Modify the Legend Box.

You can apply custom styles to the following items:

  • Single nodes and links

  • Groups of nodes and links

  • Groups of nodes and links based on certain conditions

To apply a custom style to a single node

  1. Right-click the node whose style you want to customize, and then click View DGML.

    Visual Studio opens the graph's .dgml file and highlights the <Node/> element for that node.

  2. In the <Node/> element, add any of the following attributes to customize its style:

    To change the

    Add the following attribute

    Background color

    		 
    Background="ColorNameOrHexadecimalValue"

    Outline

    		 
    Stroke="ColorNameOrHexadecimalValue"

    Outline thickness

    		 
    StrokeThickness="StrokeValue"

    Text color

    		 
    Foreground="ColorNameOrHexadecimalValue"

    Icon

    		 
    Icon="IconFilePathLocation"

    Text size

    		 
    FontSize="FontSizeValue"

    Text type

    		 
    FontFamily="FontFamilyName"

    Text weight

    		 
    FontWeight="FontWeightValue"

    Text style

    		 
    FontStyle="FontStyleName"

    For example, you can specify Italic as the text style.

    Texture

    		 
    Style="Glass"

    - or -

    Style="Plain"

    Shape

    		 
    Shape

    For example:

    <Nodes>
   <Node Id="MyNode" Background="Green" Stroke="#FF000000"
   Foreground="White" Icon="...\Graph Icons\MyNodeIcon.jpg"/>
</Nodes>

  1. On the graph, move the mouse pointer over the link to show the tooltip and to identify the source node and the target node of the link.

  2. Right-click the graph, and then click View DGML.

    Visual Studio opens the graph's .dgml file.

  3. Find the <Link/> element that contains both the names of the source node and target node.

  4. In the <Link/> element, add any of the following attributes to customize its style:

    To change the

    Add the following attribute

    Arrowhead color

    		 
    Background="ColorNameOrHexadecimalValue"

    Outline color

    		 
    Stroke="ColorNameOrHexadecimalValue"

    Outline thickness

    		 
    StrokeThickness="StrokeValue"

    Outline style

    		 
    StrokeDashArray="StrokeArrayValues"

    For example:

    <Links>
   <Link Source="MyFirstNode" Target="MySecondNode" Background="Green" Stroke="#FF000000" />
</Links>

  1. Assign any categories or properties that you want to the nodes or links.

    For more information, see Assign Categories to Nodes and Links and Assign Properties to Nodes and Links.

  2. Right-click the graph surface, and then click View DGML.

    Visual Studio opens the graph's .dgml file.

  3. If a <Styles></Styles> element does not exist, add one under the <DirectedGraph></DirectedGraph> element after the <Links></Links> element.

  4. In the <Styles></Styles> element, under the <Style/> element and specify the following attributes:

    • TargetType="Node | Link | Graph"

    • GroupLabel="NameInLegendBox"

    • ValueLabel="NameInStylePickerBox"

    To apply a custom style to all target types, do not use a condition.

  1. In the <Style/> element, add a <Condition/> element that contains an Expression attribute to specify an expression that returns a Boolean value.

    For example:

    <Condition Expression="MyCategory"/>

    - or -

    <Condition Expression="MyCategory > 100"/>

    - or -

    <Condition Expression="HasCategory('MyCategory')"/>

    This expression uses the following Backus-Naur Form (BNF) syntax:

    <Expression> ::= <BinaryExpression> | <UnaryExpression> | "("<Expression>")" | <MemberBindings> | <Literal> | <Number>

    <BinaryExpression> ::= <Expression> <Operator> <Expression>

    <UnaryExpression> ::= "!" <Expression> | "+" <Expression> | "-" <Expression>

    <Operator> ::= "<" | "<=" | "=" | ">=" | ">" | "!=" | "or" | "and" | "+" | "*" | "/" | "-"

    <MemberBindings> ::= <MemberBindings> | <MemberBinding> "." <MemberBinding>

    <MemberBinding> ::= <MethodCall> | <PropertyGet>

    <MethodCall> ::= <Identifier> "(" <MethodArgs> ")"

    <PropertyGet> ::= Identifier

    <MethodArgs> ::= <Expression> | <Expression> "," <MethodArgs> | <empty>

    <Identifier> ::= [^. ]*

    <Literal> ::= single or double-quoted string literal

    <Number> ::= string of digits with optional decimal point

    You can specify multiple <Condition/> elements, which must all be true to apply the style.

  2. On the next line after the <Condition/> element, add one or multiple <Setter/> elements to specify a Property attribute and a fixed Value attribute or a computed Expression attribute to apply to the graph, nodes, or links that meet the condition.

    For example:

    <Setter Property="BackGround" Value="Green"/>

As a simple complete example, the following condition specifies that a node appears green or red based on whether its Passed category is set to True or False:

<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph xmlns="https://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      <Node Id="MyFirstNode" Passed="True" />
      <Node Id="MySecondNode" Passed="False" />
   </Nodes>
   <Links>
   </Links>
   <Styles>
      <Style TargetType="Node" GroupLabel="Passed" ValueLabel="True">
         <Condition Expression="Passed='True'"/>
         <Setter Property="Background" Value="Green"/>
      </Style>
      <Style TargetType="Node" GroupLabel="Passed" ValueLabel="False">
         <Condition Expression="Passed='False'"/>
         <Setter Property="Background" Value="Red"/>
      </Style>
   </Styles>
</DirectedGraph>

The following table includes some example conditions that you can use:

To

Example DGML

Set the font size as a function of the number of lines of code, which also changes the size of the node. This example uses a single conditional expression to set multiple properties, FontSize and FontFamily.

 
<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph xmlns="https://schemas.microsoft.com/vs/2009/dgml">
<Nodes>
   <Node Id="Class1" LinesOfCode ="200" />
   <Node Id="Class2" LinesOfCode ="1000" />
   <Node Id="Class3" LinesOfCode ="20" />
</Nodes>
<Properties>
   <Property Id="LinesOfCode" Label="LinesOfCode" Description="LinesOfCode" DataType="System.Int32" />
</Properties>
<Styles>
   <Style TargetType="Node" GroupLabel="LinesOfCode" ValueLabel="Function">
      <Condition Expression="LinesOfCode &gt; 0" />
      <Setter Property="FontSize" Expression="Math.Max(9,Math.Sqrt(LinesOfCode))" />
      <Setter Property="FontFamily" Value="Papyrus" />
   </Style>
</Styles>
</DirectedGraph>

Set the background color of a node based on the Coverage property. The styles are evaluated in the order that they appear, similar to if-else statements.

In this example:

  1. If Coverage is > 80, then set the Background property to green.

  2. Else if Coverage is > 50, then set the Background property to a shade of orange based on the value of the Coverage property.

  3. Else set the Background property to a shade of red based on the value of the Coverage property.

 
<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph xmlns="https://schemas.microsoft.com/vs/2009/dgml">
<Nodes>
   <Node Id="Class1" Coverage="58" />
   <Node Id="Class2" Coverage="95" />
   <Node Id="Class3" Coverage="32" />
</Nodes>
<Properties>
   <Property Id="Coverage" Label="Coverage" Description="Code coverage as a percentage of blocks" DataType="Double" />
</Properties>
<Styles>
   <Style TargetType="Node" GroupLabel="Coverage" ValueLabel="Good">
      <Condition Expression="Coverage &gt; 80" />
      <Setter Property="Background" Value="Green" />
   </Style>
   <Style TargetType="Node" GroupLabel="Coverage" ValueLabel="OK">
      <Condition Expression="Coverage &gt; 50" />
      <Setter Property="Background" Expression="Color.FromRgb(180 * Math.Max(1, (80 - Coverage) / 30), 180, 0)" />
   </Style>
   <Style TargetType="Node" GroupLabel="Coverage" ValueLabel="Bad">
      <Setter Property="Background" Expression="Color.FromRgb(180, 180 * Coverage / 50, 0)" />
   </Style>
</Styles>
</DirectedGraph>

Set the Shape property to None so that the icon replaces the shape. Use the Icon property to specify the location of the icon.

 
<DirectedGraph xmlns="https://schemas.microsoft.com/vs/2009/dgml">
<Nodes>
   <Node Id="Automation" Category="Test" Label="Automation" />
   <Node Id="C# Provider" Category="Provider" Label="C# Provider" />
</Nodes>
<Categories>
   <Category Id="Provider" Icon="..\Icons\AddIn.png" Shape="None" />
   <Category Id="Test" Icon="..\Icons\Macro.png" Shape="None" />
</Categories>
<Properties>
   <Property Id="Icon" DataType="System.String" />
   <Property Id="Label" Label="Label" Description="Displayable label of an Annotatable object" DataType="System.String" />
   <Property Id="Shape" DataType="System.String" />
</Properties>
<Styles>
   <Style TargetType="Node" GroupLabel="Group" ValueLabel="Has category">
      <Condition Expression="HasCategory('Group')" />
      <Setter Property="Background" Value="#80008080" />
   </Style>
   <Style TargetType="Node">
      <Setter Property="HorizontalAlignment" Value="Center" />
   </Style>
</Styles>
</DirectedGraph>

Modify the Legend box

You can rearrange, delete, or temporarily inactivate styles in the Legend box:

  1. Right-click a style in the Legend box.

  2. Perform one of the following tasks:

    To

    Click

    Move the style up

    Move Up

    Move the item down

    Move Down

    Delete the item

    Delete

    Inactivate the item

    Disable

    Reactivate the item

    Enable

Copy Styles from One Graph to Another Graph

  • Right-click a blank area of the source graph, click Copy Legend, and then paste the style onto the target graph.

Organize Nodes into Groups

To

Perform these steps

Show nodes with containment relationships as groups or as links

To show links as groups, select the container nodes, right-click your selection, point to Group, and then click Show as Group.

To show groups as links, select the container nodes, right-click your selection, point to Group, and then click Show as Link.

To show all groups as links, right-click the graph, point to Group, and then click Show All As Links.

To show all links as groups, right-click the graph, point to Group, and then click Show All As Groups.

Add a new group around selected nodes

  1. Right-click your selection, point to Group, and then click Add Parent Group.

  2. Right-click the new group, and then click Properties.

  3. In the Label property, rename the group.

Add a new group around nodes that have specific categories or properties

  1. To display the Selection box, right-click the graph surface, and then click Show Advanced Selection

  2. In the Selection box, click the categories or properties that you want.

  3. Right-click the graph surface, point to Group, and then click Add Parent Group.

  4. Right-click the new group, and then click Properties.

  5. In the Label property, rename the group.

Group nodes according to their containers

  1. On the Architecture menu, point to Windows, and then click Architecture Explorer.

  2. Use Architecture Explorer to find and select all the nodes that you want to group.

    For more information, see How to: Find Code Using Architecture Explorer.

  3. On the right side of the current column, click the collapsed action column to expand it.

    NoteNote
    The action column appears highlighted when you move the pointer over it.

  4. In the action column, click Contained By.

  5. From next column, drag the container groups to the graph.

  6. Right-click the graph surface, point to Group, and then click Show All as Groups.

Group nodes according to their property values

  1. Save the graph as a .dgml file on disk.

  2. On the Architecture menu, point to Windows, and then click Architecture Explorer.

  3. In Architecture Explorer, under File System, click Select Files.

  4. In the next column, click your saved .dgml file

  5. Use Architecture Explorer to find and select all the nodes that you want to group.

    For more information, see How to: Find Code Using Architecture Explorer.

  6. On the right side of the current column, click the collapsed action column to expand it.

    NoteNote
    The action column appears highlighted when you move the pointer over it.

  7. In the action column, under Grouping, click Group by Properties.

  8. In the next column, select the properties that you want to use as groups.

    The next column appears and shows the available property values.

  9. From the next column, drag the property value groups to the graph.

  10. Right-click the graph surface, point to Group, and then click Show All as Groups.

Remove groups

Select the group or groups that you want to remove, right-click your selection, point to Group, and then click Remove Group.

Remove nodes from their parent group up to their grandparent, or outside a group, if they have no grandparent group

Select the nodes that you want to move, right-click your selection, point to Group, and then click Remove From Parent.

You can also organize nodes into groups by editing the graph's .dgml file.

To use an existing node as a group or add a new group

  1. To use an existing node as a group, right-click the node that you want to use as a group node, and then click View DGML.

    Visual Studio opens the graph's .dgml file and highlights the <Node/> element for that node.

    -or-

    1. To add a new group, right-click a blank area of the graph, and then click View DGML.

    2. In the <Nodes> section, add a new <Node/> element.

  2. In the <Node/> element, add a Group attribute to specify whether the group appears expanded or collapsed. For example:

    <Nodes>
   <Node Id="MyFirstGroup" Group="Expanded" />
   <Node Id="MySecondGroup" Group="Collapsed" />
</Nodes>

  3. In the <Links> section, make sure that a <Link/> element that has the following attributes exist for each relationship between a group node and its child nodes:

    • A Source attribute that specifies the group node

    • A Target attribute that specifies the child node

    • A Category attribute that specifies a Contains relationship between the group node and its child node

    For example:

    <Links>
   <Link Category="Contains" Source="MyFirstNewGroup" Target="FirstGroupChildOne" />
   <Link Category ="Contains" Source="MyFirstNewGroup" Target="FirstGroupChildTwo" />
   <Link Category ="Contains" Source="MySecondNewGroup" Target="SecondGroupChildOne" />
   <Link Category="Contains" Source="MySecondNewGroup" Target="SecondGroupChildTwo" />
</Links>

    For more information about the Category attribute, see Assign Categories to Nodes and Links.

You can organize nodes and links by assigning properties to them. For example, you can select nodes that have specific properties so that you can group them, change their style, or hide them.

To assign a property to a node

  1. Right-click the node, and then click View DGML.

    Visual Studio opens the graph's .dgml file and highlights the <Node/> element for that node.

  2. In the <Node/> element, specify the name of the property and its value. For example:

    <Nodes>
   <Node Id="MyNode" MyPropertyName="PropertyValue" />
</Nodes>

  3. Add a <Property/> element to the <Properties> section to specify attributes such as its visible name and data type:

    <Properties>
   <Property Id="MyPropertyName" Label="My Property" DataType="System.DataType"/>
</Properties>

  1. On the graph, move the mouse pointer over the link to show the tooltip and to identify the source node and the target node of the link.

  2. Right-click the graph, and then click View DGML.

    Visual Studio opens the graph's .dgml file.

  3. Find the <Link/> element that contains both the names of the source node and target node.

  4. In the <Node/> element, specify the name of the property and its value. For example:

    <Links>
   <Link Source="MyFirstNode" Target="MySecondNode" MyPropertyName="PropertyValue" />
</Links>

  5. Add a <Property/> element to the <Properties> section to specify attributes such as its visible name and data type:

    <Properties>
   <Property Id="MyPropertyName" Label="My Property Name" DataType="System.DataType"/>
</Properties>

You can organize nodes by assigning categories to them. For example, you can select nodes that are in certain categories so that you can group them, change their style, or hide them. You can highlight links that have certain categories. For more information, see the following sections:

  • Organize nodes into groups

  • Change the style of nodes and links

  • Hide or show nodes

To assign a category to a node

  • To assign a predefined category, such as Category 1, right-click the node, point to Categorize, and then click a predefined category.

- or -

  • To create and assign a custom category:

    • Click the node that you want to categorize, press F4 to open the Properties window, type the name of the category in the node's New Category property, and then press ENTER.

    - or -

    1. Right-click the node, and then click View DGML.

      Visual Studio opens the graph's .dgml file and highlights the <Node/> element for that node.

    2. In the <Node/> element, add a Category attribute to specify the name of the category. For example:

      <Nodes>
   <Node Id="MyNode" Category="MyCategory" />
</Nodes>

    3. Add a <Category/> element to the <Categories> section so that you can use the Label attribute to specify the display text for that category:

      <Categories>
   <Category Id="MyCategory" Label="My Category" />
</Categories>

  1. On the graph, move the mouse pointer over the link to show the tooltip and to identify the source node and the target node of the link.

  2. Right-click the graph, and then click View DGML.

    Visual Studio opens the graph's .dgml file.

  3. Find the <Link/> element that contains both the names of the source node and target node.

  4. In the <Link/> element, add a Category attribute to specify the name of the category. For example:

    <Links>
   <Link Source="MyFirstNode" Target="MySecondNode" Category="MyCategory"
</Links>

  5. Add a <Category/> element to the <Categories> section so that you can use the Label attribute to specify the display text for that category:

    <Categories>
   <Category Id="MyCategory" Label="My Category" />
</Categories>

You can create hierarchical categories to help you organize nodes and add attributes to child categories by using inheritance.

To create hierarchical categories

  • Add a <Category/> element for the parent category, and then add the BasedOn attribute to the child category's <Category/> element.

    For example:

    <Nodes>
   <Node Id="MyFirstNode" Label="My First Node" Category= "MyCategory" />
   <Node Id="MySecondNode" Label="My Second Node" />
</Nodes>
<Links>
   <Link Source="MyFirstNode" Target="MySecondNode" />
</Links>
<Categories>
   <Category Id="MyCategory" Label="My Category" BasedOn="MyParentCategory"/>
   <Category Id="MyParentCategory" Label="My Parent Category" Background="Green"/>
</Categories>

    In this example, the background of MyFirstNode is green because its Category attribute inherits the Background attribute of MyParentCategory.

You can link items, such as documents or URLs, to a node by editing the graph's .dgml file and adding a Reference attribute to the <Node/> element of that node. The Reference attribute specifies the path of that content. This can be a path relative to the location of the .dgml file or an absolute path. You can then open and view that content from the node on the graph.

Note

The referenced item or items must exist for you to view them

For example, you might want to link the following items:

  • To describe the changes to a class, you might link the URL of a work item, document, or another .dgml file to the node for a class.

  • You might link a layer diagram to a group node that represents a layer in the software's logical architecture.

  • To show more information about a component that exposes an interface, you might link a component diagram to the node for that interface.

  • Link a node to a Team Foundation Server work item or bug, or some other information that is related to the node.

  1. On the graph, right-click the node, and then click View DGML.

    Visual Studio opens the graph's .dgml file and highlights the <Node/> element for that node.

  2. Perform one of the tasks in the following table:

    To link

    Follow these steps

    A single item

    • In the <Node/> element, add a Reference attribute to specify the location of the item.

      NoteNote
      You can have only one Reference attribute per <Node/> element.

    For example:

    <Nodes>
   <Node Id="MyNode" Reference="MyDocument.txt" />
</Nodes>
<Properties>
   <Property Id="Reference" Label="My Document" DataType="System.String" IsReference="True" />
</Properties>

    Multiple items

    1. In the <Node/> element, add a new attribute to specify the location of each reference.

    2. In the <Properties> section:

      1. Add a <Property/> element for each new type of reference.

      2. Set the Id attribute to the name of the new reference attribute.

      3. Add the IsReference attribute and set it to True to make the reference appear on the node's Goto shortcut menu.

      4. Use the Label attribute to specify the display text on the node's Goto shortcut menu.

    For example:

    <Nodes>
   <Node Id="MyNode" SequenceDiagram="MySequenceDiagram.sequencediagram" ActiveBugs="MyActiveBugs.wiq"/>
</Nodes>
<Properties>
   <Property Id="SequenceDiagram" Label="My Sequence Diagram" DataType="System.String" IsReference="True" />
   <Property Id="ActiveBugs" Label="Active Bugs" DataType="System.String" IsReference="True" />
</Properties>

    On the graph, the name of the node appears underlined.

  3. Use the ReferenceTemplate attribute to specify a common string, such as a URL, that is used by multiple references instead of repeating that string in the reference.

    The ReferenceTemplate attribute specifies a placeholder for the value of the reference. In the following example, the {0} placeholder in the ReferenceTemplate attribute will be replaced by the values of the MyFirstReference and MySecondReference attributes in the <Node/> element to produce a full path:

    <Nodes>
   <Node Id="MyNode" MyFirstReference="MyFirstDocument" MySecondReference="MySecondDocument"/>
   <Node Id="MySecondNode" MyFirstReference="AnotherFirstDocument" MySecondReference="AnotherSecondDocument"/>
</Nodes>
<Properties>
   <Property Id="MyFirstReference" Label="My First Document" DataType="System.String" IsReference="True" ReferenceTemplate="http://www.Fabrikam.com/FirstDocuments/{0}.asp"/>
   <Property Id="MySecondReference" Label="My Second Document" DataType="System.String" IsReference="True" ReferenceTemplate=" http://www.Fabrikam.com/SecondDocuments/{0}.asp"/>
</Properties>

  4. Perform one of the following tasks to view the referenced item:

    To view

    Perform the following step

    A single item

    Double-click the node.

    - or -

    Right-click the node, point to Goto, and then click the item.

    Multiple items

    Right-click the node, point to Goto, and then click an item.

Create Aliases for Commonly-Used Paths

Replacing commonly-used paths with aliases helps reduce the size of the .dgml file and the time required to load or save the file. To create an alias, add a <Paths></Paths> section at the end of the .dgml file. In this section, add a <Path/> element to define an alias for the path:

<Paths>
   <Path Id="MyPathAlias" Value="C:\...\..." />
</Paths>

To reference the alias from an element in the .dgml file, enclose the Id value of the <Path/> element with a dollar sign ($) and parentheses (()):

<Nodes>
   <Node Id="MyNode" Reference="$(MyPathAlias)MyDocument.txt" />
</Nodes>
<Properties>
   <Property Id="Reference" Label="My Document" DataType="System.String" IsReference="True" />
</Properties>

Understanding Directed Graph Markup Language (DGML)

DGML uses simple XML to describe cyclical and acyclic directed graphs. A directed graph is a set of nodes that are connected by links, or edges. Nodes and links can be used represent network structures, such as elements in a software project. Use DGML to visualize information, perform complexity analysis, or just browse and edit directed graphs.

Nodes and links are called graph elements, or just elements. The following table describes the kinds of elements that are used in DGML:

Note

When you edit a .dgml file, IntelliSense helps you identify attributes that are available for each element and their values. To specify color in an attribute, use names for common colors, such as "Blue", or ARGB hexadecimal values, such as "#ffa0b1c3". DGML uses a small subset of Windows Presentation Foundation (WPF) color definition formats. For more information, see Colors Class.

Element

Example Format

<DirectedGraph></DirectedGraph>

This element is the root element of directed graph (.dgml) document. All other DGML elements appear within the scope of this element.

The following list describes optional attributes that you can include:

  • Background - The color of the graph background

  • BackgroundImage - The location of an image file to use as the graph background.

  • ButterflyMode - If True, show only those linked nodes that are on the same path as the selected nodes. If no nodes are selected, then the graph selects the primary hub.

    NoteNote
    Circular links do not appear in this mode. Instead, nodes that participate in circular relationships are copied so that they appear on both sides of the selected nodes. Dependencies that are more than one level away from the selected node will not necessarily appear in order because the graph layout is based on the shortest path from the selected node.

    For more information, see How to: Browse and Navigate Graph Documents.

  • GraphDirection - When the graph is set to tree layout (Sugiyama), arrange the nodes so that most of the links flow in the specified direction: TopToBottom, BottomToTop, LeftToRight, or RightToLeft. For more information, see How to: Browse and Navigate Graph Documents.

  • Layout - Set the graph to the following layouts: None, Sugiyama (tree layout), ForceDirected (quick clusters), or DependencyMatrix. For more information, see How to: Browse and Navigate Graph Documents.

  • NeighborhoodDistance - When the graph is set to tree layout or quick clusters layout, show only those nodes that are a specified number (1-7) of links away from selected nodes. For more information, see How to: Browse and Navigate Graph Documents.

  • Title - The name of the graph

  • ZoomLevel - The zoom level used to display the graph initially. Specify a floating point value where 1 is 100%, or Fit to fit the graph to the window size.

 
<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" Background="Blue" xmlns="https://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      ...
   </Nodes>
   <Links>
      ...
   </Links>
   <Categories>
      ...
   </Categories>
   <Properties>
      ...
   </Properties>
</DirectedGraph>

<Nodes></Nodes>

This optional element contains a list of <Node/> elements, which define nodes on the graph. For more information, see the <Node/> element.

NoteNote
When you reference an undefined node in a <Link/> element, the graph creates a <Node/> element automatically. 
<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="https://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      <Node ... />
   </Nodes>
   <Links>
      <Link ... />
   </Links>
</DirectedGraph>

<Node/>

This element defines a single node. It appears within the <Nodes><Nodes/> element list.

This element must include the following attributes:

  • Id - The unique name of the node and the default value of the Label attribute, if no separate Label attribute is specified. This name must match the Source or Target attribute of the link that references it.

The following list describes some of the optional attributes that you can include:

  • Label - The display name of the node

  • Style attributes. For more information, see Apply Custom Styles to Nodes and Links.

  • Category - The name of a category that identifies elements that share this attribute. For more information, see the <Category/> element.

  • Property - The name of a property that identifies elements that have the same property value. For more information, see the <Property/> element.

  • Group - If the node contains other nodes, set this attribute to Expanded or Collapsed to show or hide its contents. There must be a <Link/> element that includes the Category="Contains" attribute and specifies the parent node as the source node and the child node as the target node. For more information, see Organize Nodes into Groups.

  • Visibility - Set this attribute to Visible, Hidden, or Collapsed. Uses System.Windows.Visibility. For more information, see Hide or Show Nodes.

  • Reference - Set this attribute to link to a document or URL. For more information, see Link Items to Nodes.

 
<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="https://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      <Node Id="Driver" Label="Student" Category="Person" />
      <Node Id="Passenger" Label="Instructor" Category="Person" />
      <Node Id="Car" Label="Car" Category="Automobile" />
      <Node Id="Truck" Label="Truck" ategory="Automobile" />
   </Nodes>
   <Links>
      <Link ... />
   </Links>
   <Categories>
      <Category Id="Person" Background="Orange" />
      <Category Id="Automobile" Background="Yellow"/>
   </Categories>
</DirectedGraph>

<Links></Links>

This element contains the list of <Link> elements, which define links between nodes. For more information, see the <Link/> element.

 
<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="https://schemas.microsoft.com/vs/2009/dgml">
   <Links>
      <Link ... />
   </Links>
</DirectedGraph>

<Link/>

This element defines a single link that connects a source node to a target node. It appears within the <Links></Links> element list.

NoteNote
If this element references an undefined node, the graph document automatically creates a node that has the specified attributes, if any.

This element must include the following attributes:

  • Source - The source node of the link

  • Target - The target node of the link

The following list describes some of the optional attributes that you can include:

  • Label - The display name of the link

  • Style attributes. For more information, see Apply Custom Styles to Nodes and Links.

  • Category - The name of a category that identifies elements that share this attribute. For more information, see the <Category/> element.

  • Property - The name of a property that identifies elements that have the same property value. For more information, see the <Property/> element.

 
<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="https://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      <Node Id="Driver" Label="Student" Category="Person" />
      <Node Id="Passenger" Label="Instructor" Category="Person" />
      <Node Id="Car" Label="Car" Category="Automobile" />
      <Node Id="Truck" Label="Truck" Category="Automobile" />
   </Nodes>
   <Links>
      <Category Id="Person" Background="Orange" />
      <Category Id="Automobile" Background="Yellow"/>
      <Link Source="Driver" Target="Car" Label="Passed" Stroke="Black" Background="Green" Category="PassedTest" />
      <Link Source="Driver" Target="Truck" Label="Failed" Stroke="Black" Background="Red" Category="PassedTest" />
   </Links>
</DirectedGraph>

<Categories></Categories>

This element contains the list of <Category/> elements. For more information, see the <Category/> element.

 
<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="https://schemas.microsoft.com/vs/2009/dgml">
   <Categories>
       <Category ... />
   </Categories>
</DirectedGraph>

<Category/>

This element defines a Category attribute, which is used to identify elements that share this attribute. A Category attribute can be used to organize graph elements, provide for shared attributes through inheritance, or define additional metadata.

This element must include the following attributes:

  • Id - The unique name of the category and the default value of the Label attribute, if no separate Label attribute is specified.

The following list describes some of the optional attributes that you can include:

  • Label - A reader-friendly name for the category.

  • BasedOn - The parent category from which the <Category/> of the current element inherits.

    In the example for this element, the FailedTest category inherits its Stroke attribute from the PassedTest category. For more information, see "To create hierarchical categories" in Assign Categories to Nodes and Links.

Categories also provide some basic template behavior that controls the appearance of nodes and links when they are displayed on a graph. For more information, see Apply Custom Styles to Nodes and Links.

 
<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="https://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      <Node Id="Driver" Label="Driver" Category="Person" />
      <Node Id="Car" Label="Car" Category="Automobile" />
      <Node Id="Truck" Label="Truck" Category="Automobile" />
      <Node Id="Passenger" Category="Person" />
   </Nodes>
   <Links>
      <Link Source="Driver" Target="Car" Label="Passed" Category="PassedTest" />
      <Link Source="Driver" Target="Truck" Label="Failed" Category="FailedTest" />
   </Links>
   <Categories>
      <Category Id="Person" Background="Orange" />
      <Category Id="Automobile" Background="Yellow"/>
      <Category Id="PassedTest" Label="Passed" Stroke="Black" Background="Green" />
      <Category Id="FailedTest" Label="Failed" BasedOn="PassedTest" Background="Red" />
   </Categories>
</DirectedGraph>

<Properties></Properties>

This element contains the list of <Property/> elements. For more information, see the <Property/> element.

 
<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="https://schemas.microsoft.com/vs/2009/dgml">
   <Properties>
       <Property ... />
   </Properties>
</DirectedGraph>

<Property/>

This element defines a Property attribute that you can use to assign a value to any DGML element or attribute, including categories and other properties.

This element must include the following attributes:

  • Id - The unique name of the property and the default value of the Label attribute, if no separate Label attribute is specified.

  • DataType - The type of data stored by the property

If you want the property to appear in the Properties window, use the Label property to specify the property's display name.

For more information, see Assign Properties to Nodes and Links.

 
<?xml version="1.0" encoding="utf-8"?>
<DirectedGraph Title="DrivingTest" xmlns="https://schemas.microsoft.com/vs/2009/dgml">
   <Nodes>
      <Node Id="Driver" Label="Driver" Category="Person" DrivingAge="18"/>
      <Node Id="Car" Label="Car" Category="Automobile" />
      <Node Id="Truck" Label="Truck" Category="Automobile" />
      <Node Id="Passenger" Category="Person" />
   </Nodes>
   <Links>
      <Link Source="Driver" Target="Car" Label="Passed" Category="PassedTest" />
      <Link Source="Driver" Target="Truck" Label="Failed" Category="FailedTest" />
   </Links>
   <Categories>
      <Category Id="Person" Background="Orange" />
      <Category Id="Automobile" Background="Yellow"/>
      <Category Id="PassedTest" Label="Passed" Stroke="Black" Background="Green" />
      <Category Id="FailedTest" Label="Failed" BasedOn="PassedTest" Background="Red" />
   </Categories>
   <Properties>
       <Property Id="DrivingAge" Label="Driving Age" DataType="System.Int32" />
   </Properties>
</DirectedGraph>

See Also

Concepts

How to: Generate Dependency Graphs for .NET Code

How to: Browse and Navigate Graph Documents

How to: Explore Code with Dependency Graphs