How to: Generate Dependency Graphs for .NET Code

To explore the organization and relationships in .NET code, use Visual Studio Ultimate to generate dependency graphs. Use these graphs to help you visualize, explore, and analyze dependencies in code. A graph represents code elements and their relationships as a set of nodes that are connected by links, or edges.

Note

   If you have a very large solution, generating a dependency graph might cause an out of memory exception. If this occurs, reduce the scope of your solution. You can also use Architecture Explorer to select the projects and dependencies that you want to visualize, and then generate the graph.

To generate dependency graphs for C and C++ code and for Web projects, download and install Microsoft Visual Studio 2010 Visualization and Modeling Feature Pack.

For more information, see:

• How to: Generate Dependency Graphs for C and C++ Code

• How to: Generate Dependency Graphs for ASP.NET Web Projects

Choose a Dependency Graph to Generate

Visual Studio Ultimate lets you generate graph documents quickly to explore dependencies in the code. To generate graph documents by using a command-line tool, see Generate Graph Documents for Batch Processing.

To	Generate a graph that shows relationships
See an overview of source code	Between all assemblies, all namespaces, or all classes in a Visual Studio solution. The graph shows aggregated dependencies for the top level of nodes that you selected.
See specific dependencies in source code	Between selected areas of source code in a Visual Studio solution. Use Architecture Explorer to browse the code hierarchically and to select specific kinds of structures and relationships.
See an overview of compiled code	In one or multiple .NET assembly (.dll) files or executable (.exe) files
See specific dependencies in compiled code	Between selected areas in .NET assembly (.dll) or executable (.exe) files. Use Architecture Explorer to browse and select specific kinds of structures and relationships.

After you generate the graph, you can use it to explore code in different ways. For more information, see How to: Explore Code with Dependency Graphs.

See an Overview of Source Code in a Visual Studio Solution

1. Open the solution.

2. On the Architecture menu, point to Generate Dependency Graph, and then perform one of the following steps:

   Click	To generate a graph that shows
   By Assembly	Aggregated dependencies between all the assemblies produced by your solution and any external dependencies that they depend on. To see the namespaces, classes, and methods inside an assembly, expand the assembly on the graph. External assemblies show only those items that are in use.
   By Namespace	Aggregated dependencies between all the namespaces in your solution and any external namespaces that the code depends on. To see the classes and methods inside a namespace, expand the namespace on the graph. External namespaces show only those items that are in use.
   By Class	Aggregated dependencies between all the classes in your solution. No information about external classes used by the code will appear.

   -or-

   To see dependencies across multiple types of structures, click Custom.

   1. In the Generate Dependency Graph dialog box, click at least one of the following boxes: Assemblies, Namespaces, Types, or Methods.

   2. Use the following table to filter the graph:

      To	Perform these steps
      See references to external dependencies. This is useful for exploring how internal assemblies build on external assemblies.	Select Externals
      See only those types and methods with specific access levels. For example, you might want to simplify the graph by selecting only public types.	Expand the Access Filter pane, and then select the levels that you want. Note You must select at least one type access level. To reduce the number of dependencies on the graph, select only the access levels that you want for methods.
      See high-level dependencies by showing containment relationships as nested groups and dependencies as aggregated links. Note For methods, dependencies will appear as individual links, not aggregated links because methods are the lowest-level leaf nodes.	Select the Show Containment as Group box.
      See low-level dependencies by showing containment relationships as linked nodes and dependencies as individual links.	Clear the Show Containment as Group box.

   3. When you are finished, click OK.

      Visual Studio creates a directed graph document (.dgml file) and opens it.

   The thickness of the link for an aggregated dependency indicates approximately how many individual dependencies that the aggregated dependency represents. To see the kinds of dependencies that the link represents, move the pointer over the link until the tooltip appears.

   Note

   Dependency graphs that you generate from the Architecture menu do not show calls to virtual methods down to the most derived type. Instead, they show dependencies on the types that declare those virtual members. However, you can use Class View in Architecture Explorer to find those calls. You can then drag them from Architecture Explorer to an existing graph, or you can generate a new graph from the Architecture Explorer toolbar.

See Specific Dependencies in Source Code in a Visual Studio Solution

Use Architecture Explorer to find the code and relationships that you want to visualize. You can also use predefined queries to generate a graph.

1. Open the solution.

2. If Architecture Explorer is not open, on the Architecture menu, point to Windows, and then click Architecture Explorer.

3. In the first column of Architecture Explorer, under Visual Studio, click one of the following views:

   • Class View to explore the logical hierarchy of the code.

     Use to browse namespaces, types, methods, and so on.

   • Solution View to explore the physical hierarchy of the code

     Use to browse projects, source files, and so on.

4. In the next column, select the items that you want to explore. To select everything in the column, press CTRL+A.

   The next column shows items that are related to your selection based on the default kinds of items and relationships for that column.

   Note

   To select other kinds of items and relationships, expand the collapsed column to the right of the column with your selections. Under Node Navigation, select the kinds of items that you want. Under Outbound Navigation or Inbound Navigation, select the kinds of relationships that you want. For more information, see How to: Find Code Using Architecture Explorer.

5. Repeat step 4 until you select all the items that you want.

   Note

   To include Calls dependencies on your graph, browse to and select all the methods that are called by your selected classes.

6. To create a new graph from your selection, under the Architecture Explorer title bar, click Create a new graph document from all the selected nodes.

   Visual Studio creates a directed graph document (.dgml file) and opens it.

   -or-

   To add your selection to an existing graph or to a blank graph, follow these steps:

   1. Open the existing graph's .dgml file, or create a blank graph.

   2. Under the Architecture Explorer title bar, click Add all the selected nodes to the currently visible graph document.

      -or-

      Drag the nodes from Architecture Explorer to the graph.

Create a Blank Graph

1. To open a blank graph, on the File menu, point to New, and then click File.

   -or-

   To add a blank graph to the Solution Items folder, in Solution Explorer, right-click the top-level solution node, and then click Add New Item.

2. Under Installed Templates, click General.

3. In the right pane, click Directed Graph Document, name the graph, and then click Add.

For more information about different ways that you can interact with the graph, click the help link that appears on the blank graph.

Explore Source Code by using Predefined Queries

1. Open the solution.

2. If Architecture Explorer is not open, on the Architecture menu, point to Windows, and then click Architecture Explorer.

3. In the first column of Architecture Explorer, under Saved DGQL Queries, click In Folders.

4. In the next column, click one of the following queries, depending on the kind of graph that you want to create:

   To generate a graph that shows	Click
   All assemblies that are referenced by the solution. From the query results, you can generate a graph that shows the dependencies between these assemblies.	All Assembly References.dgql
   A flat list of all the output assemblies in the solution without dependency links.	All Output Assemblies.dgql To generate a standard dependency graph for selected assemblies, follow these steps: In the next column, select the assemblies that you want. Along the right side of the current column, click the collapsed action column to expand it. Note The action column appears highlighted when you move the pointer over it. In the action column, under Commands, click Standard Graph.
   All projects in the solution. From the query results, you can generate a graph that shows the references between these projects.	All Project References.dgql
   A flat list of all the projects in the solution. If your solution includes solution folders, this list differs from the one shown when you click Solution View in Architecture Explorer.	All Projects.dgql
   All types in the solution. From the query results, you can generate a graph that shows the inheritance relationships between these types.	Inheritance Graph.dgql

   The next column shows the results as a flat list. Although links might exist between these nodes, Architecture Explorer will not show them.

5. To generate a graph, including the links, for all items in the results column, follow these steps:

   1. In the results column, press CTRL+A to select all the items.

   2. Press and hold the CTRL key to include only items in the current column on the graph, and then under the Architecture Explorer title bar, click Create a new graph document from all the selected nodes.

      Visual Studio creates a directed graph document (.dgml file) and opens it.

See an Overview of Compiled Code

1. Create a blank graph, or open an existing graph's .dgml file.

2. From outside Visual Studio, drag the .dll file or .exe file to the graph.

   Note

   Dragging from the References folder in Solution Explorer is not supported. You can drag assemblies from Windows Explorer only if you are running Windows Explorer and Visual Studio at the same User Access Control (UAC) permissions level. For example, if UAC is turned on, and you are running Visual Studio as an administrator, then Windows Explorer will block the dragging operation. To work around this, turn UAC off or use the predefined queries to explore your solution.

See Specific Dependencies in Compiled Code

1. If Architecture Explorer is not open, on the Architecture menu, point to Windows, and then click Architecture Explorer.

2. In the first column, under File System, click Select Files.

3. In the Open box, browse to the .dll files or .exe files to select and open them.

4. In the next column, select the assemblies. To select everything in the column, press CTRL+A.

   The next column shows items that are related to your selection based on the default kinds of items and relationships for that column.

   Note

   To select other kinds of items and relationships, expand the collapsed column to the right of the column with your selections. The action column appears highlighted when you move the pointer over it. Under Node Navigation, select the kinds of items that you want. Under Outbound Navigation or Inbound Navigation, select the kinds of relationships that you want. For more information, see How to: Find Code Using Architecture Explorer.

5. Choose one of the following:

   To create a dependency graph from the following items	Follow these steps
   Assemblies	To the right of the column that contains the assemblies, click the collapsed action column to expand it. The action column appears highlighted when you move the pointer over it. In the action column, under Commands, click Standard Graph.
   Classes and methods	Browse through the classes and methods, selecting all the items that you want to include on the graph. To create a new graph, under the Architecture Explorer title bar, click Create a new graph document from all the selected nodes. Visual Studio creates a directed graph document (.dgml file) and opens it. -or- To add your selection to an existing graph, or to a blank graph, follow these steps: Open the existing graph's .dgml file, or create a blank graph. Under the Architecture Explorer title bar, click Add all the selected nodes to the currently visible graph document. -or- Drag the nodes from Architecture Explorer to the graph.

Generate Graph Documents for Batch Processing

To generate graph documents (.dgml files) in batch mode, use the GraphCmd.exe command-line tool. For example, you can find dependencies that have changed between builds by running the tool after each build.

To find this tool, look in the following folder: C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE.

Note

GraphCmd.exe generates dependency information only for assemblies or .dgml files, not source code in Visual Studio solution or project files.

The syntax for GraphCmd.exe is:

GraphCmd -? -all -exceptions -input File_Name -query File_Name -exec

"DGQL_Statement" -output File_Name -path alias=path

The following table describes the options for GraphCmd.exe:

-?	Display the help for GraphCmd.exe.
-all	Include all intermediate query results, not just for the last node set.
-exceptions	Report the query exceptions as a graph document (.dgml) file.
-input File_Name	Process the specified .dgml file. This is useful for post-processing a large .dgml file and filtering it so that you can visualize it more easily in Visual Studio.
-query File_Name	Run the specified Directed Graph Query Language (DGQL or .dgql) file. For more information, see: How to: Find Code Using Architecture Explorer Understanding Directed Graph Query Language (DGQL)
-exec "DGQL_Statement"	Run the specified DGQL statement. For more information, see Understanding Directed Graph Query Language (DGQL).
-output File_Name	Output the specified .dgml file.
-path alias=path	Specify a new alias to use in the input and output of DGML documents. For example: GraphCmd -output MyGeneratedGraph.dgml -path "MyPathAlias=C:\Program Files\..." For more information, see Aliases for Commonly-Used Paths.

Remarks

GraphCmd.exe runs outside Visual Studio, so support for actions in .dgql queries is limited.

You can specify the following options multiple times: -input, -query, -exec, and -path.

Aliases for Commonly-Used Paths

Aliases for commonly-used paths 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 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>

For more information about editing .dgml files, see How to: Edit and Customize Graph Documents.

Understanding Directed Graph Query Language (DGQL)

DGQL is a lightweight query language that you can use to build DGML. A DGQL statement follows an alternating pattern of node selection and actions such that each node selection creates input for the next action, whose output becomes input for the next node selection, and so on.

The format of a DGQL statement is:

<node selection> / <action> / <node selection> / <action> / ...

The following table describes the DGQL syntax used to select nodes:

*	Select all nodes.
+ "text"	Select all nodes that contain "text".
+ Id.Equals("text")	Select all nodes whose Id is equal to "text".
+ Background.Contains("text")	Select all nodes whose Background attribute has a value that contains the string "text".
+ "text1" + "text2" + ...	Select all nodes that match "text1" or "text2".
+ MyProperty="True"	Select all nodes that have a property named MyProperty whose value is "True".
- Label.Contains("text")	Select all nodes except those that have a Label attribute that Contains the string "text".
+ Category.Is("MyCategory")	Select all nodes that have a category named MyCategory or that inherits from MyCategory.

Actions are provided by DGML data providers that are registered in Visual Studio, but you can discover these actions by saving a query that was created in Architecture Explorer. For more information about using Architecture Explorer, see How to: Find Code Using Architecture Explorer.

The following table describes examples of direct actions that can be performed on selected nodes:

Example action	Description
Microsoft.Contains	Return all nodes that are contained by the input nodes. You can replace Contains with a different link category.
Microsoft.Open	Open the source code for the input nodes. Note Works only within Visual Studio.
Microsoft.AllOutBoundLinks	Return all nodes that are the target of an outgoing link from the input nodes.
Microsoft.AllInboundLinks	Return all nodes that are the source end of a link to the input nodes.
Microsoft.Core.CreateGroupsByProperties	Invoke the GroupByProperties action.
Microsoft.AllNodes	Return all nodes in the entire graph thus far.

Data-driven actions select items based only on the data in the input nodes and links. When matching categories using data-driven actions, inherited categories are included. The following table describes examples of data-driven actions:

Type	Description
Node:Both:Category	Return all nodes that have the category Category and are connected with the input nodes by a link that points in either direction.
Link:Both:Category	Return all nodes that are connected with the input nodes by a link that points in either direction and has the category Category.
Link:Backward:Category	Return all nodes that point to the input nodes with a link that has the category Category.
Link:Forward:Category	Return all nodes that point from the input nodes with a link that has the category Category.

Tips

• Typically, there is a "default" action for a given set of input nodes, which is selected automatically by Architecture Explorer. To get the same behavior, use an empty action: //

• Whitespace is not significant in DGQL, so you can format your query to fit on one line if necessary. This is useful when you use the –exec option with GraphCmd.

• When debugging DGQL, use the action "Execute Expanded" in Architecture Explorer to help you see each step of the query and find the step that is not producing the expected results.

Example

The following DGQL statement performs a query as described in the following steps:

+ Id.Equals("Microsoft.Solution.ClassView") / "Microsoft.Solution.ClassView" / * / "Node:Both:CodeSchema_Class" / + CodeSchemaProperty_IsPublic.Equals("True")

1. Start by selecting the Class View node in the first column of Architecture Explorer.

2. Performs the action "Microsoft.Solution.ClassView", returning all the namespaces in the solution. 

3. Use * to select all the namespaces.

4. Select all nodes that have the category CodeSchema_Class and are related to those namespaces by a link in either direction. These will usually be containment links.

5. Filter the resulting classes to only those that have the property CodeSchemaProperty_IsPublic="True".

Technically, the action "Microsoft.Solution.ClassView" is unnecessary because it is the "default" action for the Class View node. Therefore, you can replace that action with // to simplify the query and format it on a single line as follows:

+Id.Equals("Microsoft.Solution.ClassView")//*/"Node:Both:CodeSchema_Class"/+CodeSchemaProperty_IsPublic.Equals("True")

See Also

Concepts

How to: Explore Code with Dependency Graphs

How to: Browse and Navigate Graph Documents

How to: Edit and Customize Graph Documents

How to: Save, Share, and Export Graph Documents

Visualizing Existing Code