This is a follow up article on Using Reflection and WithClass 2000 to View the .NET System.Drawing assembly. Note that both articles have exceedingly long titles, but I couldn't figure out an easy way to present the title to the topic in a few short phrases, hence the verbosity. This article extends the previous articles capabilities. The previous article allowed you to choose any .NET assembly and extract the assembly into a WithClass 2000 UML diagram (without relationships) using reflection and COM Interoperability.
Figure 1 - Persist API extracted from WithClass.
This article allows you to read the classes contained inside of WithClass 2000 into a Word Document using COM Interoperability for Word and COM Interoperability for WithClass and presents your classes in a kind of report. The report lists each class, which is followed, by its list of attribute details and its list of operation details. Our sample only used one class. The class was brought into WithClass by extracting the class from the assembly called Interop.ASPEMAILLib.dll. Some of you may recognize this as the wrapper assembly around the ActiveX Control made by Persits used to send and receive mail. (I once needed this ActiveX control to use on a website to send e-mails for a newsletter.) Below is a UML illustration of the class:
Figure 2 - Persits MailSenderClass imported into the WithClass UML class diagram.
The previous article describes how we used VB with COM interoperability to get the diagram shown in figure 2. Now we want to place the information that is stored in WithClass into a Microsoft Word Document so we can present a report to a manager who doesn't necessarily understand UML. We can do this using the same COM Interoperability techniques that got us this far.
The first step in creating the Word Report in our Window Forms application is to create a Reference to Word and a Reference to WithClass. By choosing Add Reference and clicking the COM tab, we can choose both With_Class and the Microsoft Word COM references in the dialog list. Now Visual Studio will create assembly wrappers around these COM objects for us, and we can use our Microsoft Word object and With_Class object just like any other class instance.
We are going to create a new class called WordWCExtractor, which will perform all of our data extraction from WithClass into Word. We can create new instances of our COM objects in the constructor of this class shown in Listing 1:
Listing 1 - Creating the Instances of Word and WithClass Applications.
Public Sub New()
' create a new Word COM object with our COM wrapper and launch word
WordApp = New Word.ApplicationClass
' create a new WithClass COM Object with our COM wrapper
WCApp = New With_Class.ApplicationClass ' make both applications visible
WCApp.Visible = True
WordApp.Visible = True
End Sub 'New
Now we are ready to extract data from our UML class into Word. Cycling through each class in the UML diagram, pulling out the information contained in the class, and typing it into Word do this. WithClass uses a set of methods to loop through its various collections: Restart, IsLast, and GetNext. Below is the loop structure that loops through each class diagram and then in turn each class to get the data from WithClass. Also Listing 2 shows you how to do some of the Font formatting in Word. Font formatting requires that you toggle the font properties such as Bold or Italic prior to typing. After you've toggled the Font property, any text that you insert into Word by using Selection.TypeText will be styled by the toggled settings. Don't forget to toggle the font style properties again when you are done using them so the Font returns to its original state.
Listing 2 - Looping through classes to extract data into Microsoft Word.
Public Sub WriteAllApisToWord()
Dim fileName As Object = "normal.dot"
Dim [readOnly] As Object = False
Dim isVisible As Object = True
Dim missing As Object = System.Reflection.Missing.Value
Dim newTemplate As Object = False
Dim docType As Object = 0 ' Create a new word document to type into
Dim aDoc As Word.Document = WordApp.Documents.Add(fileName, newTemplate, docType, isVisible)
' Write a Title for the document in bold and centered on the page
WordApp.Selection.ParagraphFormat.Alignment = Word.WdParagraphAlignment.wdAlignParagraphCenter
WordApp.Selection.Font.Bold = CInt(Word.WdConstants.wdToggle)
WordApp.Selection.TypeText("API of Classes Extracted from the WithClass Diagram" + ControlChars.Lf + ControlChars.Lf)
' Toggle centering and bold Off
WordApp.Selection.Font.Bold = CInt(Word.WdConstants.wdToggle)
WordApp.Selection.ParagraphFormat.Alignment = Word.WdParagraphAlignment.wdAlignParagraphLeft
' Loop through each class diagram
WCApp.ActiveDocument.ClassDiagrams.Restart()
While WCApp.ActiveDocument.ClassDiagrams.IsLast() = False
Dim nextClassDiagram As With_Class.ClassDiagram = CType
WCApp.ActiveDocument.ClassDiagrams.GetNext(), With_Class.ClassDiagram)
' Loop through each collection of classes in the diagram
nextClassDiagram.Classes.Restart()
While nextClassDiagram.Classes.IsLast() = False
' Write class name in Bold Italic in Microsoft Word
Dim nextClass As With_Class.Class = nextClassDiagram.Classes.GetNext()WordApp.Selection.Font.Bold = CInt(Word.WdConstants.wdToggle)WordApp.Selection.Font.Italic = CInt(Word.WdConstants.wdToggle)WordApp.Selection.TypeText((nextClass.Name + ControlChars.Lf))WordApp.Selection.Font.Bold = CInt(Word.WdConstants.wdToggle)WordApp.Selection.Font.Italic = CInt(Word.WdConstants.wdToggle)
' Write Attributes and Operations into Word
WriteClassAPIToWord(aDoc, nextClass)
End While
End While
End Sub 'WriteAllApisToWord
We perform similar looping through data of WithClass for both attributes and operations. Below is the method used to extract attribute information into Word. The method simply loops through each attribute in a particular class using again - Restart, IsLast, GetNext in a while loop. The attribute is obtained each time through the loop and this attribute can be used to extract various attribute properties into word such as attribute type, initial value, and visibility (Note that the UML attribute is not to be confused with the attribute intrinsic to the .NET library):
Listing 3 - Writing the class attributes to Microsoft Word.
Public Sub WriteAttribute(ByVal aDoc As Word.Document, ByVal attribute As With_Class.Attribute)
' Type the name of the attribute into Word in Italics
WordApp.Selection.TypeText("Attribute Name:" + ControlChars.Tab + " ")WordApp.Selection.Font.Italic = CInt(Word.WdConstants.wdToggle)WordApp.Selection.TypeText((attribute.Name + ControlChars.Lf))WordApp.Selection.Font.Italic = CInt(Word.WdConstants.wdToggle)
' Type some of the attribute properties. Each property is followed by a return character
WordApp.Selection.TypeText(("Type:" + ControlChars.Tab + " " + attribute.Type + ControlChars.Lf))
WordApp.Selection.TypeText(("Modifier:" + ControlChars.Tab + " " + attribute.Visibility + ControlChars.Lf))
WordApp.Selection.TypeText("Initial")
' Also type some of the Attribute indicators such as constant, static, read-only
If attribute.IsConstant Then
WordApp.Selection.TypeText("constant ")
End If
If attribute.IsStatic Then
WordApp.Selection.TypeText("static ")
End If
If attribute.IsArray Then
WordApp.Selection.TypeText("array ")
End If
If attribute.IsReadOnly Then
WordApp.Selection.TypeText("read-only ")
End If
' Put paragraph breaks after each attribute
WordApp.Selection.TypeParagraph()
WordApp.Selection.TypeParagraph()
End Sub 'WriteAttribute
The routine for extracting information from the operations of the class looks very similar. Below is the routine for extracting operation information from WithClass into Microsoft Word.
Listing 4 - Writing the Operations to Microsoft Word.
Public Sub WriteOperation(ByVal aDoc As Word.Document, ByVal operation As With_Class.Operation)
' Write the Operation name out to Microsoft Word in Italics
WordApp.Selection.TypeText("Operation Name:" + ControlChars.Tab + " ")WordApp.Selection.Font.Italic = CInt(Word.WdConstants.wdToggle)WordApp.Selection.TypeText((operation.Name + ControlChars.Lf))
' Write out a few operation properties such as Return Type and Visibility
WordApp.Selection.Font.Italic = CInt(Word.WdConstants.wdToggle)WordApp.Selection.TypeText(("Return Type:" + ControlChars.Tab + " " + operation.ReturnType + ControlChars.Lf))
WordApp.Selection.TypeText(("Modifier:" + ControlChars.Tab + " " + operation.Visibility + ControlChars.Lf))
WordApp.Selection.TypeText("Additional Properties:" + ControlChars.Tab)
' Write some of the operation special modifiers such as static, abstract, and virtual
If operation.IsStatic Then
WordApp.Selection.TypeText("static ")
End If
If operation.IsVirtual Then
WordApp.Selection.TypeText("virtual ")
End If
If operation.IsAbstract Then
WordApp.Selection.TypeText("abstract ")
End If
' Linebreak
WordApp.Selection.TypeParagraph()
' Loop through each operation parameter and type them all on a line in Microsoft Word
operation.Parameters.Restart()
WordApp.Selection.TypeText("Parameters:" + ControlChars.Tab)
While operation.Parameters.IsLast() = False
Dim p As With_Class.Parameter = operation.Parameters.GetNext()WordApp.Selection.TypeText((p.Name + ":" + p.Type + " "))
End While
' Leave a space for the next operation
WordApp.Selection.TypeParagraph()
WordApp.Selection.TypeParagraph()
End Sub 'WriteOperation
Conclusion.
You may also note that you could probably extract most of this information directly from reflection, but I suspect extracting object-oriented data using WithClass may be a bit less code and less complicated once you understand WithClass's COM structure. These same techniques for creating class reports using WithClass can also be extended to creating reports for State Charts and Interaction Diagrams.
What are great about .NET and VB.NET are COM structures present in Applications such as Word, WithClass, or Excel, look and act like VB.NET classes so you no longer have to distinguish them in your head as being "special" COM objects. The fact that the COM architecture is hidden from you in this case is a good thing.