Outputting Code - Extending the Harness

(Page 4 of 19 )

This book is the start of your code generation adventures, not the sum total of them. There’s no way I can predict what you’ll need to do; there isn’t even a way for you to predict what you’ll need to do. The provided directives do everything I thought of; I trust your creativity, so I designed the harness with extensibility in mind. You can incorporate new templates using all the current harness capabilities (generating output from templates, collecting metadata, running processes, running SQL scripts, and so on) without extending the harness. If you need more capabilities, you can extend it. I provided this feature so you could incorporate every step of code generation as part of your one-click code process, even if I didn’t provide the directive. To create new directives, you’ll need to do the following:

1. Design the XML for the directive (what attributes does it need?)

2. Create a .NET assembly that performs the task in a static (Shared) method

3. Specify the assembly, type, and method name in the XSD along with any other information you defined

4. Add this directive’s definition to the XSD

5. Create a new entry in your XML harness script for the new item

That’s it. If your method doesn’t run, you may need to look up (in the .NET Help) how to attach a debugger to an executing process to debug your code. The problem will probably be with the parameters passed. In designing the schema for your extension, you can use any existing child element—all of which are defined via XSD-named complex types. (Appendix A further discusses named complex types and simple types and how to restrict entries to a list.) You can also create new named complex types. Combo box entries are simple types restricted to a list. You can add new items to existing lists or create new lists.

CAUTION: Changes to your XSD won’t affect your editing in Visual Studio unless the updated XSD is in the project directory or in the magic directory [Program Files]\ Microsoft Visual Studio .NET 2003\ Common7\Packages\schemas\xml and you restart Visual Studio. Appendix A has more information about doing this.

Dynamic Techniques

Does it seem odd that a key tool in a book on code generation doesn’t use code generation but instead uses its wild and crazy sister, data-driven dynamic techniques? Code generation just wasn’t the easiest way to build the code generation harness. A few reasons why dynamic techniques are a better fit for this tool are as follows:

• The application is simple, just displaying the attributes for XML nodes and cycling through these nodes for processing.

• Performance isn’t an issue.

• A sophisticated user interface isn’t needed.

• The interface can be inferred from available information (the XSD).

• The structure of the user interface is under external control (the XSD, not the harness).

• The task of the application is fixed, so there’s no reason, other than XSD changes, to compile and deploy the application.

• Maintenance programmers already need to understand reflection because of the way templates run. 

NOTE: If you’re interested in how I used dynamic techniques to build this tool, refer to Appendix C. It walks through the code, explaining the dynamic techniques.

Looking at the Harness Script

You’ll use scripts containing directive elements when you run the harness. I’ll discuss details of scripts and directives in Chapter 5, but a look at the XML illustrates how the XML directives control code generation. The XML corresponding to the directive displayed in Figure 3-1 is as follows:

<kg:XSLTGeneration>
<kg:Standard Name="XSLTTest" Checked="true" Ordinal="0" /> <kg:OutputRules HashOutput="true"
  OutputFileType="VB"
  OutputGenType="UntilEdited" />
<kg:MultiPass SelectFile="[MetadataFileName]"
    SelectNamespace=http://kadgen/DatabaseStructure
    SelectNSPrefix="dbs" 
 SelectXPath="//dbs:DataStructures/dbs:DataStructure/dbs:Tables/dbs:Table" OutputDir="[Chapter3]Output\XSLT Output" OutputFilePattern="<@Name>.vb" />
<kg:XSLTFiles InputFileName="[MetadataFileName]" XSLTFileName="[Chapter3]Test\SimpleDataContainer.xslt" /> </kg:XSLTGeneration>

The Standard element contains the information common to all directives. The OutputRules contains overwriting information. In this case, code generation creates a hash and overwrites any existing file, unless a human edited the file.

The MultiPass child element contains information about how multiple output files are created based on a single directive. The SelectNamespace and SelectNSPrefix support the SelectXPath in selecting nodes. The SelectFile attribute tells the harness which XML file to use in selecting nodes. Code generation creates files in the OutputDir using the OutputFilePattern. This pattern is XML-like so uses angle brackets to define replacement tokens in the filename. However, you can’t directly output the less than (<) sign via XSLT, so this attribute uses the escaped version < and >. Examples of the resulting filenames are Customers.vb and Project.vb.

The XSLTFiles element contains information about the XSLT transform. This includes the input file and the XSLT transform filename. Brute-force and CodeDOM sections of the script use identical Standard, OutputRules, and MultiPass child elements. Instead of XSLTFiles, the brute-force generation uses the Process directive. With the Standard, OutputRules, and MultiPass child elements represented by ellipses, the brute-force directive is as follows:

<kg:BruteForceGeneration>
...
<kg:Process
  AssemblyFileName="[Chapter3BruteForceExample\bin\
BruteForceExample.dll" TypeName="BruteForceExample"
MethodName="GetStream"
AssemblyName="" />

The similar CodeDOM directive is as follows:

<kg:CodeDOMGeneration TargetLanguage="VB">
...
<kg:Process
AssemblyFileName="[Chapter3CodeDOMExample\bin\CodeDOMExample.dll" TypeName="CodeDOMExample" MethodName="BuildGraph" AssemblyName="" />

NOTE The Process directive uses the AssemblyFileName attribute if the class is in an external assembly and uses the AssemblyName attribute in the less common case where the class is part of the harness.

Although these directives may initially seem complex, they provide a great deal of consistency between different directives, which makes maintenance easier. Even if you’re sticking with one generation mechanism (recommended), you’ll use multiple directives because you’ll create metadata, merge metadata, transform metadata, generate code, run SQL scripts, and so on. 

This chapter is from Code Generation in Microsoft .NET by Kathleen Dollard (Apress, 2004, ISBN: 1590591372). Check it out at your favorite bookstore today. Buy this book now.

Next: Examining Code Generation Mechanics >>
 

More .NET Articles
More By Apress Publishing

Comments On: Outputting Code

>>> Be the FIRST to comment on this article!