In this article

Customize code maps by editing the DGML files

11/15/2016

13 minutes to read

Contributors

In this article

Note

This article applies to Visual Studio 2015. If you're looking for Visual Studio 2017 documentation, use the version selector at the top left. We recommend upgrading to Visual Studio 2017. Download it here.

To customize a code map, you can edit a map's Directed Graph Markup Language (.dgml) file. For example, you can edit elements to specify custom styles, assign properties and categories to code elements and links, or link documents or URLs to code elements or to links. For more information about DGML elements, see Directed Graph Markup Language (DGML) reference.

Edit the code map's .dgml file in a text or XML editor. If the map is part of your Visual Studio solution, select it in Solution Explorer, open the shortcut menu, and choose Open With, XML (Text) Editor.

Note

To create code maps, you must have Visual Studio Enterprise. When you edit a code map in Visual Studio, it cleans up any unused DGML elements and attributes by deleting them when you save the .dgml file. It also creates code 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.

Group code elements

You can add new groups or convert existing nodes into a group.

Open the .dgml file in a text or XML editor.

To convert a code element to a group, find the <Node/> element for that code element.

- or -

To add a new group, find the <Nodes> section. Add a new <Node/> element.

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

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

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 map, code elements, or links that meet the condition.

For example:

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

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

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

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

Assign properties to code elements and links

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

To assign a property to a code element

Open the .dgml file in a text or XML editor.

Find the <Node/> element for that code element. Specify the name of the property and its value. For example:

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

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

Assign categories to code elements and links

The following sections demonstrate how you can organize code elements by assigning categories to them, and how you can create hierarchical categories that help you organize code elements and add attributes to child categories by using inheritance.

To assign a category to a code element

Open the .dgml file in a text or XML editor.

Find the <Node/> element for the code element that you want.

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

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

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

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

Link documents or URLs to code elements and links

You can link documents or URLs to code elements or to links by editing the map's .dgml file and adding a Reference attribute to the <Node/> element for a code element or the <Link/> element for a link. You can then open and view that content from the code element 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.

Caution

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 code elements:

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

You might link a layer diagram to a group code element 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 code element for that interface.

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

To link a document or URL to a code element

Open the .dgml file in a text or XML editor.

Find the <Node/> element for the code element that you want.

Perform one of the tasks in the following table:

A single code element

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

On the map, the name of the code element appears underlined. When you open the shortcut menu for the code element or the link, you will see a Go To Reference shortcut menu that contains the linked code elements for you to choose.

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: