Outputting Code - Understanding Other Features of the Generation Harness
(Page 3 of 19 )
An overview of harness features will help answer questions that may arise as you explore template details later in this chapter. For example, in the later discussion on using template parameters, you might wonder how context-sensitive parameters are passed from the harness. Information on harness features will also let you use the generation harness to test the templates in this chapter. This overview is simplified, and Chapter 5 offers additional information on these features.
Working with Abstract File Paths
The generation harness uses abstractions for file paths and names. This allows the same script to be used to start another project by changing only path definitions. Many of the file paths appear multiple times within the script, and this also provides you with a straightforward way to update all occurrences quickly. Square brackets surround abstract FilePath filenames, such as the BasePath in this code:
OutputDir="[BasePath]Chapter 3\Output\XSLT Output"
The FilePath elements of each harness script contain the definitions for the abstract file paths used by that script. You can nest abstract paths and use multiple abstract paths in a sequence.
NOTE: File paths are relative to the harness script file location. This allows users with different file configurations to use the same harness, as long as the project directory has the same organization. |
Providing Parameters
The harness retrieves the parameters accepted by templates during the generation process. It does this via reflection for brute-force and CodeDOM templates and by running an internal stylesheet against XSLT templates.
NOTE: To retrieve parameters from an XSLT stylesheet, the stylesheet is opened as the input XML document, and an internally stored XSLT stylesheet is run against the template stylesheet. The internal XSLT retrieves all <xsl:param…> elements that are children of the <xsl:stylesheet…> (or <xsl:transform…>) element in the template stylesheet. |
CAUTION: Parameter names are case sensitive.
The harness itself provides three special parameters. If your template accepts any of these parameters, the harness will pass the values. The three special parameters are as follows:
- fileName passes the name of the output file. This would generally be used in a header comment.
- genDateTime passes the date and time the generation is to perform. You could use this in a header comment, but it causes files under source control to be checked in every time you run code generation, so this isn’t recommended.
- nodeSelect passes the current node of the file. This isn’t valid for XSLT processing, but it’s important in brute-force and CodeDOM generation to determine the XML input file context for the code generation (which node you’re processing).
In addition to these special parameters, the harness checks the node it’s processing in the input XML metadata for attributes matching the names of any additional parameters your template accepts. You’ll usually pass something identifying the current node, such as the name of the current table or object.
CAUTION: The match between parameter names and the attribute name in the XML input node is case sensitive.
TIP: Pass identifying values as parameters that allow the template to find the node to process in the metadata. If the SelectFile is the metadata file (the normal case), the template will be processing this node. It’s generally easier to retrieve additional values from the metadata than pass them as parameters. (The “Looking at the Harness Script” and “Introducing the Target and Metadata Files” sections explain this in more detail.) |
CAUTION: No error occurs if attributes matching your parameters aren’t found.
Overwriting Files Managing file overwriting is a critical part of code generation. It’s important to overwrite the correct files without overwriting the wrong files, particularly those you’ve modified by hand. Overwriting rules are defined in the harness script, so you don’t have to make any decisions during generation unless something goes wrong. In Chapter 5, you’ll see how to manage file overwriting through the OutputGenType attribute of the OutputRules child element. This allows you to specify whether to overwrite files and log errors if the harness encounters manually edited files. This feature ensures you can meet the goal of providing protection for manually edited files.
To provide this level of control, the harness needs to know whether a programmer has manually edited each file. You might think about using a date/time stamp, but in addition to the ugliness of tracking it across time zones, it isn’t reliable, especially because source control frequently changes the file time stamps. A better solution is to place a hash marker within the file header comments. A hash marker is a numeric value that has an extremely high probability of uniquely representing the underlying value—in this case representing the file’s text. The initial hash corresponds to the original file. If a hash calculated later doesn’t match, then someone has edited the file. Chapter 5 explains hash markers in more detail.
The hash marker is the weird sequence of characters at the top of a file; if you edit or remove them or the surrounding comments and markers, you’ll get code generation errors. This is an example of a hash marker:
%%%###%%%65c708f97193ef7405269d998b960f54%%%###%%%
 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: Extending the Harness >>
More .NET Articles
More By Apress Publishing
