How to: Explore Code with Sequence Diagrams

Článek
07/22/2011

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. To generate sequence diagrams from ASP.NET Web site projects, install the Visual Studio 2010 Microsoft Visual Studio 2010 Visualization and Modeling Feature Pack.

Poznámka

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.

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.

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

In Visual Studio, open the code file that contains the method definition.
Right-click anywhere in the method definition, and then click 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. The sequence diagram will show the second level of calls as messages that have no target lifeline, which are called lost messages.

Poznámka

After you generate the diagram, you can expand specific lost messages.

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.

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

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

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.

Poznámka

Array declarations do not appear on generated sequence diagrams.

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.

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.

To	Perform these steps
Show the next level of call	Right-click a message that has no target lifeline, and then click Expand Outgoing.
Expand a message in a new diagram	Right-click a message, and then click 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, right-click the selection, and then click Collapse. You can rename a group, but the name will be lost when you expand it. To expand the group, right-click it and then click Expand.
Delete elements	Right-click the shape and then click Delete.
Improve the layout	Right-click a blank area of the diagram, and then click Rearrange Layout. You can also undo this command.
Highlight selected elements	Right-click an element and then click Properties. In the Properties window, set the Color field.
Annotate the diagram	Click 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, 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

To	Perform these steps
Navigate from a lifeline or message to the definition of the class or method, respectively	Right-click the lifeline or message, and then click Go To Definition.
Find the class or method in Architecture Explorer	Right-click a lifeline or message, and then click Show in Architecture Explorer. For more information, see How to: Generate Dependency Graphs for .NET Code.

Navigate from a lifeline or message to the definition of the class or method, respectively

Right-click the lifeline or message, and then click Go To Definition.

Find the class or method in Architecture Explorer

Right-click a lifeline or message, and then click Show in Architecture Explorer.

For more information, see How to: Generate Dependency Graphs for .NET Code.

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.

To	Perform these steps
Link lifelines, messages or other elements to work items	Right-click one or multiple elements, and then click 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	Right-click one or multiple elements, and then click View Work Items.
Remove links to work items	Right-click an element, and then click Remove Work Items. In the Remove Links to Work Items dialog box, click 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.

Link lifelines, messages or other elements to work items

Right-click one or multiple elements, and then click 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

Right-click one or multiple elements, and then click View Work Items.

Remove links to work items

Right-click an element, and then click Remove Work Items.
In the Remove Links to Work Items dialog box, click 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.

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:

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.

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.

Change History

Date	History	Reason
August 2010	Updated topic to mention that the Visual Studio 2010 Microsoft Visual Studio 2010 Visualization and Modeling Feature Pack is required to generate sequence diagrams for ASP.NET Web site projects.	Customer feedback.

August 2010

Updated topic to mention that the Visual Studio 2010 Microsoft Visual Studio 2010 Visualization and Modeling Feature Pack is required to generate sequence diagrams for ASP.NET Web site projects.

Customer feedback.

Sdílet prostřednictvím