Using Class Designer to document your code – Exporting diagrams as images

  • Articolo

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

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

Comments

  • Anonymous
    May 07, 2005
    Ian's weekly review of his working week, including 'best of the blogs' and new book reviews. Week ending 8th May 2005. This week's review discusses XML Documentation in VS.Net, VS.Net 2003 debugging, a brief technical podcast review, a rant about the Coding4Fun web site samples, notes on SQL Server 2000 SP4 installation, the new Windows Server 2003 Resource Kit, and learning Adobe's InDesign with Classroom-in-a-book.
  • Anonymous
    May 08, 2005
    Visual Studio Team System

    If you’re installing Beta 2 using Virtual PC, you should learn to appreciate...
  • Anonymous
    May 15, 2005
    The comment has been removed
  • Anonymous
    May 18, 2005
    Daniel: You can do Show All Associations now using the add-in: http://blogs.msdn.com/classdesigner/archive/2005/05/17/418966.aspx Although it's not a part of the product, we're looking for your feedback to be able to understand how this feature should really work for the future releases.

    Regards
    Dmitriy