Article source code: codedom_1.zip

Hopefully over the following weeks these articles will, if nothing else, bring the possibility of generating code with .NET to your attention. More than that though I hope you will actually find a use for The CodeDOM and follow these articles to generate code and complied assemblies. Along the way I'll try to highlight some pitfalls that I have become aware of though being part of a company that has VSIP membership. The code samples will be in VB, the terminology in the most part will be VB orientated too. The generated code will be in both languages though, demonstrating the main use of the CodeDOM. Sorry C# developers, I thought it would make a change!

Requirements

1. Visual Studio.NET Professional, or Enterprise Architect Edition
2. VB.NET or C#.NET Programming Knowledge

CodeDOM Overview

Before reading this document you may want to brush up on some of the concepts and terminology found at the following sites:

System.CodeDom Namespace
CodeDOM Quick Reference

This week is simply an introduction, as I've already said hopefully you will find a use for the CodeDOM which will make any following articles more useful.

Introduction to the Code DOM

To start with I will explain some of the advantages of the CodeDOM and times where I can imagine it being of use. We'll then go on to explaining the first steps into creating simple hieratical objects know as CodeDOM graphs, or CodeDOM trees, that can be taken and built into assemblies or simply used to output source code as shown in the following examples.

The main CodeDOM advantage is language independent code generation.

I've found the CodeDOM useful in projects I been involved in where tools have been created which generate repetitive code, allowing some of the laborious nature of coding an extensible database program to be alleviated. Whenever I create a database program I usually have to create many maintenance screens that have a one-to-one relationship with certain database tables. These are required to allow users after delivery to add maybe another category to certain sections of a program etc. Time is best spent working on the more complicated screens and a tool can be created that "churns out" these similar screens in seconds, and also allows a single point of call when an alteration is required, and therefore re-generation is needed.

Another is the ability to create, compile and execute an assembly at runtime, and in utilising that advantage I have also seen the CodeDOM used quite differently to the first example when used to speed file access. An assembly created on the fly can be populated from maybe an XML configuration file; it is then far faster then to interrogate the assembly for consequent requests.

Lets get started.

Download Test Application

We will gradually build our examples up so that we can generate a class that utilises as many code structure types as I feel necessary to allow you to understand the CodeDOM.

The example I'll be using is a very simplistic bank account class with properties:

• Account Holder
• Account Number
• Current Balance (Read only)

A function that transfers money to another account and returns a success value will be included.

The example will raise an event when the balance goes below zero. The Account class implements an interface called IAccount. The class also has a constructor that allows initiation of the class with an account number and starting balance.

One you've downloaded the sample the first point of interest is the main form frmTest.

From frmTest you'll be able to build up the sample class step-by-step. The buttons on this main form basically call the functions that I will go on to explain in a moment. The return objects from the functions are then passed to the CodeWriter class.

You'll see that I've repeated a lot of function calls on the click events; this is just to ease understanding of the example. I also apologise for the order that members of the class appear; to the best of my knowledge you cannot correct this without having a file output and using the CodeLinePragma object (please contact me if you know any different)?

The example output language defaults to VB but by using the language combo you can change this to C#, showing the beauty of the CodeDOM.

The actual code for IAccount doesn't exist in my example it's simply an imaginary interface that has been referenced for demonstration purposes.

CodeWriter Class

This class will be expanded on through out the course of the articles but for now its purpose is to take CodeDOM objects placed in a hierarchical order of namespace, class, members and return code back to us as a string in our chosen language.

The shared/static class (doesn't require instantiation) contains the public property Language , this allows the choice of output code language. Also there's only one function at the moment call Write that allows a parameter of type CodeNamespace. This parameter contains the whole code hierarchy. Inside the Write function is a select statement that chooses between output language (in this case VB or C#), the code then creates either a VBCodeProvider or a CSharpCodeProvider object. The provider objects then are used to create a Generator. The Providers allow access to code generators and compilers for the relevant language.

The rest of the functionality populates a StringBuilder from a StringWriter stream that is passed to the Generator's GenerateCodeFromNameSpace method, and the contents of the StringBuilder is returned (this being the actual code).

Invoking 'Generate Class' and the CreateClass Function

Next we'll take a look line-by-line at the first function.

Private Sub cmdGenerateClass_Click(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles cmdGenerateClass.Click

Dim NewClass As CodeTypeDeclaration = CreateClass
Dim CodeNamespace As New CodeNamespace("Bank")

    CodeNamespace.Types.Add(NewClass)
    txtcode.Text = CodeWriter.Write(CodeNamespace)

End Sub

The first line of the code runs the function CreateClass. The simple job of CreateClass is to create a class (no surprise there then), by either calling the VB or C# class creation functions. This is the only time in my examples at present that we really need to do something a little different depending on the output language. Next the returned class object is added to a Namespace object, CodeNamespace. The namespace is then passed to the CodeWriter class.

First we will take a look at the function CreateVBClass.

Private Function CreateVBClass() As CodeTypeDeclaration
Dim AccountClass As New CodeTypeDeclaration()

    With AccountClass
        .IsClass = True
        .Name = "BankAccount"
        .Members.Add(New CodeSnippetTypeMember("Implements IAccount"))
        .Comments.Add(New CodeCommentStatement( _
            "This VB Class has been generated by the CodeDOM"))
        .Comments.Add(New CodeCommentStatement(""))
    End With
    Return AccountClass

End Function

I've tried to comment my code as much as I can, trying to make as readable as possible (it's probably the most commenting I've done for a while!), but I've left the comments out of the article code segments, they can be found in the actual download.

Firstly we create a CodeTypeDeclaration object state that we wish it to signify a Class, as this property also allows Enum, Interface or Structure to be chosen. We then name the class accordingly.

Next we add some comments and the base types. We are implementing an interface called IAccount, to do this is a little different in VB than C#. In the C# we wouldn't need to inherit from Object but we need to do this in VB so that when we add our further basetypes the CodeDOM knows that they must be interfaces as VB can only inherit from on base class.

Finally we return the class object to the calling function.

Looking at CreateCSharpClass we can see the subtle differences required by C#.

Private Function CreateCSharpClass() As CodeTypeDeclaration
Dim AccountClass As New CodeTypeDeclaration()

    With AccountClass
        .IsClass = True
        .Name = "BankAccount"
        .BaseTypes.Add(New CodeTypeReference("IAccount"))
        .Comments.Add(New CodeCommentStatement( _
            "This C# Class has been generated by the CodeDOM"))
        .Comments.Add(New CodeCommentStatement(""))

        .Members.Add(New CodeEntryPointMethod())
    End With
    Return AccountClass

End Function

The first of these differences is the possible need for an Entry Point method. This is achieved by creating a CodeMemberMethod object (as shown else where in this article).

The second is the ability to utilise the BaseTypes collection to add a reference to the interface, IAccount, that the class implements.

Other than those two additions the code is identical for either of the two languages. The class creation is the only time that I have had to make a differentiation between the two output languages within the whole example.

Invoking 'With Fields' and the AddFields Function.

To add field members to the class creation, we have just looked at, requires the following code which calls the AddFields function creating a CodeMemeberFieldObject.

NewClass.Members.AddRange(AddFields)

Beneath is the code for the AddFields function

Private Function AddFields() As CodeMemberField()

Dim AccountHolderField As New CodeMemberField()

    With AccountHolderField
        .Name = "mAccountHolder"
        .Type = New CodeTypeReference(GetType(String))
        .Attributes = MemberAttributes.Private
    End With

Dim AccountNumberField As New CodeMemberField()

    With AccountNumberField
        .Name = "mAccountNumber"
        .Type = New CodeTypeReference(GetType(Int32))
    End With

Dim StartBalanceField As New CodeMemberField()

    With StartBalanceField
        .Name = "mStartBalance"
        .Type = New CodeTypeReference(GetType(Decimal))
    End With

Dim CurrentBalance As New CodeMemberField()

    With CurrentBalance
        .Name = "mCurrentBalance"
        .Type = New CodeTypeReference(GetType(Decimal))
    End With

    Return New CodeMemberField() {AccountHolderField, AccountNumberField, _
        StartBalanceField, CurrentBalance}

End Function

The account class has three private fields, mAccountHolderField, mAccountNumberField, mStartBalanceField, mCurrentBalance. The function of these fields is to store the state of there corresponding properties or in the case of the mStartBalanceField it's job is simply to store the initial value passed into the constructor.
For each of the fields a CodeMemberField object is created and properties Name and Type are set, also it is necessary to set the scope of the field using the Attributes property. Finally a CodeMemberField array is passed back to the calling code to be added to our class.

Invoking 'With Properties' and the AddProperties Function.

Firstly we need to add the function call -

NewClass.Members.AddRange(AddProperties)

Then looking at the AddProperties function, we see it's one of the larger functions in this example, it mostly just repeats the same code for each of the three properties so we'll just take a look at defining the AccountHolderProperty property –

    Dim AccountHolderProperty As New CodeMemberProperty()
    Dim AccountInterface As New CodeTypeReference("IAccount")

    With AccountHolderProperty
        .Name = "AccountHolder"
        .Type = New CodeTypeReference(GetType(String))
        .Attributes = MemberAttributes.Public
        .HasGet = True
        .HasSet = True
        .ImplementationTypes.Add(AccountInterface)

        Dim AccountHolderReference As New CodeFieldReferenceExpression()
        AccountHolderReference.FieldName = "mAccountHolder"

        .GetStatements.Add(New CodeMethodReturnStatement( _
            AccountHolderReference))

        Dim AccountHolderAssignment As New CodeAssignStatement()
        AccountHolderAssignment.Left = AccountHolderReference
        AccountHolderAssignment.Right = New CodeArgumentReferenceExpression( _
            "value")
        .SetStatements.Add(AccountHolderAssignment)
        AccountHolderAssignment = Nothing
    End With

To start with we create a CodeMemberProperty called 'AccountHolderProperty' to be returned from this function along with the other properties. Next we create a new instance of a CodeTypeReference, the type we will be referenceing is IAccount as the properties of this class will be implementing members of this interface. As I mentioned earlier I haven't actually gone into defining the structure of IAccount as it's really just for demonstration purposes as it could just confuse matters?

Now we have the property instance, we need to set a few details namely, Type, Attributes (Scope), HasGet (Has a Get accessor), HasSet (has a set accessor), Name and the any types that are implemented (in this case we add the reference to IAccount as mentioned before).

Before we return the Property from this function we need to build the the Get and Set accessors. First the Get, in which we need to create a reference to the private field member mAccountHolder, using the CodeDOM object, CodeFieldReferenceExpression. Now we have a refrence to the field, we need to return it from the function so we use a CodeMethodReturnStatement object, passing the field reference in as the required parameter. The return statement is then taken and added to the Statements collection of the Get accessor. Our generated code will now return the value of the private field, which is exactly what we want.

Now the Set accessor, we'd like to just create a pretty standard set that takes the value assigned to the property and set mAccountHolder to be equal to that value. So to do this we are going to create a CodeAssignStatement, this object has two important properties, they are the left and right hand side of the assignment statement. For the left hand side we can reuse or reference to the private field, mAccountHolder. The right hand side requires us to create a CodeArgumentReferenceExpression to the default 'value' property of a Set accessor (well in VB anyway).

The last step of property creation is to add the return statement to the GetStatement's Statement collection, and the value Assignment statement to the SetStatement's Statement collection.

Invoking 'With Constructor' and the CreateConstructor Function.

    Dim Constructor As New CodeConstructor()
    With Constructor
        .Parameters.Add(New CodeParameterDeclarationExpression(GetType( _
            Int32), "accountNumber"))
        .Parameters.Add(New CodeParameterDeclarationExpression(GetType( _
            Decimal), "startBalance"))

        Dim FieldReference As New CodeFieldReferenceExpression()
        Dim ArgumentRef As New CodeArgumentReferenceExpression()
        
        ArgumentRef.ParameterName = .Parameters(0).Name
        FieldReference.FieldName = "mAccountNumber"
        Dim AccountNumberAssign As New CodeAssignStatement(FieldReference, _
            ArgumentRef)
        .Statements.Add(AccountNumberAssign)

        FieldReference = New CodeFieldReferenceExpression()
        ArgumentRef = New CodeArgumentReferenceExpression()
        ArgumentRef.ParameterName = .Parameters(1).Name
        FieldReference.FieldName = "mStartBalance"
        Dim StartBalanceAssign As New CodeAssignStatement(FieldReference, _
            ArgumentRef)

        FieldReference = Nothing
        ArgumentRef = Nothing
        .Statements.Add(StartBalanceAssign)
        StartBalanceAssign = Nothing
    End With
    Return Constructor

In order to create a Constructor we need the aptly named CodeDOM CodeConstructor object. The statements within the Constructors will take the two defined parameters and assign them to their corresponding private field members. In order to understand the code I will just take you through one of the assignments.

To start with then we need to define the parameters, we could have used AddRange but I've added them one at a time for simplicity. The parameters are accountNumber (Int32) and startBalance (Decimal ).

We have created a CodeAssignStatement before but we'll go through it again. The first step in this case is to create a CodeArgumentReferenceExpression (ArgumentRef) that refers to the constructors' parameter accountNumber. Next using a CodeFieldReferenceExpression object we need to make reference to the field mAccountNumber. Using a CodeAssignStatement we assign these two objects to each other and then add the assignment to the constructors' Statements collection. This process is then repeated for each parameter. The Constructor is then returned to the calling code and passed to the CodeWriter class.

Invoking 'With Function' and the AddFunction Function

At this stage we are not including any event demonstration code, notice the overloaded version of the AddFunction, so I've removed that section for now from the following code:

Private Function AddFunction( _
    ByVal includeEvent As Boolean) As CodeMemberMethod

Dim FunctionMember As New CodeMemberMethod()
    
    With FunctionMember
        .Name = "TransferFunds"
        .Statements.Add(New CodeCommentStatement( _
            "Put the body of the function here that commits the transfer."))
        .Attributes = MemberAttributes.Public

        .Statements.Add(New CodeMethodReturnStatement( _
            New CodeSnippetExpression("true")))

        .ReturnType = New CodeTypeReference(GetType(Boolean))
    End With

    Return FunctionMember

End Function

Once a CodeMemberMethod has been created, (a CodeMemberMethod defines both a sub or a function, the differentiation is made by the ReturnType property), we need to set a few basic properties such as Name and Attributes (scope) and the ReturnType (Boolean).

We also have two Statements to add to the function, the first is just a comment using the CodeCommentStatement object, that states any futher function code should go here, in this case the code would action the transfer of money, if we were going into that much detail. The second is the return statement, not surprisingly using the CodeDOM CodeMethodReturnStatement object, and a CodeSnippetExpression (which allows us to add any text we wish) containing the return value of 'True'. The CodeMemberMethod is then returned from this function.

Invoking 'With Event and the AddEvent Function.

There are three parts to adding the demonstration of events. Invoking the OnOverDrawn sub which raises the Event OnOverDrawn (the addition to the previous function that calls the OnOverDrawn sub). Having a protected sub that raises the event means that if the class is inherited from a different action can be taken and also any logic required around raising the event can be placed within the sub which means there is only one section of code to maintain/change and all the calling code will benefit from the change. Finally the definition of the OverDrawn Event.

If we look at these three steps in a sensible order we should start with the definition of the Event:

Private Function AddEvent() As CodeMemberEvent

Dim OverDrawnEvent As New CodeMemberEvent()

    With OverDrawnEvent
        .Name = "OverDrawn"
        .Attributes = MemberAttributes.Public
        .Type = New CodeTypeReference(GetType(EventHandler))
    End With
    Return OverDrawnEvent

End Function

This time we use a CodeMemberEvent object and set the name and Attributes properties. The type of the Event will be an EventHandler, this is set by creating a CodeTypeReference object. Then we just return the CodeMemberEvent back to the calling code.

Lets look at the definition of the OnOverDrawn sub:

Private Function AddOnOverDrawnSub() As CodeMemberMethod

Dim OnOverDrawnSub As New CodeMemberMethod()

    With OnOverDrawnSub
        .Attributes = MemberAttributes.FamilyOrAssembly
        .Name = "OnOverDrawn"
        .Parameters.Add(New CodeParameterDeclarationExpression(GetType( _
            EventArgs), "e"))

        Dim OverDrawnEventRef As New CodeEventReferenceExpression( _
            New CodeThisReferenceExpression(), "OverDrawn")
        Dim OverDrawnEventInvoke As New CodeDelegateInvokeExpression()
        With OverDrawnEventInvoke
            .TargetObject = OverDrawnEventRef
            .Parameters.Add(New CodeThisReferenceExpression())
            .Parameters.Add(New CodeVariableReferenceExpression("e"))
        End With
        .Statements.Add(OverDrawnEventInvoke)

        OverDrawnEventInvoke = Nothing
        OverDrawnEventRef = Nothing
    End With
    Return OnOverDrawnSub

End Function

As with AddFunction we have created a CodeMemberMethod but this time with no return type and the Attributes property is set to FamilyOrAssembly meaning it is protected. This method accepts a parameter called e and is of type EventArgs as you can see this is achieved by the use of a CodeParameterDeclarationExpression object. We then need to reference the Event OverDrawn using a CodeEventReferenceExpression. This Event reference is added to the Target Property of the CodeDelegateInvokeExpression object, also parameters of Me and e are added to the object. This Delegate invocation is added to the methods Statement collection and the Sub is passed back to the calling code.

Here is the extra section of AddFunction that is added by the overloaded AddFunction with a parameter value of True -

Dim CodeConditionStatement As New CodeConditionStatement()

    With CodeConditionStatement
        .Condition = New CodeBinaryOperatorExpression( _
                    New CodeFieldReferenceExpression( _
                    New CodeThisReferenceExpression(), "mCurrentBalance"), _
                        CodeBinaryOperatorType.LessThan, _
                        New CodePrimitiveExpression(0))

        Dim OnOverDrawnMethodInvoke As New CodeMethodInvokeExpression()

        OnOverDrawnMethodInvoke.Method = New CodeMethodReferenceExpression( _
            New CodeThisReferenceExpression(), "OnOverDrawn")

        OnOverDrawnMethodInvoke.Parameters.Add(New CodeSnippetExpression( _
            "System.EventArgs.Empty"))

        .TrueStatements.Add(OnOverDrawnMethodInvoke)
    End With
    .Statements.Add(CodeConditionStatement)

We need to create a CodeConditionStatement that will decide if the OnOverDrawn sub should be called. The condition needs to contain a CodeBinaryOperatorExpression that checks to see if the field reference to mCurrentBalance is less than zero (I've used CodePrimitiveExpression to include the integer value of '0' in the comparison).

Next we need to create the Statement to be added to the True part of the comparison (we have no need to define a False statement). This will mean building a CodeMethodInvokeExpression object. The Method property of the CodeMethodInvokeExpression will reference the method OnOverDrawn. Also we need to pass the required parameter into the method, we'll do this with the following line of code -

    CodeSnippetExpression("System.EventArgs.Empty"))

The condition is now complete and is added to the functions Statement collection.

The explanation of the Event calling code means that all sections of the test application have now been covered.

I hope that this small demonstration helps illustrate how to utilise much of the functionality included in the CodeDOM to achieve the code structures that you will undoubtedly require in any CodeDOM projects you embark on yourselves.

To conclude this section of building CodeDOM graphs it has to be said that there is a lot of work required to build event the simplest of elements such as an event of property. But in order to achieve a totally language independent representation of the code you wish to output it is obvious that this is something we have to put up with.

The examples, I feel so far, haven't been complicated but have covered a lot of ground.

Next we'll go one to look a list of the limitations I have experienced so far within the CodeDOM.

Limitations

Below I have listed (in no particular order), limitations that I have encounted in version 1 of the .NET Framework (and in some cases 1.1).Where ever posible I have tied to add workarounds.

Also:

• Unsafe modifier not supported.
• ReadOnly modifier not supported.
• Volatile modifier not supported.
• Add and Remove accessors for Event not supported.

Useful links

An example of taking C# code and building a CodeDOM tree.
Microsoft .NET CodeDom Technology - Part 1
Microsoft .NET CodeDom Technology - Part 2
If you do not need source code, you can use the classes in System.Reflection.Emit This namespace is designed to be used by script engines and compilers to generate MSIL code or complete assemblies on disk.

Next Time, Part 2: Introduction to the Code Model