T4 templates: the lazy programmer’s friend

Text Template Transformation Toolkit (T4 templates) are a very powerful asset when used appropriately. Their main advantage is their ability to generate large amount of repetitive code over and over, at the click of a button and with a Swiss watchmaker’s precision.

My current project, Responder, an Outage Management System, contains dozens of xml files to define its data model and for configuration. Until a few months ago, adding a new column to a data table was a several hours process. It involved a lot of manual editing of XML files, updating SQL scripts, updating of code classes used to manipulate data, etc.. Errors were frequent and the simplest typo could prove dramatic if not caught on time by manual testing.

This all started changing with a T4 template. By generating all the necessary code straight out of the XML file, we removed most of the hand-coding, making the code (our RxDb.* and ArchivesDb.* structures for those who know) a perfect translation of the content of the original XML file. In the process, we have found typos and missing code that slipped through the QA cracks.

This change to code generation was started a couple of years ago. Now, other team members have embraced the T4 power to generate business objects to manipulate data in our complex DataSets. This has allowed us to update our data schema with minimal friction and add a lot of convenience methods to all our business objects with just a couple of line of actual code change

Of course, T4 templates have their own complexity and can be hard to navigate as they are a mingling of template and code. This becomes even more blurry (literally) when you are generating a C# file using C# as the template language. But, with the right tools, you can make more sense out of this funky looking piece of code/template.

Here is the MSDN main documentation for T4 templates, fully supported in VS2010. You can find the supporting source code for this post here. I have to apologize for dummying down the attached code, but I wanted to ensure that it did not contain any proprietary information. I took the safe route and took out any business-related terms. I just kept the basic structure.
Don’t forget to download the free tangible T4 Editor for VS2010. There are plenty very valuable resources online which will guide you through your first steps.

But here are some pointers that can help you keep things clean.

The first pointer I will give you is regarding accessing local but relative resources (such as XML files). Feel free to visit StackOverflow and read through my question and the answer here. Basically, if you want your template generating code to be aware of its surroundings, you must set the hostspecific flag to true AND use the Host class to access host-specific information. This makes your template portable.
Here is the tag declaration: 

<#@ template language="C#" hostspecific="true" #>

And here is the use of the Host class:


XmlFile = Host.ResolvePath(@"..\Data\Schema.xml")

The following pointer was not in the original post but came after several months of using more and more T4 templates. We started realizing that, as we add more code to the generated code, our templates were getting pretty hard to read. We were able to simplify some of our templates by using some of the following techniques:



  • Abstract base class: whether you are generating a single class or many classes, putting some of the common code into an abstract base class will keep your template focused on the code that needs to be generated
  • Extension methods: introduced with C# 3.0, those allow you to add public methods to existing classes without getting access to the extended class. There are some restrictions with this approach, but it will still allow you to separate code that must be generated from code that can stay static from one code-gen to another
  • Partial classes: the best approach in my opinion. This allows you to put all your static code in one or more code file and leave only the generated code in your T4 template. And the static code can include private members, helping you keep your objects nicely encapsulated

Of course, the best approach is a good mix of all 3 of them. Try to keep each code file, be it template, extensions, partial or base class, as easy to read as possible. The attached code sample contains both an abstract base class and partial classes.

Comments

Post a Comment

Popular posts from this blog

Running Karma in specific TimeZone

Recently, I had to write some tests related to date and time. In order to tests corner cases, in particular when the UTC date was different from the local date, I had to find a way to set the timezone for my tests. There are countless posts and articles out there that explain how you can set a specific time , but I couldn’t find much about how to actually set the timezone . Many articles references how you could use your browser’s profiles to set it up, etc. But all of it seemed too complicated for my taste. In the end, I came across a gitlab-foss commit by Takuya Nogushi . Simply setting the process.env.TZ variable will do the trick. module . exports = function ( config ) { config . set ( { // your karm configuration } ) ; // Fix the timezone process . env . TZ = 'America/New_York' ; } ; I have not tested with other browsers, but this works with Chrome. The possible values for TZ are available on Wikipedia .
Read more

Let’s get blogging!

Hello dear visitor. This will officially be my first blog post. I know, not that exciting, but I have been posting a bit on our internal blogs for the past few months, sort of getting my feet wet. But I decided it was time to take my posting to a larger audience. Not that the world has been missing what I have been saying, but because I want to get more feedback from the software engineering community at large. For years, I have been following and admiring Jeff Atwood from his Coding Horror days to Stack Overflow . On multiple occasions, he reminded us that sometimes, you just need to get out there, and get started. You won’t be an internet superstar overnight, but overnight success does not happen overnight . That goes for writing software, to writing blogs and many other aspects of our lives. And recently, my coworker Shawn Kendrot decided to take that step also and start blogging to the world on Visually Located . I actually borrowed his disclaimer. To get started, I am going t...
Read more

Semver carets and tilde in npm

If you use npm you have likely seen notation for dependencies in your package.json like ^4.2.7 or ~3.5.3 , etc. Those are respectively caret ranges and tilde ranges . They are well documented on the npm website . And while I have become quite familiar on how to use them, I had an epiphany recently that I thought I would share. This could help newbies navigate these powerful yet odd notation. The main power of those notations versus their easier-to-understand cousins x , X and * is that you can fix the lowest version . This is usually critical, because when everybody follows semantic versioning, a library is backward compatible , but your code, as the consumer, does not have to be. Actually, it is only forward compatible . Let’s say you use a library called foo . The authors of foo , at version 1.2 decide to introduce a cool new bar() method in their package. You want to take advantage of bar() in your code. If you used the x notation in your package.json , like this: ...
Read more