Visualize code on sequence diagrams

To visualize how the code implements a particular method, create a sequence diagram from a method in Visual Studio Ultimate. The sequence diagram shows the 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, but not from projects that share code across multiple apps.

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.

• Generate a sequence diagram from source code

• Explore code on sequence diagrams

• Edit the diagram to propose design changes

• Go to code from the diagram

• Link a sequence diagram to work items

• Relationships to other diagrams

• Troubleshoot sequence diagrams

Generate a sequence diagram from source code

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

2. Go to the method definition, right-click inside the editor, and choose Generate Sequence Diagram.

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

   

   Note

   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	Choose
   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. Check the box if you want to add the diagram to the current project.

7. When you are finished, choose OK to generate the sequence diagram.

   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 Link Model Elements and Work Items.

Important

After you generate the diagram, any changes that you make to the diagram will not appear in the code, and any changes that you make to the code will not appear on the diagram. To show these changes, you must generate a new sequence diagram. You can generate a new sequence diagram from the same method as many times as you want.

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

To	Perform these steps
Show the next level of call	Open the shortcut menu for a message that has no target lifeline, and then choose Expand Outgoing.
Expand a message in a new diagram	Open the shortcut menu for a message, and then choose Generate Sequence Diagram. The new diagram is added to the current project.
Collapse a group of messages into one lifeline.	Select the lifelines that you want to group, open the shortcut menu for the selection, and then choose Collapse. You can rename a group, but the name will be lost when you expand it. To expand the group, open the shortcut menu for it and then choose Expand.
Delete elements	Open the shortcut menu for the shape and then choose Delete.
Improve the layout	Open the shortcut menu for a blank area of the diagram, and then choose Rearrange Layout. You can also undo this command.
Highlight selected elements	Open the shortcut menu for an element and then choose Properties. In the Properties window, set the Color field.
Annotate the diagram	Choose the Comment tool, click in the diagram, and then type a note into the comment. Use the Comment Link tool to connect the comment to one or more points on lifelines or fragments.

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, choose Comment, and then on the diagram, click near the element. In the Toolbox, choose Comment Link, and then on the diagram, choose the comment, and then choose 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 choose 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	Choose Lifeline in the Toolbox, and then choose the diagram.
Add a message	In the Toolbox, choose 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, choose a source lifeline. Choose a target lifeline. - or - To create a found message or lost message, choose 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. Open the shortcut menu for your selection, point to Surround With, and then choose 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	Open the shortcut menu for a message, and then choose 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	Open the shortcut menu for the sequence diagram surface, and then choose Properties. Set the Show Manual Changes property to False.

Go to code from the diagram

To	Perform these steps
Navigate from a lifeline or message to the definition of the class or method, respectively	Open the shortcut menu for the lifeline or message, and then choose Go To Definition.
Find the class or method in Architecture Explorer	Open the shortcut menu for a lifeline or message, and then choose Show in Architecture Explorer. For more information, see Map dependencies across your code on dependency graphs.

Link 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. Before you start, make sure that you are connected to a Team Foundation Server. For more information, see Link Model Elements and Work Items.

Warning

You must already be connected to TFS Source Code Control (SCC) to create or link to a work item. If you try to open a connection to a different TFS SCC, Visual Studio closes the current solution automatically. Ensure that you are already connected to the appropriate SCC before attempting to create or link to a work item. In later releases of Visual Studio, the menu commands are not available if you are not connected to an SCC.

To	Perform these steps
Create and link new work items to lifelines, messages, or other elements	Open the shortcut menu for one or multiple elements, choose Create Work Item, and then choose the type of work item that you want to create. A new work item opens so that you can complete it.
Link lifelines, messages, or other elements to work items	Open the shortcut menu for one or multiple elements, and then choose Link to Work Item. In the Link to Work Items dialog box, run a query to find a work item, or enter its ID directly. You can select any number of work items. You can later repeat this command to add more work item links to the same model element.
View linked work items	Open the shortcut menu for one or multiple elements, and then choose View Work Items.
Remove links to work items	Open the shortcut menu for an element, and then choose Remove Work Items. In the Remove Links to Work Items dialog box, choose the work item links that you want to remove. The links between the model element and the chosen work items are deleted. The work items and the model elements are not removed.

Guidelines for using generated sequence diagrams

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

Explore 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 Map dependencies across your code on dependency graphs.

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

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

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

Troubleshoot sequence diagrams

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

Issue	Resolution
Sequence diagram cannot be generated.	A sequence diagram might not generate if the System namespace is excluded, and the code contains a call to a COM method that accepts ref or out parameters and passes a parameter by using the new keyword. To avoid this issue, change the code, or when you generate the diagram, include the System namespace.
A blank sequence diagram is generated after the following message is displayed: "Object reference not set to an instance of an object." This issue occurs when a sequence diagram is generated from an explicit implementation of an interface method, and the diagram is not added to the source project automatically. An explicit implementation precedes the method name with the interface name and a period (.). For example, this issue occurs when you generate a sequence diagram from the following signature and do not add the sequence diagram to the project automatically: void ILinkedWorkItemExtension.OnWorkItemCreated( ) {}	When it is possible, do not include the interface name and period (.). -or- In the sequence diagram generation dialog box, make sure to add the sequence diagram to the project automatically.
Sequence diagram takes very long to generate. - or - Sequence diagram crashes on reopening. Depending on your computer configuration, the sequence diagram might be too large to generate quickly and might cause Visual Studio to run out of memory and crash when you close and then reopen the diagram. For example, a sequence diagram that has 390 lifelines and 19,000 messages results in a diagram file that is more than 85 MB.	Reduce the scope of the diagram by decreasing the call depth, filtering out unnecessary namespaces, removing properties and events, and so on.

See Also

Reference

UML Sequence Diagrams: Reference

Concepts

Visualize code

Map dependencies across your code on dependency graphs

Create layer diagrams from code