ReadMe for Class Diagrammer 1.4.4

Table of Contents

1. Quick Start
2. Documentation
3. System Requirements
4. Security Permissions
5. Installed Files
6. Deinstallation
7. Source Package
8. Copyright Notice
9. Known Issues

1. Quick Start

Make sure that the .NET Framework 4.0 Client Profile is installed on your Microsoft Windows system. Unpack the binary package to any directory of your choice.

Run the GUI application Diagrammer.exe and open the file SampleProject.xml in the same directory. This project contains a few sample diagrams based on the assemblies that ship with Class Diagrammer. Try creating an output job to publish the diagrams as image files!

Alternatively, create your own project. Add the .NET assemblies that define your classes, then create your class diagrams, and finally define output jobs. Run the output jobs to save or print images of your diagrams.

Once your project is saved, you can also run the console application Diagrammer.Console.exe to run all or some output jobs without loading the GUI front-end.

2. Documentation

The Class Diagrammer GUI application is documented by context-sensitive online help.

• Pressing the F1 key will bring up the help entry for the current dialog while one is shown, or for the selected menu item while browsing the main menu. Most dialogs also feature a Help button that has the same effect.
• Pressing the F1 key when no dialog or menu is active will display the introduction page and a list of help topics. The menu command Help: Contents has the same effect.

The Class Diagrammer console application shows usage information when invoked without any command line parameters, or with the switch “-?” or “/?”.

Class Reference

The Class Diagrammer source code is documented by a comprehensive class reference, available as a separate download at the Class Diagrammer home page. This reference was created from XML source code comments using the free Sandcastle help compiler.

To recreate the class reference from the Source Package, you also need the Microsoft HTML Help Workshop. To view the class reference, you need the Microsoft HTML Help Viewer. You can obtain the current versions of both programs at this MSDN page.

3. System Requirements

Class Diagrammer requires a Microsoft Windows system capable of running the Microsoft .NET Framework 4.0 Client Profile. This includes the following operating systems:

• Microsoft Windows XP SP3
• Microsoft Windows Vista SP1 or later
• Microsoft Windows 7
• Microsoft Windows Server 2003 SP2
• Microsoft Windows Server 2008 & R2 (except Server Core Role)

On all of these systems, Microsoft Internet Explorer 5.01 or later and Microsoft Windows Installer 3.1 or later are also required.

4. Security Permissions

Class Diagrammer requires a number of .NET security permissions that are available only when the executable is running with “Full Trust”. This is usually the case for all .NET programs that are run from a local hard disk or a shared network drive. Class Diagrammer does not require administrator privileges.

Note: Although .NET executables receive “Full Trust” permissions when running from a shared network drive, you will not be able to view the online help. Microsoft’s Compiled HTML Help File format relies on an ActiveX control for Internet Explorer, and that control cannot run over a network for security reasons. Unfortunately there is no reasonable workaround, other than running Class Diagrammer from a local hard disk.

5. Installed Files

The binary package contains the following files:

6. Deinstallation

Since Class Diagrammer has no formal installer, you can simply uninstall the binary package by deleting its directory. You may also with to delete your user settings which are saved under the Kynosarges subdirectory of the local application data folder of any user who had been running Class Diagrammer.

7. Source Package

This section provides additional information regarding the source package, available as a separate download at the Class Diagrammer home page.

The directory to which the archive was unpacked contains the source files required to build all .NET assemblies comprising the binary package. You need either Microsoft Visual Studio 2010 or the free Microsoft Windows SDK 7.1 for Windows 7 and .NET 4.0 to perform the build. Both have the same system requirements as the .NET Framework 4.0 itself, but the Windows SDK also requires that you first install the full .NET Framework 4.0 – not just the Client Profile.

The subdirectory Tektosyne contains version 5.6.2 of my Tektosyne library. The current version of this class library is also available as a separate download at the Tektosyne home page, but this is not required to run or compile Class Diagrammer.

Building Class Diagrammer

Use Visual Studio or MSBuild to load or build the solution Diagrammer\Diagrammer.sln. The output directory is Diagrammer\bin. This directory contains other files and subdirectories which are not created during the build process but which must be present for Class Diagrammer to execute properly. Please refer to Installed Files for details.

Rebuilding the solution will create an “unsupported developer version” because the assemblies are no longer signed with the expected strong name. There are only two differences to the version in the binary package: the About Class Diagrammer dialog will show a warning, and error reporting by e-mail will be disabled.

You can use the free Visual C# Express IDE instead of Visual Studio 2010. However, the Express edition has several artificial limitations, including a lack of support for “solution items”. These are files that are linked to a solution but not to any particular project, such as this ReadMe file. Express users will have to locate and open these files manually.

The distribution package was created by running MSBuild on the separate build script Publish.proj. This script offers the following targets:

• CleanAll deletes all files and directories created by any previous builds. This is much more thorough than Microsoft’s default “Clean” target.
• Publish invokes “CleanAll”, creates the source package Diagrammer\DiagrammerSource.zip, then a signed release build in subdirectory Diagrammer\bin, and finally the binary package Diagrammer\Diagrammer.zip.

The default target is “Publish”. You need a key container named “Kynosarges” and the applications 7-Zip for this target to succeed.

The HTML Help Project

The directory Diagrammer\Diagrammer.Help contains the sources for the HTML Help file Diagrammer\bin\Diagrammer.Help.chm, wrapped in a Visual Studio project for convenient editing and automatic building along with the Class Diagrammer solution.

The Diagrammer.Help project appears as a C# project but is actually a customized MSBuild script because Visual Studio does not directly support editing or building HTML Help files. Therefore, you shouldn’t edit the properties of this project from within Visual Studio. Load the MSBuild file Diagrammer\Diagrammer.Help\Diagrammer.Help.csproj into an XML text editor to view or change the build process.

Building the HTML Help file requires Microsoft’s HTML Help compiler. This compiler is part of the Microsoft HTML Help Workshop, available as a free download at this MSDN page.

Visual Studio provides no GUI support for editing the HTML Help project file (Diagrammer.Help.hhp) and the table of contents file (Diagrammer.Help.hhc), whereas the HTML Help Workshop allows editing the TOC as a tree structure. However, the Workshop’s HTML editor is far inferior to that of Visual Studio, and you must manually synchronize the list of HTML files between the two environments if you decide to use both.

The HTML Help file is built using the “flat” option which means that all HTML topic files are stored without directory prefixes. This greatly simplifies cross-referencing between topic files stored in different phyiscal folders; however, it also means that most href links won’t work outside of the compiled HTML Help file. Moreover, you must ensure that all HTML topic files have unique names if you decide to add or rename files.

The PDFsharp Libraries

Class Diagrammer includes two libraries from the PDFsharp project. One is the precompiled assembly PdfSharp-WPF.dll, and the other is the source code project PdfSharp.Xps. The latter was never officially completed, and therefore has no precompiled counterpart in the PDFsharp distribution.

While integrating PdfSharp.Xps with Class Diagrammer, I took the opportunity to apply a few bug fixes.

• Corrected image opacity to avoid invisible WPF images, as described in this forum post. (This fix was necessary to render drop shadows on UML elements, by the way.)
• Corrected glyph indexing for Symbol fonts, as described in this forum post.
• Corrected XML comments of some XpsConverter methods, and corrected use of the docIndex parameter in the largest Convert overload.
• Corrected AssemblyInfo.cs to match other PDFsharp libraries.

There is no official documentation for the PdfSharp.Xps library, so I’d like to add a few tips here.

• The simplest way is to call one of the static XpsConverter.Convert methods. These take an XPS file and convert one of its fixed documents (usually the first) into a PDF file.
• Alternatively, you can instantiate XpsConverter and call the RenderPage method to convert individual XPS pages into PDF pages. This also permits stream input for the XPS document. See the method Diagrammer.Core.Output.CreatePdfDocument for an example of this process.
• Check out the directory PDFsharp\dev\XGraphicsLab-WPF in the PDFsharp source distribution for an example of integrating PDFsharp graphics objects with a WPF application. I have not pursued this approach.

There appears to be no way of converting a WPF display object, or an XPS object other than a top-level XPS document. PDFsharp must (re-)create an entire document in its own internal types before conversion can take place, and the only public entry point for a pre-existing WPF/XPS object is the XpsConverter class described above, which requires a complete XPS document. The alternative approach, demonstrated in XGraphicsLab-WPF, is to build your entire document with PDFsharp objects from the ground up, and produce WPF rendering from those objects.

8. Copyright Notice

All files – individual files, multi-file packages, and individual files contained in multi-file packages – that constitute the original distribution of Class Diagrammer are Copyright © 2010–2012 by Christoph Nahr, except where otherwise noted.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

PDFsharp

The included libraries PdfSharp-WPF and PdfSharp.Xps are part of the PDFsharp project, used by permission under the following license:

Copyright © 2005–2009 empira Software GmbH, Cologne (Germany)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

9. Known Issues

Diagram Output

Adobe PDF file output uses the PDFsharp library which converts any Adobe Type 1 fonts into embedded TrueType fonts. Unfortunately, this process is rather inefficient and results in large PDF files. To avoid this, either use TrueType fonts in your diagrams, or output using a virtual Adobe PDF printer that can directly embed Adobe Type 1 fonts.

Class Reference

The current Sandcastle release that was used to build the Class Reference still has a few bugs. You may encounter the following issues:

• A method link without any arguments always links to a single method in a group of overloads, rather than to the overload page itself.
• Documentation for classes that back XAML pages repeats the class name below the summary.

When in doubt, please refer to the source code for the correct documentation.