Outputting Code - Exploring Other Features
(Page 18 of 19 )
In addition to the structure of the CodeDOM, a couple of features cut across all the different layers of the CodeDOM. These include UserData, which pass any information to the language-specific compiler, and code snippets, which include literal code in your output.
Using UserData UserData lets you enter information that the language-specific provider uses to alter details of how it outputs code. This is a great feature. Unfortunately, the current providers support few UserData items, and many that they do support are undocumented.
NOTE: Appendix D shows how to control Option Strict and Option Explicit in VB.NET output using UserData. |
UserData appears at all levels of CodeDOM objects (compile unit, namespace, type, member, statement, and expression). In all cases, UserData is an IDictionary object allowing a string key and an object value. Only the language-specific provider that’s looking for a UserData entry will use it. Language compilers ignore any UserData items they don’t know about. If you extend CodeDOM providers, keep UserData in mind as the appropriate mechanism for the template programmer to communicate information to your specific provider.
Using Snippets Literal snippets are evil. Okay, maybe they aren’t quite evil, but they’re terribly close. Snippets output language-specific code. The code contained in the snippet is output as literals—it isn’t interpreted by the CodeDOM, which is why it’s language specific.
Snippets may seem cool, but a short time after you do anything with literal snippets you’ll smack yourself on the head and do the Homer Simpson “D’oh!” I hope the reason you’re using the CodeDOM is to provide language-specific output from a language-neutral source. Snippets output literal code segments, and literal code segments are inherently language specific. If you’re doing language-specific stuff, you’re breaking language neutrality, so why use the CodeDOM? Snippets are easy to grab when you can’t figure out how to make the CodeDOM do something, and certainly that’s their purpose. But before resorting to them, exhaust other ways to accomplish what you need. You can insert snippets in numerous locations in your code, and there are a handful of different snippet classes to provide the correct type of snippet for different uses, such as CodeSnippetTypeMember, CodeSnippetStatement, and CodeSnippetExpression.
Although it’s ugly, passing a flag that indicates which language you’re currently outputting and inserting different snippets based on the language is possible, but it makes the CodeDOM graph itself language specific, so you have to regenerate the graph for each language.
NOTE: The current version of the code generation harness regenerates the CodeDOM graph although my primary intention was to simplify the harness, not to make it easier to output snippets. |
Understanding the Nature of Output
The CodeDOM is about the syntax it outputs and makes no attempt to see if the output is sensible. For example, the CodeDOM recognizes the difference between variables and arguments and provides CodeVariableReferenceExpression and CodeArgumentReferenceExpression. However, both C# and VB .NET happen to use the same syntax for both variables and arguments. Both the variable and the argument class output the same thing, the output will compile, and you won’t see an issue unless someone uses your template to create output in a language that differentiates between the variables and arguments. In this particular case, I can’t think of a language that differentiates how arguments and variables are referenced, so you could argue it doesn’t matter. But that’s really the issue I’m describing—the CodeDOM allows you to be as sloppy as you’d like, and your only feedback is later compiler errors or improperly behaving applications, which may occur down the road and undermine your vision of a single template for all output languages.
NOTE: There are numerous other cases where the CodeDOM and the compiler won’t choke on what you’re outputting, but the CodeDOM classes are improperly used. Although this may seem to make life easier, I think it actually makes it harder to work with the CodeDOM. You don’t know if it’s correct unless you carefully review your code by examining it manually. That’s tedious and error prone. The best you’ll be able to do is get to know all of the classes in the CodeDOM, particularly those in Figures 3-3 and 3-4. In some cases, such as switching the CodeVariableReferenceExpression and the CodeArgumentReferenceExpression, the output is identical and you could probably ignore the issues. In other cases, such as switching the CodeBinaryOperatorExpression and the CodeAssignStatement, the output may work in one language but not all .NET languages. |
Using Keywords
Each CodeDOM language provider understands its own keywords and how to mark them when they’re used as variable names. C# escapes them using the at (@) sign, and VB .NET surrounds them with square brackets as in [New]. If you’d prefer to modify keywords, such as adding a leading underscore, you’ll have to do that yourself. Because the CodeDOM language provider handles escaping, you can use any names that match your style guidelines.
Using Parentheses CodeBinaryOperatorExpressions places parentheses around its output. You can control parentheses with the order you build up these expressions, but you can’t explicitly output parentheses unless you use snippets.
Testing in All Target Languages
It’s absolutely essential that you test in all your target languages. I’ve been unable to create something that executed differently in the two core languages once it compiled in both (with Option Strict On [See footnote 13]) other than the Shadows issue (discusses in Appendix D) and the scope issues on private interfaces. That doesn’t mean it isn’t possible; if you can create something, send it to me because it should be reported as a bug. This consistency says a great deal about how robust and stable the CodeDOM is, but it’s not surprising because Visual Studio uses the CodeDOM in multiple places.
Footnote 13. I suggest you don’t count on C# operator overloading and VB .NET implicit casts (used when you set Option Strict Off) to always produce the same results.
Although I haven’t created code that did different things once it compiled, I can create dozens of different ways to output code that’ll compile in one but not both languages—and that doesn’t even touch on warnings because C# catches unused variables and inaccessible code, and the VB .NET compiler doesn’t. I haven’t used the CodeDOM in J#. It’s essential that you test the compile in all target languages early and often to catch problems and adjust your habits. You also need to test the resulting code. Microsoft used the technology in a relatively narrow usage, and there aren’t many other people out there shaking it down.
 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: Working with the CodeDOM >>
More .NET Articles
More By Apress Publishing
