Visualize code on sequence diagrams
To visualize how the code implements a particular method, create a sequence diagram from that 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
Navigate 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
In Visual Studio Ultimate, open the code file that contains the method definition.
Go to the method definition.
Right-click inside the code editor. Choose Generate Sequence Diagram.
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.
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.
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.
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.
When you are finished, choose 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 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. |
Edit 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:
|
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:
|
Move and re-order messages |
Drag a message up or down on the diagram.
|
Add a lifeline |
Choose Lifeline in the Toolbox, and then choose the diagram. |
Add a 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 |
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 |
|
Navigate 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.
To |
Perform these steps |
---|---|
Create and link new work items to lifelines, messages, or other elements |
|
Link lifelines, messages, or other elements to 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 |
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:
|
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