One of the design goals of Class Designer was to enable developers to easily document the design of applications and keep it in sync with the code. Class diagrams residing in Visual Studio projects solve this purpose very well, however more traditional documentation formats commonly used for external documentation or presentation such as Microsoft Office documents or web-pages, require diagrams to be saved in some image format.

“Export as Image” functionality provided by Class Designer allows you to export all or a subset of class diagrams inside a solution with a few mouse clicks. In this post I’ll describe how to use this feature to produce project design documentation and keep it in sync later on.

Preparing Diagram for Export

Before you save diagrams as images for embedding into Office documents or publishing on the web, you can use class diagram annotation and customization features to make diagrams better explain your design.

While working with a class diagram within Visual Studio tool-tips and live code are available right there to look at, this information is not accessible when diagram is saved as an image – thus you might want to display types of members on the diagram using the “Display Member Types” command available from toolbar or diagram context menu.

In case you’re documenting a general-purpose API which will be consumed by external customers, you might want to filter members visible on the diagram to those of public and protected visibility and hide all private/internal details of implementation. You can use “Group by Access” mode of the diagram (available from toolbar) to see all private/internal members in groups and hide groups of members by invoking “Hide Compartment” command on Private or Internal compartments. Another thing to consider would be removing private/internal types from diagrams for public consumption.

Finally, you can make great use of comment shapes to annotate your diagram to explain design decisions and to clarify the purpose of different elements. To create a comment shape, open the Toolbox tool window, then drag & drop a Comment item on the diagram and enter your annotation text.

Here is an example of a class diagram customized for documentation:

Exporting Diagrams as Images 

When the diagram(s) are ready for export, simply right-click empty design surface area of the diagram and choose “Export Diagram as Image…” menu item – you will see Export Diagram as Image dialog opened and the active diagram checked in the diagrams list:

If you click Export button now a diagram image with the same name as diagram name and .png extension, designating Portable Network Graphics format, will be created at the same location where your solution (.sln) file is located on disk.

Lets take a quick look over dialog elements. 

Diagrams check list – this element allows you to choose diagrams to be exported and contains a full list of all diagrams included in the projects of the currently opened solution.

Overwrite existing files – this option switches on or off the prompt for image file overwrite – when the check-box is set (the default), Class Designer won’t ask you to overwrite existing files. 

Export location – specifies path of the folder where diagram image files will be created.

Image format – allows you to choose the format of exported images from a list of standard formats (BMP, JPEG, GIF, PNG, TIFF and EMF). If you need a quality/size balance, PNG format is probably a good choice, however if quality is important and/or diagram is large and needs to scale, EMF (Enhanced Metadata Format) might be a better choice.  

When you click Export and all checked diagrams are exported to specified location in format selected, dialog settings are also stored in the user options file (.suo) for the opened solution. Next time you use the Export dialog, all choices are preserved unless you change it again or remove the .suo file from solution folder.

Documentation Scenarios 

Now lets take a look how “Export Diagram as Image” functionality can be used in documentation scenarios.

One scenario is when diagrams are published to web and linked from web-pages – in this case most likely there’s a folder on the web-site containing diagram images, so specifying this folder in the “Export Diagram as Image” dialog would directly update the web-site content replacing existing diagram images with the current versions. 

When documentation represents a set of Office documents, diagram images are embedded into the documents. You do so by using “Insert | Picture | From File…” command from Microsoft Word menu. This menu item brings Insert Picture dialog which lets you choose the image to insert. Default behavior of this command is to copy image into the document. However another option might look more attractive from the point of view of continuous updates to diagrams used within the document when code they’re generated from is changing. Instead of storing the image in the Word document itself, store a link to the image file in disk – you can choose this option by clicking on the down arrow icon on the “Insert” button of Insert Picture dialog and choosing “Link to File” or “Insert and Link”:

In case of “Link to File” the document will always display the external image file and in the case of “Insert and Link” the image will still be inserted into the document, however a link to the file on disk will be added so that when the image file is updated, the image stored in the document will be updated as well. 

Using image linking option you can keep your design documentation up-to-date with minimal effort by invoking the “Export Diagram as Image” command from Class Designer. Images in design documents will be updated automatically when you update diagram images using Export as Image.

Copy Image Command 

Cases when you need to copy/paste just a single class shape or a couple of types with lines from a class diagram to a Word document or e-mail are quite often. Exporting the whole diagram in such situations neither practical nor reasonable. For these cases Copy Image command available on type shapes and/or multiple selection of those comes in handy – this command places the image of current selection on clipboard in BMP and WMF formats. When you paste “Copy Image” result into raster applications such as Paint the BMP format will be placed. Pasting into Word documents will paste a vector-base scalable image of the diagram which doesn’t loose quality/clarity on reasonable resizing.

What is the difference between Copy and Copy Image? 

You might ask why there are two commands available – Copy and “Copy as Image”? The usual Copy command (available via Ctrl+C) places on clipboard shape information (e.g. for cloning code or copying the shape to another diagram) as well as regular raster BMP image of selection. “Copy Image” command as described above places BMP format as well and WMF format, but doesn’t place shape info, so it can’t be used to copy the shape.

Dmitriy Vasyura
Visual Studio Class Designer Team

Original Link

Here are the shapes after the following customizations:

• XmlNode
  • Methods compartment is collapsed to hide all methods.
  • The Attributes property is shown as a line pointing to XmlAttributeCollection class, rather than just a regular member inside the shape.
  • The following properties are hidden on the diagram: BaseURI, InnerXml, IsReadOnly, LocalName, NamespaceURI, NextSibling, OuterXml, OwnerDocument, Prefix, PreviousSibling, SchemaInfo.
  • “Lollipop” is collapsed – the diagram now communicates that the class implements one or more interfaces, but it isn’t important to show in this diagram precisely which interfaces are implemented.
• XmlAttributeCollection
  • Shape is collapsed to hide all its members.
  • Width is increased so that entire name is readable.

Class Designer has a couple of cool features that helps you preserve your shape customizations in scenarios described earlier (refactoring your code with the class diagrams closed).  I mentioned earlier the thing that associates a shape to code is the fully qualified type name and the source artifact name.  Well, there is one additional piece of information that is also stored for a shape – a hash code value.  This value is computed from the member signatures (other than constructor/destructor) of the various members in the class.  When the class diagram is opened, if the class designer cannot find the type in the source file, it will look for other classes defined in the same file and compute the hash value for those classes.  If it finds one that falls within a certain pre-determined threshold percentage, then class designer will assume that type to be the one representing the shape and associate it with that shape.  Obviously, this heuristic will work better if the class has more members.  The reason we don’t require an exact match of the hash value is because it is likely that along with the rename, you might have added or changed a few members.  But it may be the case that you also changed the file name along with the class name.  If this is so, the class designer will go through all the files in your project and try to find a class that is the best match.  Note if your project contains a lot of files this will result in a delay in opening the diagram.  If your project contains more than 50 files, Class Designer will give you an option of doing this search or not.

Under what circumstances will I see orphan shapes in my diagram?

The class designer makes a reasonable effort to keep your diagram intact by using this heuristic.  However, as any solution based on heuristics, it is likely that there are situations where Class Designer cannot make an association between a shape and the type it represents.  Or you may have a large project and choose to not wait for Class Designer to search through all the files to look for a match.  In such situations, when you open a diagram, you will get what we call an “Orphan” shape on the diagram for any shapes that cannot be associated with its type.  Here is an example:

The following table lists the possible causes for an orphaned shape in your diagram.

If you hover over the shape you will get tooltip text that says code is missing for the shape and how you can associate the shape back to the type.

As the tooltip text suggests, you can either type in the new fully qualified name for the shape (either in-place on the shape or in the property browser) or drag and drop the renamed type from Class View.  Once this association is made, the Class Designer will restore the shape with all the customizations that still apply including lines coming to and going from the shape!

A simple walkthrough:

The following section provides a simple walk through that lets you experiment with this feature:

1.     Create a new C# class library. In the auto-generated class Class1, add a new method foo which looks like this:

 
public void foo(int i)
{
}
 
 

5.     Re-open the diagram and you will see that the diagram now shows class MyClass

In this example, Class Designer’s heuristics determined that there is a high probability that the shape that used to be associated with Class1 ought to be associated with MyClass.  In most cases, the heuristic can reconcile differences well enough to re-associate shapes to types.  In the event it cannot, please read on…

You can re-associate an orphaned shape to a type using one of the following methods:

1.     Drag/drop a type node from Class View onto the orphaned shape. The orphaned shape will display appropriate drop target feedback when a Class View type is dragged onto it for re-association.

           Here are a couple of things to keep in mind:

a.     You cannot drop a selection containing multiple types from the Class View onto an orphaned shape.  If you try to do so, a no-smoking icon will appear to indicate that the shape is rejecting the types.

b.     You cannot drop a type from Class View onto an orphaned shape if the type is already represented by another shape on the diagram.  A no-smoking icon will appear to indicate that that type cannot be dropped on the shape.

2.     Rename the shape to match the name of the type that you want it to be associated with. You can rename a shape by single-clicking on its name; this will put you in edit mode.  Alternatively, you can right-click on the orphan shape and choose “Relink Shape with Code” and then enter the name of the type that you want the shape to be associated with.  When you’re done, press ENTER to commit the change.

3.     Another alternative is simply to rename the class in the code file to match the name of the orphaned shape. Class Designer automatically will recognize the match and associated the type with the shape.

4.     Or, if you don’t want the orphaned shape anymore, you can simply delete it.

Ramesh Rajagopal and Patrick Tseng

Microsoft Visual Studio Class Designer Team