How to: Explore Code with Sequence Diagrams

In Visual Studio Ultimate, generate a sequence diagram to help you visualize and understand how the code implements a particular method. A sequence diagram describes an interaction between objects as a series of lifelines and messages. Lifelines represent instances of objects, and messages represent method calls between those objects. You can generate sequence diagrams from Visual C# .NET or Visual Basic .NET code.

A generated sequence diagram shows elements similar to those on a UML sequence diagram. A sequence diagram that is generated from code exists independently of a UML model and can be added to any .NET project. By contrast, a UML sequence diagram that is drawn by hand is always part of the model in which you created it. For more information, see UML Sequence Diagrams: Reference and the following video:MSDN How Do I Series: How to Generate UML Sequence Diagrams.

In This Topic

• Generating a Sequence Diagram from Source Code

• Exploring Code on Sequence Diagrams

• Editing the Diagram to Propose Design Changes

• Navigating from the Diagram

• Linking to Interaction Elements to Work items

• Relationships to Other Diagrams

• Troubleshooting Sequence Diagrams

Generating a Sequence Diagram from Source Code

To generate a sequence diagram from code

1. In Visual Studio, open the code file that contains the method definition.

2. Right-click anywhere in the method definition, and then click Generate Sequence Diagram.

   

3. In the Generate Sequence Diagram dialog box, in the Maximum call depth box, specify the maximum level of calls that you want to see.

   For example, if you want to see only the first level of calls, specify a maximum call depth level of 1.

   Tip

   The sequence diagram will show the second level of calls as messages that have no target lifeline, which are called lost messages. After you generate the diagram, you can expand specific lost messages. For more information about lost messages, see UML Sequence Diagrams: Reference.

4. Under Include calls in, choose a scope from the following table:

   To see	Click
   Calls to items in the immediate project	Current project
   Calls to items in the solution	Current solution (default)
   Calls to items inside and outside the solution	Solution and external references

   For example, you can start with a simple sequence diagram by examining only those method calls to items in the immediate project. You can expand the scope of the diagram by generating a new one that shows calls to items across the solution. If you want to see calls to items that are not in the solution, you must generate a diagram that includes external references.

5. Under Exclude calls to, you can simplify the diagram more by omitting calls to the following items:

   To omit calls to	Select
   Properties and events	Properties and events (default)
   System namespace	System namespace (default)
   Specific namespaces	Other namespaces, and then type the namespaces in the box by using a comma (,) to separate them. Do not use wildcard (*) characters as they are not supported.

   To include calls to these items, clear their corresponding check boxes.

6. When you are finished, click OK.

   Visual Studio generates a sequence diagram and adds it to the corresponding project. For information about issues with generating sequence diagrams, see Troubleshooting Sequence Diagrams.

   Note

   Array declarations do not appear on generated sequence diagrams.

To identify and communicate changes that you might want to make without affecting the code, you can explore and modify a generated sequence diagram. For example, you can add new lifelines, messages, interaction uses, and fragments. To create and track tasks for work that you want to perform on the corresponding code, you can create or link work items to diagram elements. For more information, see How to: Link from Model Elements to Work Items.

Exploring Code on Sequence Diagrams

A sequence diagram can help you explore the code and to present it to others. To achieve the most useful diagram for these purposes, experiment with different scopes when you generate the diagram. You can also modify the diagram after you have generated it. For example, you can delete messages that are not interesting for presenting and discussing the design.

You can make the following changes to the sequence diagram.

Editing the Diagram to Propose Design Changes

You can change the diagram, adding and deleting elements to help you consider alternative designs. You can also copy parts of the diagram to a UML sequence diagram that you have created in a UML modeling project. That enables you to associate the lifelines with the types, components and actors of the UML model.

The following table summarizes changes that are useful for describing design proposals. For more details, see UML Sequence Diagrams: Guidelines.

To	Perform these steps
Highlight lifelines, messages, and other elements	Change the element's Color property. -or- Link a Comment to the element: In the Toolbox, click Comment, and then on the diagram, click near the element. In the Toolbox, click Comment Link, and then on the diagram, click the comment, and then click the element.
Move lifelines	Drag a lifeline to a different area of the diagram. To move a group of lifelines that have lost or found messages, follow these steps to select the lifelines before you move them: Draw a rectangle around the lifelines. -or- Press and hold the CTRL key while you click each lifeline. Note If you use Select All or CTRL+A to select all lifelines and then move them, any lost or found messages attached to these lifelines will not move. If this scenario occurs, you can move these messages separately.
Move and re-order messages	Drag a message up or down on the diagram. Select a message, and then: To adjust the message's position, use the UP ARROW and DOWN ARROW keys. To change the sequence of messages, use CTRL+UP ARROW and CTRL+DOWN ARROW.
Add a lifeline	Click Lifeline in the Toolbox, and then click the diagram.
Add a message	In the Toolbox, click a Synchronous or Asynchronous message. To add a found message or lost message, use an Asynchronous message. A found message comes from an unknown event source, and a lost message broadcasts to an unknown recipient. On the diagram, click a source lifeline. Click a target lifeline. - or - To create a found message or lost message, click a blank area on the diagram behind the source lifeline or in front of it, respectively. Type a new name for the message.
Copy lifelines and messages to or from other diagrams	Copy and paste lifelines. The messages between them will automatically be copied also. Note When you copy lifelines from a UML sequence diagram in a modeling project to a generated sequence diagram, the lifeline headers might only appear, or you might have to adjust their colors. To fix this issue, select the pasted lifelines, and set their Color properties.
Enclose messages in a combined fragment	Select one or more messages. Right-click your selection, point to Surround With, and then click a type of combined fragment. Use combined fragments to represent alternative sequences, loops, and other compositions of messages.
Move a message to a new diagram	Right-click a message, and then click Move to Diagram. A new diagram is created, which contains the message and its subsidiary messages. On the original diagram, the message is replaced by an Interaction Use.
Copy the diagram	Copy the diagram in Solution Explorer, or copy the files in Windows Explorer. There are two files associated with each diagram. A generated sequence diagram can be edited using any instance of Visual Studio Ultimate, and can be read using Visual Studio Ultimate or Visual Studio Premium.
Do not highlight certain manual changes, such as additions and name changes	Right-click the sequence diagram surface, and then click Properties. Set the Show Manual Changes property to False.

Navigating from the Diagram

Linking a Sequence Diagram to Work Items

To help plan the work of implementing a change, you can link elements of any kind on a sequence diagram to work items in Team Foundation Server. For more information, see How to: Link from Model Elements to Work Items.

Guidelines for Using Generated Sequence Diagrams

The following guidelines might be useful when you are exploring code with generated sequence diagrams.

Exploring the Code

Generate dependency diagrams to obtain an overall picture of the major groupings and dependencies in a large body of code. Then generate sequence diagrams to focus on individual parts of the design. For more information, see How to: Generate Dependency Graphs for .NET Code.

Interpreting the Diagram

The algorithm that creates the diagram performs a symbolic execution of your code. There are some situations that this technique does not cover. In particular, these situations include:

• Two or more lifelines might appear in the diagram where your executing code only deals with one instance. In general, a separate target lifeline is generated for each message.

• The type of a lifeline is the type declared in the program code, even if your code always uses a subtype.

Focusing on an Aspect of the Design

• Choose one aspect of the design to focus on. You can generate different diagrams to focus on different aspects, and make copies of the diagram files at any stage of your work.

• To get a useful diagram that clearly exposes an aspect of the design, you might have to experiment with the namespace filters and generation.

• Delete messages that are not relevant to the focus aspect, and expand relevant messages to show more detail.

• Use the Collapse command to group lifelines that represent a collaborating group of objects, unless their internal interactions are interesting for the aspect you are focusing on.

Updating the Design

• You can work collaboratively on a diagram using version control. We recommend that you lock a diagram when you are editing it so that only one person can edit it at a time.

• Using a generated sequence diagram, you can often identify features of the existing code that make it difficult to change or adapt. For example, you might notice that one lifeline sends all the messages, but others just respond to messages, without sending many of their own. Consider whether the work being done by this object can be more effectively divided between the other objects. Each class of object should have a single clearly-defined task. In general, this policy makes it easier to identify which parts of the program must be changed when the users' needs change, or to rearrange the parts in a different variant of the application.

• When you have a diagram that focuses on a specific aspect of the design, make copies of it and edit them to create alternative proposals for changes.

• You can copy elements of a generated sequence diagram into a UML sequence diagram. You must first create the UML sequence diagram inside a UML modeling project. There, you can model different views of the updated design, and you can link the lifelines to components or classes in the model. You can also extend the interaction to include external actors.

Troubleshooting Sequence Diagrams

The following table describes issues that might occur when generating sequence diagrams and possible resolutions:

void ILinkedWorkItemExtension.OnWorkItemCreated( ) {}

See Also

Reference

UML Sequence Diagrams: Reference

Concepts

Visualizing Existing Code

How to: Generate Dependency Graphs for .NET Code

How to: Create Layer Diagrams from Artifacts