Class Designer File Format

Article
07/28/2005

In the past few months, we have covered Class Designer features in the upcoming Visual Studio 2005 release. After reading these articles, you have probably noticed that the serialization format for the diagram file (.cd file extension) is in plain XML format. In this article, I will describe the Class Designer file format in detail.

As you know, the diagram file uses the .cd file extension. If you use the Notepad to open this file, you will notice it is in simple plain XML format. As opposed to a proprietary binary format, we decide to serialize the diagram in the XML format. The reason to use the XML format is for its brevity and simplicity. You can easily understand the element/attribute describes the shape rendering behavior in the diagram. Another benefit is for you to easily diff the delta between iterations. Imagine you are working in a collaborative environment and the .cd file is also checked into the source code control system. You can easily diff the diagram file versions and understand the changes between them. If we’re to store the diagram in the binary proprietary format, you will not be able to make sense out of the deltas.

Consider your have the following code snipped in your class library project.

namespace CDFileFormat

{

public delegate void OrderShipped( Order order);

public class Customer

{

public string FirstName;

public string LastName;

public Address Address;

public void OrderGoods(int productID) { }

public IList<Order> currentOrders;

public event OrderShipped OrderShipped;

}

public class Address

{

public string Street;

public int ZipCode;

}

public class Order

{

}

And you create the following diagram

If you open the actual .cd file from the solution explorer using Notepad, you will see the following XML content.

<?xml version="1.0" encoding="utf-8"?>

<FileName>Class1.cs</FileName>

<HashCode>AAAAAGAAAAAAAAAAAAAEAAAAAAAAAAASAAAAAAAAAAg=</HashCode>

</TypeIdentifier>

</ShowAsAssociation>

</ShowAsCollectionAssociation>

</Compartments>

</Class>

<FileName>Class1.cs</FileName>

<HashCode>AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</HashCode>

</TypeIdentifier>

</Class>

<FileName>Class1.cs</FileName>

<HashCode>AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAIAAAAAAAA=</HashCode>

</TypeIdentifier>

</Class>

</Class>

</ClassDiagram>

Here’re the element descriptions:

ClassDiagram: This is the top level element which describes the setting applicable to the whole diagram. Attribute MembersFormat indicates whether we’re displaying class member in name, name_and_type, or full_signature format. In our case, we have value FullSignature which indicates showing member in its full signature form.

Font: Indicates the font used throughout the whole diagram. Attribute Name and size describe the font and size used in the diagram.

Class: For each class (box) shape in the diagram, it has a corresponding element Class in the file. It describes the rendering information for your class. The Name attribute described the fully qualified name for this class. During the file open phase, we’re using this full name to find the type in your project. Attribute Collapsed indicates whether the member compartments are hidden or not. In the above example, member compartments in Address, Order and System.Object classes are hidden from the user. Attribue HideInheritanceLine indicates whether the inheritance line is hidden or not. In our example above, both Address’ and Order’s parent class (System.Object) are present in the diagram. However, notice that the inheritance line is not being drawn because I chose to hide it for both the Address and Order classes.

Position: The shape position in the diagram. The (X, Y) coordinates are relative to the upper left corner of the diagram. The unit is in inches.

TypeIdentifier: This is used to identify the class in your actual project. E.g. Let’s say you have Address class shown in the diagram and you close the diagram. The next day, your co-worker changes the class name to LocalAddress in the project. When you open the diagram again at later time, we cannot find class Address in the project anymore. In this case, we will be using the FileName and HashCode with the heuristic algorithm to determine shape Address is now class LocalAddress is the project. If we cannot determine where the class is, the Address shape will be shown in red color. This is what we referred to as Orphan shape in the diagram. For details on orphan shape, please refer to the previous blog article.

ShowAsAssociation and ShowAsCollectionAssociation: These two elements represent which field/property is being shown as association/collection_association to other class in the diagram. If you look at the example above, you will notice that field Address and currentOrders are rendered as association lines in the diagram.

Members: This element holds a collection of hidden members in the shape. In our example above, field Customer.FirstName is hidden in the diagram.

Compartments: This element contains a collection of member compartments which are hidden in the diagram. In our example above, we see the Events compartment is hidden in class Customer.

As you can see, the XML file format we use is pretty straightforward. By comparing the diagram with the XML text, you can see how the diagramming information is maintained in the XML file. If you have a complex diagram, you might want to open the .cd file using Notepad. You will find interesting information in it.

Have you installed the latest CTP and tried out the Class Designer? As we are wrapping up the current release, this is also a good time for you to provide feedback to us. Do you have any suggestions on what topic we should be covering in the coming months? Any missing features you would like us to address? We would love to hear your feedback...

Regards,

Patrick Tseng

Visual Studio Class Designer Team

Class Designer File Format

Additional resources