You may have noticed, the tutorial series I have been writing about code generation is based on T4 Toolbox. Some of you may be wondering if using the toolbox on top of plain Text Template Transformation Toolkit is really necessary. What does the T4 Toolbox provide that T4 itself doesn’t already have? Well, it improves T4 by adding another word that starts with letter T… Just kidding. When someone posted a question on the CodePlex forum about functionality the T4 Toolbox adds on top of T4, I realized that I cannot answer it with a simple bullet point list without explaining the reasons behind features and technical details.
As a software engineer, I make my living by building business applications. I use code generation tools primarily to help me build business applications faster and better. T4, on the other hand, is a code generation tool originally designed for building development tools. I started researching it back in November of 2007 to see if I could use it in application development projects I’m working on. Once I learned the trick to change file extension to .tt, It was easy to get started. However, several problems would need to be solved before I could use T4 productively.
The first real challenge was code reuse. How do we reuse code generators without duplicating the entire .tt file? Well, we need a way to pass different parameter values to the same template. Can we use the <#@ property #> directive? … Looks complicated – there are two different implementations, two different ways of passing parameters, the code is just ugly… Can we use the <#@ include #> directive? We could, but that would mean having a separate template file just to specify the parameters. How well is that going to work? … Well, it seems to be working all right… Here are some of the code generators I created during this stage: .config, decorator, CRUD, AzMan.
The next challenge was generating multiple files from a single code generator. My CRUD generator works great! Wait… I need to create 200 individual template files just to generate stored procedures for my current projects. That’s not going to fly… How do we generate stored procedures for all tables in the database from a single template?… Let’s just iterate through all tables in the template and spit out the stored procedures to a single file… Whoa! More than a 100 thousand lines in a single SQL script. I don’t think so… After a bit of digging, I figured out how to generate multiple outputs from a single T4 template.
The last challenge was figuring out how to design complex code generators. I really didn’t want to follow the example of some CodeSmith templates we’ve used before. 1200 lines of code in a single CRUD template? Well, that’s not too bad. No, wait, 700 lines of it is in a single method with a mixture of text blocks, code blocks and various conditional statements! Does anyone volunteer to maintain that when I’m done? Anyone?.. It turned out there are several different approaches you could use to design T4 templates. Merged template class, template method, standalone template and nested template class are just those that I identified. I’m sure others could come up with a few more. My personal choice is the nested template class, which strikes a nice balance between power and simplicity.
One of the nuisances we’ve had with the CodeSmith templates is having to manage generated output files manually. If a new output file is generated, you need to make sure it is added to the source control and to the Visual Studio project. If you are regenerating a particular file, you have to make sure it is checked out. I wanted to alleviate this pain in my T4 templates. To avoid this problem, I spent a fair bit of time researching Visual Studio extensibility APIs and figuring out how to invoke them from a T4 template and automate project and source control operations.
In the process of learning T4 and overcoming these challenges the amount of supporting code I had to write gradually increased. The amount of this code became significant enough to make duplicating it in each new code generator undesirable. It was time to get organized. Since I don’t have my own source control server and don’t hold any illusions about making money on this, I decided to publish it as T4 Toolbox on CodePlex.
So here you have it: T4 Toolbox provides an object-oriented micro-framework, built on top of T4 to help building code generators during application development projects. You may want to consider using it if you are working on application development projects and are concerned about code reuse, generating multiple files, simplifying source control operations for numerous output files, maintaining and unit testing complex code generators. Do you have to use it? No, you can make plain T4 do the job.
P.S. Wow! This was meant to be a single paragraph when I started… Anyway, I hope this explains the why’s behind T4 Toolbox. In the next post I’ll provide the what’s and how’s - technical details.