Edit and Customize Dependency Graphs

  • Article

You can edit dependency graphs without affecting the underlying code. This is useful when you want to focus on key items or communicate ideas about the code. For example, to highlight interesting areas, you can select nodes and filter them, change the style of nodes and links, hide or delete nodes, and organize nodes using properties, categories, or groups.

You can customize a graph even further by editing the graph's Directed Graph Markup Language (.dgml) file. For example, you can edit elements to specify custom styles, assign properties and categories to nodes and links, or link nodes to items, such as documents, URLs, or other graphs.

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. For more information about DGML elements, see Understanding Directed Graph Markup Language (DGML).

Requirements

In this topic

  • Select nodes or links

  • Rename nodes or links

  • Hide or show nodes and links

  • Add nodes and links

  • Add comments to the graph

  • Delete nodes

  • Group nodes

  • Merge graphs

  • Change the style of the graph

  • Change the node or link style

  • Copy styles from one graph to another graph

  • Assign properties to nodes and links

  • Assign categories to nodes and links

  • Link items to nodes or links

  • Create aliases for commonly-used paths

To

Perform these steps

Select all unselected nodes

Open the shortcut menu for the selected nodes. Choose Select, Invert Selection.

Select additional nodes that link to the selected ones

Open the shortcut menu for the selected nodes. Choose Select and one of the following:

  • To select additional nodes that link directly to the selected node, choose Incoming Dependencies.

  • To select additional nodes that link directly from the selected node, choose Outgoing Dependencies.

  • To select additional nodes that link directly to and from the selected node, choose Both.

  • To select additionally all nodes that link to and from the selected node, choose Connected Subgraph.

  • To select additionally all children of the selected node, choose Children.

  • Select the node or the link. Press F2. When the edit box appears, rename the node or the link.

    If the label is visible, select the label.

Hiding nodes keeps them from participating in layout algorithms. By default, cross-group links are hidden. Cross-group links are individual links that connect nodes across groups. When groups are collapsed, the graph aggregates all cross-group links into single links between groups. When you expand a group and select nodes inside the group, cross-group links appear and show the dependencies in that group.

Warning

Before you share a graph that was created in Visual Studio Ultimate with those who use Visual Studio Premium or Visual Studio Professional, make sure to unhide any nodes or cross-group links that you want others to see. Otherwise, those users won't be able to unhide those items.

To hide or show nodes

To

Perform these steps

Hide selected nodes

  1. Select nodes you want to hide.

  2. Open the shortcut menu for the selected nodes or for the graph. Choose Select, Hide Selected.

Hide unselected nodes

  1. Select nodes you want to stay visible.

  2. Open the shortcut menu for the selected nodes or for the graph. Choose Select, Hide Unselected.

Show hidden nodes

  • To show all hidden nodes inside a group, make sure the group is expanded first. Choose Unhide ChildrenUnhide Children Icon in the upper left corner of the group.

  • To show all hidden nodes, open the shortcut menu for the graph. Choose Selection, Unhide All.

Hide nodes by editing the .dgml file

  1. Open the shortcut menu for the graph. Choose Goto, 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>

To show or hide links

To

On the graph toolbar, open the Change how links are rendered on the graph list or open the graph shortcut menu. Choose:

Show cross-group links at all times

Show All Cross-Group Links

This hides aggregated links between groups.

Show only cross-group links for selected nodes

Show Cross-Group Links On Selected Nodes

Hide cross-group links at all times

Hide Cross-Group Links

Hide all links (or show all links)

Hide All Links

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

To add a new undefined node

Perform these steps

At the current pointer location

Select a place on the graph where to put the new node. Press Insert.

That links to the selected node

  1. Select the source node.

    A toolbar starts to appear above the node.

    Dependency graph toolbar

  2. On the toolbar, choose Create a node with the same category as this node and add a new link to itGraph toolbar - Create node with link.

  3. Choose a place on the graph to put the new node.

    (Keyboard: Press Tab until the node from which you want to link has focus, and then press Alt+Insert.)

That links to an existing node with current focus

Press Tab until the node to which you want to link has focus. Press Alt+Shift+Insert.

To add nodes for

Perform these steps

Items in the solution

  1. Find the item in Solution Explorer. Use the Solution Explorer search box or browse the solution. To browse your code in Solution Explorer, see Viewing the Structure of Code.

    Tip

    To find items that have dependencies on a type or a member, open the shortcut menu for the type or the member in Solution Explorer. Choose the relationship that interests you.

    Solution Explorer shows only those items with the specified dependencies.

  2. Drag the items that interest you to the graph surface.

    To include the parent container hierarchy for the selected items when using Visual Studio Ultimate, press and hold the CTRL key while you drag items to the graph.

    - or -

    On the Solution Explorer, open the Create a new graph document… list. Choose Add to Active Dependency Graph. To add the parent container hierarchy, choose Add to Active Dependency Graph with Containment Hierarchy instead.

    Visual Studio adds nodes for the top-level code items in your selection. To see if a node contains items, move the mouse pointer on top of the node so that the chevron (^) appears. Choose the chevron (^) to expand the node. To expand all nodes, open the shortcut menu for the graph. Choose Group, Expand All.

    Note

    This command is not available when expanding all groups produces an unusable graph or memory issues.

Items related to nodes on the graph

Open the shortcut menu for the node. Choose Show and the kind of relationship that interests you.

For an assembly, choose:

  • Referenced Assemblies: Add assemblies that this assembly references. External assemblies appear in the Externals group.

  • Referencing Assemblies: Add assemblies in the solution that reference this assembly.

For a class, choose:

  • Base Types: For a class, add the base class and the implemented interfaces.

    For an interface, add the base interfaces.

  • Derived Types: For a class, add the derived classes.

    For an interface, add the derived interfaces and the implementing classes or structs.

  • All Base Types: Add the base class or interface hierarchy recursively.

  • All Derived Types: For a class, add all the derived classes recursively.

    For an interface, add all the derived interfaces and implementing classes or structs recursively.

  • Containment Hierarchy: Add the parent container hierarchy.

  • Used Types: Add all classes and their members that this class uses.

  • Used-By Types: Add all classes and their members that use this class.

For a method, choose:

  • Containment Hierarchy: Add the parent container hierarchy.

  • Called Methods: Add methods that this method calls.

  • Called-By Methods: Add methods that call this method.

  • Overridden Methods in Base Types: For a method that overrides other methods or implements an interface's method, add all the abstract or virtual methods in base classes that are overridden and, if any, the interface's method that is implemented.

  • Referenced Fields: Add fields that this method references.

For a field, choose:

  • Containment Hierarchy: Add the parent container hierarchy.

  • Referencing Methods: Add methods that reference this field.

Compiled .NET assemblies (.dll or .exe) or binaries

Use Architecture Explorer to find and drag items and relationships to the graph.

  1. Select the source node.

    A toolbar starts to appear above the node.

    Dependency graph toolbar

  2. On the toolbar, choose Create new link from this node to which ever node that you click on nextGraph toolbar - Create link. Select the target node.

    A link appears between the two nodes.

Add comments to the graph

  1. Select the node where you want to add a linked comment.

    A toolbar starts to appear above the node.

    Dependency graph toolbar

  2. On the toolbar, choose Create a new comment node with a new link to the selected nodeGraph toolbar - Create comment with link.

  3. Type your comments. To type on a new line, press SHIFT+Enter.

Delete nodes

You can delete nodes from a graph without affecting the underlying code. To delete a node, select the node, and then press the Delete key. When you delete nodes, their definitions are removed from the DGML (.dgml) file.

When you delete nodes from a group, the Refetch Children button Refetch Children Icon appears inside the group. To retrieve missing nodes, choose Refetch ChildrenRefetch Children Icon. Graphs that are created by editing the DGML, adding undefined nodes, or by using earlier versions of Visual Studio Ultimate, do not support this capability.

Warning

Before you share a graph that was created using Visual Studio Ultimate with those who use Visual Studio Premium or Visual Studio Professional, make sure any nodes you want others to see are visible on the graph. Otherwise, those users won't be able to retrieve deleted nodes.

Group nodes

To

Perform these steps

Show container nodes as group nodes or leaf nodes

To show container nodes as leaf nodes, select the nodes. Open the shortcut menu for your selection. Choose Group, Convert To Leaf.

To show container nodes as group nodes, select the nodes. Open the shortcut menu for your selection. Choose Group, Convert To Group.

To show all leaf nodes as group nodes, open the shortcut menu for the graph. Choose Group, Turn On Grouping.

To show all group nodes as leaf nodes, open the shortcut menu for the graph. Choose Group, Turn Off Grouping.

Add a node to a group

Drag the node onto the group.

You can also drag nodes out of a group.

Add a node to a non-group node

You can convert any node into a group. Drag the node onto the target node.

Group selected nodes

  1. Select the nodes that you want to group.

    A toolbar starts to appear above the nodes.

    Dependency graph toolbar

  2. On the toolbar, choose Group the selected nodesGraph toolbar - Group selected.

    - or -

    Open the shortcut menu for your selection. Choose Group, Add Parent Group.

  3. Open the shortcut menu for the new group. Choose Properties. In the Label property, rename the group.

Group nodes that have specific categories or properties

  1. On the Architecture menu, choose Windows, Architecture Explorer.

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

    See Find Code with Architecture Explorer.

  3. On the right side of the current column, choose the collapsed action column to expand it. (Keyboard: Press Tab to move focus until the collapsed action column expands.)

    Note

    The action column appears highlighted when you move the pointer, or focus, on top of it.

  4. In the action column, click Contained By. (Keyboard: Press Tab to move focus and then use the arrow keys until the Contained By relationship is selected.)

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

  6. Open the shortcut menu for the graph. Choose Group, Turn On Grouping.

Group nodes according to their property values

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

  2. On the Architecture menu. Choose Windows, Architecture Explorer.

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

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

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

    See Find Code with Architecture Explorer.

  6. On the right side of the current column, choose the collapsed action column to expand it. (Keyboard: Press Tab to move focus until the collapsed action column expands.)

    Note

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

  7. In the action column, under Grouping, choose Group by Properties. (Keyboard: Press Tab to move focus and then use the arrow keys until the Group by Properties command is selected.)

  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. Open the shortcut menu for the graph surface. Choose Group, Turn On Grouping.

Remove groups

Select the group or groups that you want to remove. Open the shortcut menu for your selection. Choose Group, 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. Open the shortcut menu for your selection. Choose Group, Remove From Parent.

To group nodes by editing the graph's .dgml file

  1. To convert a node to a group, open the shortcut menu for the node. Choose Goto, DGML.

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

    -or-

    To add a new group:

    1. Open the shortcut menu for a blank area of the graph. Choose Goto, 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.

Merge graphs

You can merge graphs by copying and pasting nodes between graphs. If the node identifiers match, then pasting nodes functions like a merge operation. To make this task easier, put all the assemblies or binaries that you want to visualize in the same folder so that the full path of each assembly or binary is the same for each graph that you want to merge.

Alternatively, you can create a single graph for the assemblies or binaries that you want to visualize by following one of these steps:

  • Drag the assemblies or binaries to the same graph.

    -or-

  • Open Architecture Explorer. Under File System, choose Select Files to browse, select, and open the assemblies or binaries. To refine the graph, select specific items that you want to visualize. When you are finished, choose Create a new graph document from all the selected nodes on the Architecture Explorer toolbar.

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.

  1. Open the shortcut menu from the graph surface. Choose Goto, 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. 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, open the shortcut menu for the graph. Choose 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, choose + in the Legend box, Node Category or Node Property, and the category or property.

    The category or property now appears in the Legend box.

    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, open 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

    Choose

    Background color

    Background

    Outline color

    Stroke

    Text color

    Foreground

    Icon

    Icons

    The Color Set Picker box appears for you to select a color (or icon).

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

    To apply a

    Perform these steps

    Set of colors (or icons

    Open the Select color (or icon) set list. Select a set of colors (or icons).

    To revert to the default color (or icon), in the Select color (icon) set list, choose None.

    Specific color (or icon)

    Open the category or property value list. Select a color (or icon).

    Note

    You can rearrange, delete, or temporarily inactivate styles in the Legend box. See Modify the Legend Box.

  1. If the Legend box is not visible, open the shortcut menu for the graph. Choose 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, choose + in the Legend box, Link Category or Link Property, and the category or property.

    The category or property now appears in the Legend box.

    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, open the list next to the category or property.

  5. Select Stroke to change the link's outline and arrowhead color.

    The Color Set Picker box appears for you to select a color.

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

    To apply a

    Perform these steps

    Set of colors

    Open the Select colorset list. Select a set of colors.

    To revert to the default color, in the Select color set list, choose None.

    Specific color

    Open the type or property value list to select a color.

    Note

    You can rearrange, delete, or temporarily inactivate styles in the Legend box. 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. Open the shortcut menu for the node whose style you want to customize. Choose Goto, 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

    To replace the shape with an icon, set the Shape property to None and set the Icon property to the path with the icon file.

    		 
    Shape="ShapeFilePathLocation"

    For example:

    <Nodes>
   <Node Id="MyNode" Background="#FF008000" Stroke="#FF000000"
   Foreground="#FFFFFFFF" Icon="...\Icons\Globe.png"/>
</Nodes>

  1. On the graph, move the mouse pointer on top of the link. A tooltip appears and identifies the source node and the target node of the link. (Keyboard: Press Tab until focus is on the link.)

  2. Open the shortcut menu for the graph. Choose Goto, 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

    Outline and arrowhead color

    		 
    Stroke="ColorNameOrHexadecimalValue"

    Outline thickness

    		 
    StrokeThickness="StrokeValue"

    Outline style

    		 
    StrokeDashArray="StrokeArrayValues"

    For example:

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

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

    Tip

    If you have repeating styles across many nodes or links, you might consider applying a category to those nodes or links, and then applying a style to that category. For more information, see Assign Categories to Nodes and Links and Assign Properties to Nodes and Links.

  2. Open the shortcut menu for the graph surface. Choose Goto, 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\Module.png" Shape="None" />
   <Category Id="Test" Icon="...\Icons\Page.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. Open the shortcut menu for a style in the Legend box.

  2. Perform one of the following tasks:

    To

    Choose

    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

  1. Make sure the Legend box appears on the source graph. If it is not visible, open the shortcut menu for a blank area of the source graph. Choose Show Legend.

  2. Open the shortcut menu for the Legend box. Choose Copy Legend.

  3. Paste the legend onto the target graph.

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. Open the shortcut menu for the node. Choose Goto, 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 on top of the link. A tooltip appears and identifies the source node and the target node of the link. (Keyboard: Press Tab until focus is on the link.)

  2. Open the shortcut menu for the graph. Choose Goto, 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:

  • Group nodes

  • 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, open the shortcut menu for the node. Choose Categorize and a predefined category.

- or -

  • To create and assign a custom category:

    • Choose the node that you want to categorize. Press F4 to open the Properties window. Type the category name in the node's New Category property. Press ENTER.

    - or -

    1. Open the shortcut menu for the node. Choose Goto, 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. (Keyboard: Press Tab until focus is on the link.)

  2. Open the shortcut menu for the graph. Choose Goto, 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 or to a link by editing the graph's .dgml file and adding a Reference attribute to the <Node/> element for a node or the <Link/> element for a link. You can then open and view that content from the node or link. 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.

Warning

If you use relative paths, and the .dgml file is moved to a different location, then those paths will no longer resolve. When you try to open and view the linked content, an error stating that the content cannot be viewed will occur.

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, open the shortcut menu for the node. Choose Goto, 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

    Perform these steps

    A single item

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

      Note

      You can have only one Reference attribute per 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/> or <Link/> 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 item's Goto shortcut menu.

      4. Use the Label attribute to specify the display text on the item'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. When you open the shortcut menu for the node or the link, you will see a Goto shortcut menu that contains the linked items for you to choose.

  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. To view the referenced item or items from the graph, open the shortcut menu for the node or the link. Choose Goto and then the 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.

  • 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. See Browse and Rearrange Dependency Graphs.

  • Layout - Set the graph to the following layouts: None, Sugiyama (tree layout), ForceDirected (quick clusters), or DependencyMatrix. See Browse and Rearrange Dependency Graphs.

  • 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. See Browse and Rearrange Dependency Graphs.

 
<?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.

Note

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. 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. See Organize Nodes into Groups.

  • Visibility - Set this attribute to Visible, Hidden, or Collapsed. Uses System.Windows.Visibility. See Hide or Show Nodes.

  • Reference - Set this attribute to link to a document or URL. 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" Category="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.

Note

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. 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. 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. 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.

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

Visualize Code Dependencies on Dependency Graphs

Browse and Rearrange Dependency Graphs