Writing Code Generators with the CodeDOM - Part 2

The first part of this article introduced the macro steps involved in creating a code generator with Microsoft's .NET CodeDOM. This powerful part of the framework is already used to generate a strongly typed DataSet from an XML Schema (integrated into the IDE and found in the XSD.exe utility), create client side proxies for XML Web Services (again, integrated into the IDE and found in the WSDL.exe utility), and several other places inside the framework.

In this second half of the article, we'll create a code generator that generates all of the code for a Windows Form. While not earth shaking, it could very well be the basis for a Windows application generator or a clever wizard and will give you all of the foundation you need to start writing your own code generators. (If you'd like to review the macro steps, I encourage you to read last month's first-part article, having the same title.)

Each part of this article approximately covers one of the aforementioned macro steps. As a result, the code is chopped up a bit. To help you successfully build the sample program, a complete, single listing is provided at the end of this article. You should be able to cut and paste the source into a VB.NET module and compile the test unit. To focus our explanation, I will chunk out the individual pieces in the appropriate explanatory section, and then, as mentioned, consolidate the entire listing at the end without comment.

Creating a CodeCompileUnit

It helps me to form analogies or equate what I need to learn without what I already know. (Probably pretty much how everyone learns.) The first thing we need to do after we have created our project and add the CodeDOM namespaces—System.CodeDOM and Syste.CodeDOM.Compiler—we need a CodeCompileUnit. The CodeCompileUnit represents the encapsulating class, analogous to a module. The verbiage in the help file refers to the process of generating code as creating a code graph. In the code graph of a code generator, the CodeCompileUnit is the root of the graph. In our example, we declare and create the CodeCompileUnit with a statement such as the following:

Dim Unit As CodeCompileUnit = New CodeCompileUnit()

Adding Namespaces

Namespaces in VB.NET are generally concealed from us in the project properties. They are there, and we need to manually incorporate these into our code generator. In the scheme of things, the namespace is the enclosing entity inside of a module, and we need to create that piece next. In conjunction with defining a namespace, we add our import statements at this point, too. The whole parcel is added to the enclosing CodeCompileUnit.

We know from experience—or by creating a Windows application from a template—that the namespaces System, System.Drawing, System.Windows.Forms, System.Xml, and System.Data are useful in Windows applications. Collectively, with the namespace we want to add the import statements we'll likely need in a Windows application. The namespace CodeDOM code for our example is:

Dim Namespaces As CodeNamespace = New CodeNamespace( _
                                      "codeguru.com")
Namespaces.Imports.Add( New CodeNamespaceImport("System"))
Namespaces.Imports.Add( New CodeNamespaceImport("System.Drawing"))
Namespaces.Imports.Add( New CodeNamespaceImport("System. _
                        Windows.Forms"))
Namespaces.Imports.Add( New CodeNamespaceImport("System.Xml"))
Namespaces.Imports.Add( New CodeNamespaceImport("System.Data"))
Unit.Namespaces.Add(Namespaces)

Adding Types

The next logical step in writing object-oriented code is to define our types. This step carries over into our code generator, and we define a type using the CodeTypeDeclaration. The next group of code defines our Form class and adds that class to our codeguru.com namespace.

Dim MyType As CodeTypeDeclaration = New CodeTypeDeclaration( _
                                        "Form1")
MyType.IsClass = True
MyType.TypeAttributes = Reflection.TypeAttributes.Public
MyType.BaseTypes.Add("System.Windows.Forms.Form")
Namespaces.Types.Add(MyType)

The first statement will ultimately perform substitution and add the lines of code "Class Form1" and "End Class". One facet of the CodeDOM is that if we use the CSharpCodeProvider (instead of the VBCodeProvider), the same statement will generate "class Form1{" and "}", the C# version of a class deifinition.

The balance of the statements indicate that the type is a class, as opposed to a structure or enumeration, that the class is Public, it inherits from System.Windows.Forms.Form, and adds the type to our namespace. These are all steps that we would perform if we were writing code in the editor. The code substitution performed by this part of our code generator, using a VBCodeProvider, will produce code that looks like this:

Public Class Form1
  Inherits System.Windows.Forms.Form

End Class

Adding Members

Consistent with our "what would I do next if I were writing the code in the IDE?" theme is to add members to our class. Members means events, fields, properties, enumerations, delegates, nested classes, nested structures, and methods. A Windows Form class uses a constructor, a Dispose method, an IContainer field, and InitializeComponent method and their incumbent lines of code. We'll examine each of these member types and their coincidental CodeDOM code next.

Defining the Constructor

The Sub New method—or constructor—in a Windows Form is a public method. All it does in a Form—by default, unless you add code—is to call the InitializeComponent method. We'll follow the framework's lead and generate the lines of code. The next part of our generator takes care of this part of the Form's initialization for us.

Dim Constructor As CodeConstructor = New CodeConstructor()
  Constructor.Attributes = MemberAttributes.Public
  Constructor.Statements.Add( _
    New CodeMethodInvokeExpression( _
      New CodeThisReferenceExpression(), "InitializeComponent", _
      New CodeExpression() {}))

MyType.Members.Add(Constructor)

The first statement creates an instance of a CodeConstructor. In VB.NET, this will generate a Sub New; and in C#, it will generate a constructor with the same name as the class. The next statement establishes our constructor as a public constructor. (We might use a non-public constructor for a Singleton class.) The next monolithic statement is indicative of lines-of-code CodeDOM statements in general; they tend to be verbose. The first object represents a reference to our InitializeComponent method. The next, nested objects represent the pointer-to-self Me, and a call to InitializeComponent with no parameters. The last statement adds the constructor, represented by the CodeConstructor object, to our type. Collectively this code generates:

Public Sub New()
  MyBase.New()
  InitializeComponent()
End Sub

We didn't explicitly write any code to call the parent class' constructor. This was added by the CodeDOM itself.

Defining the Dispose Method

The basic form of the Dispose method in a Form is to call Dispose on the container holding all of our components. Knowing the implementation of a reasonable Dispose method from a Form template, we can implement the Dispose generate code as follows:

1:          Dim DisposeMethod As CodeMemberMethod = _
2:            New CodeMemberMethod()
3:
4:          DisposeMethod.Name = "Dispose"
5:          DisposeMethod.Attributes = _
6:            MemberAttributes.Family Or MemberAttributes. _
                                         Overloaded Or _
7:            MemberAttributes.Override
8:
9:          DisposeMethod.Parameters.Add( _
10:           New CodeParameterDeclarationExpression( _
11:             GetType(Boolean), "disposing"))
12:
13:         Dim Statement As CodeConditionStatement = _
14:           New CodeConditionStatement()
15:         Statement.Condition = _
16:           New CodeArgumentReferenceExpression("disposing")
17:
18:         Dim TrueStatement As CodeConditionStatement = _
19:           New CodeConditionStatement()
20:         TrueStatement.Condition = _
21:           New CodeBinaryOperatorExpression( _
22:             New CodeArgumentReferenceExpression( _
                    "components"), _
23:             CodeBinaryOperatorType.IdentityInequality, _
24:             New CodePrimitiveExpression(Nothing))
25:
26:
27:         TrueStatement.TrueStatements.Add( _
28:           New CodeMethodInvokeExpression( _
29:             New CodeFieldReferenceExpression(Nothing, _
                    "components"), _
30:               "Dispose", New CodeExpression() {}))
31:
32:         Statement.TrueStatements.Add(TrueStatement)
33:
34:         DisposeMethod.Statements.Add(Statement)
35:
36:         DisposeMethod.Statements.Add( _
37:           New CodeMethodInvokeExpression( _
38:               New CodeBaseReferenceExpression(), _
39:               "Dispose", New _
                      CodeArgumentReferenceExpression() _
40:               {New CodeArgumentReferenceExpression( _
41:                 "disposing")}))
42:
43:         MyType.Members.Add(DisposeMethod)

(Line numbers were added for reference due to the length of the listing.) When generated, a Dispose method is only about six lines of code. Clearly, the code to generate this method is much longer. From experience, it seems to take about ten lines of code for every one line of generated code.

When rendered, Dispose is comprised of a nested If-conditional statement and a call to the base Dispose method. Lines 1 through 7 define the Dispose method body. The settings used for the CodeMemberMethod indicate that Dispose is a Protected (Family), overloaded and overridden method. Lines 9 through 11 indicate that Dispose takes one Boolean argument name disposing, thus ending the method signature. The remaining statements are lines dancing between the bounds of the Dispose method.

We use the CodeConditionStatement on lines 13 through 16 to create a conditional statement to determine if we are disposing of the Form. Lines 18 through 24 perform the nested test to ensure that the components field has been assigned. Ultimately, such a test has a True and False part. By adding an expression to the TrueStatements collection, we are codifying the generative part of the If half of the statement. Our If-half invokes a call to components.Dispose, passing no arguments as represented by the empty array of CodeExpression objects on line 30. We finish the Dispose method by adding the nested test and the components.Dispose call to our conditional statement (line 32), adding code to our Dispose method (line 24), adding a call to our base Dispose method (lines 36 through 41), and adding the Dispose method to our class (line 43).

Adding the IContainer Reference

The components field will be an instance of a class that implements IContainer. Field declarations are relatively simple instances of the CodeMemberField. Here is the statement that declares the components field; the initialization of the container occurs in the InitializeComponent method in the next section.

MyType.Members.Add( _
  New CodeMemberField("System.ComponentModel.IContainer", _
      "components"))

Defining the InitializeComponent Method

A blank form defines the InitializeComponent method by using the DebuggerStepThrough attribute and creating an instance of an IContainer. (If you were creating a code generator based on this form, you would want to keep a reference to the InitializeComponent method, as this is where you would add code that instantiated nested controls such as Labels and TextBoxes.) As with the Dispose method, line numbers were added for reference only due to the length of the fragment.

1:  Dim InitializeMethod As CodeMemberMethod = _
2:    New CodeMemberMethod()
3:
4:  InitializeMethod.name = "InitializeComponent"
5:  InitializeMethod.Attributes = MemberAttributes.Private
6:
7:  InitializeMethod.CustomAttributes.Add( _
8:    New CodeAttributeDeclaration( _
9:      "System.Diagnostics.DebuggerStepThrough"))
10:
11: InitializeMethod.Statements.Add( _
12:   New CodeAssignStatement( _
13:     New CodeFieldReferenceExpression( _
14:       New CodeThisReferenceExpression(), "components"), _
15:       New CodeObjectCreateExpression( _
16:         New CodeTypeReference( _
17:           GetType(System.ComponentModel.Container)), _
18:             New CodeExpression() {})))
19:
20: MyType.Members.Add(InitializeMethod)

Lines 1 and 2 declare a CodeMemberMethod. This class will always represent a method. Lines 4 and 5 name the method and adorn it with the Private access modifier. Lines 7 through 8 attach the System.Diagnostics.DebuggerStepThrough attribute, as an instance of the CodeAttributeDeclaration class, by adding the instance to CodeMemberMethod's CustomAttributes collection. Lines 11 through 18 will generate a code that creates a new instance of System.ComponentModel.Container and assigns that instance to the components field. Let's take a second to decompose all of the inline code.

Line 11 indicates that we are adding a statement to the CodeMemberMethod's Statements collection. Line 12 creates a new instance of an assignment statement. Line 13 indicates that we will be referring to a field in this class. Line 14 completes the CodeFieldReferenceExpression with Me and components, yielding the code Me.components on the left-hand-side of the assignment. Line 15 begins the right-hand-side of the assignment, indicating that we will be constructing an object. Line 16 indicates a type reference (think, class name) and will generate a constructor call by name to the Container class, passing no arguments. Finally we add the CodeMemberMethod to the graph on line 20.

Picking a Provider and Generating Code

We are just about finished at this point. We need to pick a provider. The separation of responsibilities in the CodeDOM means that almost anyone should be able to implement a provider that reads the CodeDOM graph and substitutes it for a specific language. I have used the C# and VB providers, and there are others being implemented or that already exist.

If we want to generate VB.NET source code, we need a provider, a code generator, and a stream. The generator writes its output to a stream, offering more flexibility than if it only generated code to a file. For example, a string stream would permit the code to be generated directly a string and inserted into the IDE. Here are the statements that write source code from our graph.

  Dim Stream As StreamWriter = New StreamWriter("out.vb")
  Try
    Dim Generator As ICodeGenerator = _
      (New VBCodeProvider()).CreateGenerator

    Generator.GenerateCodeFromCompileUnit( _
      Unit, Stream, Nothing)
  Finally
    Stream.Close()
  End Try

The first statement creates an instance of a StreamWriter. The StreamWriter will send our generated code to a file. In the example, the file will be named out.vb. The next statement (after the beginning of the Try..Finally block) declares an instance of an IGenerator, creates a VBCodeProvider, and asks that provider for its code generator. If we needed to, we could keep an instance of the VBCodeProvider by assigning it to a temporary variable defined as an ICodeProvider. The next statement generates the source code, and we finish up by closing the stream. The generated source code is shown in Listing 1.

Listing 1: The code created by our code generator.

'----------------------------------------------------------------
' <autogenerated>
'     This code was generated by a tool.
'     Runtime Version: 1.0.3705.0
'
'     Changes to this file may cause incorrect behavior and
'     will be lost if the code is regenerated.
' </autogenerated>
'----------------------------------------------------------------

Option Strict Off
Option Explicit On

Imports System
Imports System.Data
Imports System.Drawing
Imports System.Windows.Forms
Imports System.Xml

Namespace codeguru.com

    Public Class Form1
        Inherits System.Windows.Forms.Form

        Private components As System.ComponentModel.IContainer

        Public Sub New()
            MyBase.New
            Me.InitializeComponent
        End Sub

        Protected Overloads Overrides Sub Dispose(ByVal _
                                      disposing As Boolean)
            If disposing Then
                If (Not (components) Is Nothing) Then
                    components.Dispose
                End If
            End If
            MyBase.Dispose(disposing)
        End Sub

        <System.Diagnostics.DebuggerStepThrough()> _
        Private Sub InitializeComponent()
            Me.components = New System.ComponentModel.Container
        End Sub
    End Class
End Namespace

At this point, you might wonder about the .resx file that is associated with forms. As it turns out, if you open this file in the IDE, Visual Studio .NET will generate the resource file for the form. We don't need to explicitly define the .resx file.

Compiling

What remains to do is compile our source code and ensure that our generator works correctly. What I specifically like about code generators is that, once perfected, they generate perfect code every single time. No syntax errors. No typographic errors, and no typing. To compile our code, we need to create an ICodeCompiler, specify some compiler options, compile, and then check for errors. Here is the rest of the code generator.

1:  ' Create the compiler
2:  Dim Compiler As ICodeCompiler = _
3:    (New VBCodeProvider()).CreateCompiler()
4:
5:  ' Create the compiler options, include referenced assemblies
6:  Dim Options As CompilerParameters = _
7:    New CompilerParameters()
8:  Options.GenerateExecutable = True
9:  Options.OutputAssembly = "test.exe"
10: Options.CompilerOptions = "/target:winexe"
11: Options.MainClass = "codeguru.com.Form1"
12: Options.ReferencedAssemblies.AddRange( _
13:   New String() {"System.dll", "System.Data.dll", _
14:     "System.Drawing.dll", "System.Windows.Forms.dll", _
15:     "System.XML.dll"})
16:
17:
18: ' Build and look for compiler errors
19: Dim Result As CompilerResults = _
20:   Compiler.CompileAssemblyFromFile(Options, "out.vb")
21:
22: Dim E As CompilerError
23: If (Result.Errors.Count > 0) Then
24:   For Each E In Result.Errors
25:     Console.WriteLine(E.ErrorText)
26:   Next
27: Else
28:   Console.WriteLine("compiled successfully")
29: End If
30: Console.WriteLine("press enter to continue")
31: Console.ReadLine()

Lines 2 and 3 create a VBCodeProvider and request that provider's compiler. Lines 6 through 15 define the CompilerParameters. Line 8 indicates that we want to create an executable, as opposed to a DLL. Line 9 names our output .exe file. Line 10—CompilerOptions—permits us to express additional compiler parameters not represented by a CompilerParameters property. Without line 10, our code would generate a console application that happened to display a Windows Form. Line 11 defines the entry point for our executable as the Form1 code we generated. Finally, lines 12 through 15 include the assemblies we need to reference. Because these assemblies are in the Global Assembly Cache, we can reference them without file path information. Unregistered assemblies not in the local directory probably need path information.

Lines 19 and 20 compile our source code and assign the CompilerResults to the local Result variable. If there are errors—line 23—the code enumerates each error and writes it to the console. That's it. We're finished. If everything went correctly, there should be a test.exe file in the same directory as the code generator, and running that executable should display a blank form, as shown in Figure 1.

Figure 1: Our wholly generated form.

Reference: Complete Listing for the Form Generator

Imports System.CodeDom
Imports System.CodeDom.Compiler
Imports System.IO

Module Module1

    Sub Main()
      ' Create the Unit
      Dim Unit As CodeCompileUnit = New CodeCompileUnit()

      ' Define a namespace and add Imports statements
      Dim Namespaces As CodeNamespace = _
        New CodeNamespace("codeguru.com")
      Namespaces.Imports.Add( _
        New CodeNamespaceImport("System"))
      Namespaces.Imports.Add( _
        New CodeNamespaceImport("System.Drawing"))
      Namespaces.Imports.Add( _
        New CodeNamespaceImport("System.Windows.Forms"))
      Namespaces.Imports.Add( _
        New CodeNamespaceImport("System.Xml"))
      Namespaces.Imports.Add( _
        New CodeNamespaceImport("System.Data"))

      Unit.Namespaces.Add(Namespaces)

      ' Declare the type including base type
      Dim MyType As CodeTypeDeclaration = _
        New CodeTypeDeclaration("Form1")
      MyType.IsClass = True
      MyType.TypeAttributes = Reflection.TypeAttributes.Public
      MyType.BaseTypes.Add("System.Windows.Forms.Form")

      Namespaces.Types.Add(MyType)

      ' Create the constructor/Sub New and add code
      Dim Constructor As CodeConstructor = _
        New CodeConstructor()

      Constructor.Attributes = MemberAttributes.Public
      Constructor.Statements.Add( _
        New CodeMethodInvokeExpression( _
          New CodeThisReferenceExpression(), _
              "InitializeComponent", New CodeExpression() {}))

        MyType.Members.Add(Constructor)

        ' Declare component container
        MyType.Members.Add( _
          New CodeMemberField("System.ComponentModel. _
              IContainer", "components"))

        ' Implement the Dispose method
        Dim DisposeMethod As CodeMemberMethod = _
          New CodeMemberMethod()

        DisposeMethod.Name = "Dispose"
        DisposeMethod.Attributes = _
          MemberAttributes.Family Or MemberAttributes.Overloaded _
          Or MemberAttributes.Override

        DisposeMethod.Parameters.Add( _
          New CodeParameterDeclarationExpression( _
            GetType(Boolean), "disposing"))

        Dim Statement As CodeConditionStatement = _
          New CodeConditionStatement()
        Statement.Condition = _
          New CodeArgumentReferenceExpression("disposing")

        Dim TrueStatement As CodeConditionStatement = _
          New CodeConditionStatement()
        TrueStatement.Condition = _
          New CodeBinaryOperatorExpression( _
            New CodeArgumentReferenceExpression("components"), _
            CodeBinaryOperatorType.IdentityInequality, _
            New CodePrimitiveExpression(Nothing))


        TrueStatement.TrueStatements.Add( _
          New CodeMethodInvokeExpression( _
            New CodeFieldReferenceExpression(Nothing, _
                "components"), "Dispose", New _
                                          CodeExpression() {}))

        Statement.TrueStatements.Add(TrueStatement)

        DisposeMethod.Statements.Add(Statement)

        DisposeMethod.Statements.Add( _
          New CodeMethodInvokeExpression( _
              New CodeBaseReferenceExpression(), _
              "Dispose", New CodeArgumentReferenceExpression() _
              {New CodeArgumentReferenceExpression( _
                "disposing")}))

        MyType.Members.Add(DisposeMethod)


      ' InitializeComponent
      Dim InitializeMethod As CodeMemberMethod = _
        New CodeMemberMethod()

      InitializeMethod.name = "InitializeComponent"
      InitializeMethod.Attributes = MemberAttributes.Private

      InitializeMethod.CustomAttributes.Add( _
        New CodeAttributeDeclaration( _
          "System.Diagnostics.DebuggerStepThrough"))

      InitializeMethod.Statements.Add( _
        New CodeAssignStatement( _
          New CodeFieldReferenceExpression( _
            New CodeThisReferenceExpression(), "components"), _
              New CodeObjectCreateExpression( _
                New CodeTypeReference( _
                  GetType(System.ComponentModel.Container)), _
                  New CodeExpression() {})))

      MyType.Members.Add(InitializeMethod)

      ' Write the source code
      Dim Stream As StreamWriter = New StreamWriter("out.vb")
      Try
        Dim Generator As ICodeGenerator = _
          (New VBCodeProvider()).CreateGenerator

        Generator.GenerateCodeFromCompileUnit( _
          Unit, Stream, Nothing)
      Finally
        Stream.Close()
      End Try

      ' Create the compiler
      Dim Compiler As ICodeCompiler = _
        (New VBCodeProvider()).CreateCompiler()

      ' Create the compiler options, include referenced
      ' assemblies
      Dim Options As CompilerParameters = _
        New CompilerParameters()
      Options.GenerateExecutable = True
      Options.OutputAssembly = "test.exe"
      Options.CompilerOptions = "/target:winexe"
      Options.MainClass = "codeguru.com.Form1"
      Options.ReferencedAssemblies.AddRange( _
        New String() {"System.dll", "System.Data.dll", _
      "System.Drawing.dll", "System.Windows.Forms.dll", _
      "System.XML.dll"})


      ' Build and look for compiler errors
      Dim Result As CompilerResults = _
        Compiler.CompileAssemblyFromFile(Options, "out.vb")

      Dim E As CompilerError
      If (Result.Errors.Count > 0) Then
        For Each E In Result.Errors
          Console.WriteLine(E.ErrorText)
        Next
      Else
        Console.WriteLine("compiled successfully")
      End If
      Console.WriteLine("press enter to continue")
      Console.ReadLine()

    End Sub

End Module

Summary

When some people see the CodeDOM, they say, "Oh, that's easy; it's just code substitution." Yes, at its essence it is substitution, and poetry and songs are just words and notes. Yet, the important part is that it is the orchestration of phrases and notes that create vocabulary that enables humans to be more expressive, and it is the captured classes in the CodeDOM that will likely be an invaluable step that enables programmers to create more expressive software. The CodeDOM is a stepping stone that enhances expressivity just as music and poetry enhance their respective art forms.

The power of code generators will come as we create higher and higher level constructs. The CodeDOM seems to be experiencing a period of infancy. However, as bigger, more complex aggregates evolve, we will be able to generate increasingly complex chunks of code. This in no way should diminish the number of programmers we will need; what it will do is provide programmers with a greater vocabulary to draw from and enable us to build more advanced systems while eliminating tedious, automatable chores.

About the Author

Paul Kimmel is a freelance writer for Developer.com and CodeGuru.com. Look for his upcoming book, Visual Basic .NET Power Coding, from Addison-Wesley. Paul Kimmel is available to help design and build your .NET solutions and can be contacted at pkimmel@softconcepts.com.

# # #



Comments

  • There are no comments yet. Be the first to comment!

Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Live Event Date: December 11, 2014 @ 1:00 p.m. ET / 10:00 a.m. PT Market pressures to move more quickly and develop innovative applications are forcing organizations to rethink how they develop and release applications. The combination of public clouds and physical back-end infrastructures are a means to get applications out faster. However, these hybrid solutions complicate DevOps adoption, with application delivery pipelines that span across complex hybrid cloud and non-cloud environments. Check out this …

  • On-demand Event Event Date: October 29, 2014 It's well understood how critical version control is for code. However, its importance to DevOps isn't always recognized. The 2014 DevOps Survey of Practice shows that one of the key predictors of DevOps success is putting all production environment artifacts into version control. In this webcast, Gene Kim discusses these survey findings and shares woeful tales of artifact management gone wrong! Gene also shares examples of how high-performing DevOps …

Most Popular Programming Stories

More for Developers

RSS Feeds