Click here to Skip to main content
12,701,314 members (36,199 online)
Click here to Skip to main content
Add your own
alternative version

Tagged as


31 bookmarked

Using T4 Templates to generate custom strongly-typed code in Visual Studio

, 17 Oct 2011 CPOL
Rate this:
Please Sign up or sign in to vote.
Strongly typed code rocks. Easy as that. Reduces bugs, and makes your developments more productive and efficient. We all know that.

Strongly typed code rocks. Easy as that. Reduces bugs, and makes your developments more productive and efficient. We all know that.

One example of strong-typing inside Visual Studio: resource files are parsed by default with the ResXFileCodeGenerator tool, which generates automatic properties in C# files, that give us strongly-typed access to strings.

That’s cool, by I there’s a lot of customization capabilities there missing. For instance, ResXFileCodeGenerator generates internal classes by default, and this is not always desirable. Many people struggled around this in the past, so in Visual Studio 2008 a new custom tool was introduced: PublicResXFileCodeGenerator: the same one than before, but building public classes. Cool again, but still missing many things…

So, how to customize the code generation process?

Option 1: Write your own tool

You can write a tool that mimics the behavior of ResXFileCodeGenerator, and you can install it within the Visual Studio (so you can select your ResX files to be parsed with it). It´s not too complicated, but you need to develop a separate installation project, to be able to install it within VStudio. You can find an example here.

To be honest, I don´t like the idea of having to write the extension in a different project, needing to go there for every change, recompiling, re-installing, etc. Besides that, this approach means having one single tool for every resX files you want to parse, and therefor, the tool needs to be generic enough to give support for every use case you have.

One last inconvenient, is that as far as I know, a tool like this cannot act in several files at a time. That means that it will generate a code file for each resource file. It’s impossible to generate ONE code file for SEVERAL resource files.

Seems that I´m too lazy today for all of that, so I searched for other solutions, and found one that I really like: T4 templates

Option 2: Write a T4 Text Template

A T4 Text Template is “a mixture of text blocks and control logic that generate a text file”. In other words, it’s a piece of code that will generate a text file and will include it in your Solution (below the .tt file itself). This text file, pretty well can be a source code file, so this way we can automatically generate code for the solution, with all the power to customize it.

I have been studying them for a while, and I can tell you that they are really powerful. Some relevant aspects around them:

  1. They are text files (with .tt extension), that are included INSIDE your solution, so no need to keep them in a separate project, and no need to build a setup project to install them.
  2. This .tt files are, by default, parsed by the custom tool: TextTemplatingFileGenerator
  3. They can operate on several project files at a time, not only one, generating if you want ONE code file, for SEVERAL resource files.
  4. They don´t need to be installed or distributed in any form. Simply add them to your solution
  5. Changes in the Template don’t mean to go to a different solution, rebuilding and re-installing
  6. They can be written in both C# or VisualBasic.
  7. When they are parsed, the generate a code file below the Template (see below), with the same name as the template itself:


  1. They are usually parsed as soon as they are modified and re-saved.
  2. Because the modification and installation process is so simple, and because you can have if you want a different T4 Template for each resX file, you can have as many versions of the templates as you wish. Each one covering different needs. And that is cool !
Any disadvantages? Visual Studio integration

By now, Visual Studio offers no integration for T4 files. That means that by default you get no syntax highlighting, no intellisense, etc.

But this can be fixed by using one of the T4 integration extensions for VStudio out there. I have tested three of them:

  • Tangible T4 Editor: Honestly, I couldn’t get it to work. I installed it, apparently with no error, but it didn’t work. And I already started this post by saying I´m too lazy today, so I tested other solutions that installed fine at first try:
  • Clarius Visual T4: It installed just fine and added syntax highlighting and intellisense to T4 files. Unfortunately, it made my Visual Studio 2010 Ultimate freeze for about 10 seconds from time to time. So I decided to try a different option.
  • Deviart T4: It installed fine, and works pretty well. The syntax highlighting gets messed from time to time, but nothing serious. Just re-opening the file fixes it. It’s fast, and I like it. It’s the clear winner. And it’s free!


Some basic concepts about developing T4 templates

Developing a T4 template is pretty straightforward, if you have some experience with .Net. We are not going to explain here all the coding aspects about T4 templates, as it is extremely clearly explained here and here.

However, it’s a bit meesy the first time you see one, how code blocks are mixed with plain text blocks, especially if you don´t have an extension installed that gives you syntax highlighting.

So, first thing you should understand is that T4 templates mix parts of text that will simply be copied to the generated file (Text Blocks), and others that are code blocks to control the logic of the generation (Code Blocks). In Deviart T4, you will see the following highlighting:

  1. Text blocks, copied directly to the destination file (grayed out):


As I mentioned, whatever you write here will be directly copied to the destination file. No matter what it is. It won´t be validated by the tool, just copied. You are responsible of writing something that makes sense, and that won’t generate compiling errors.

  1. Code blocks (surrounded by <# … #> and similar):


These code blocks are parsed by the tool and executed. They are validated by the compiler, just like any other piece of code you write (that means that will generate compiling errors as usually). In the previous example, the code block is writing a “}” symbol to the output file, using the WriteLine method (se next chapter for more info).

Different ways to output text to the destination file

We already seen some of them, but basically, you have three different ways of outputting text:

1.- Put a Text Block in your template (like in the previous chapter).

2.- Invoke the WriteLine method inside a Code Block. Like in the example of previous chapter, anywhere you call WriteLine(“…”) from within a code block, will write that text line to the destination file.

3.- Mixing both Code Blocks and Text Blocks, like in the following example:


In this example, the header Text Block (grayed out) will only be copied if insertWarningHeader == true. This means that flow control of code blocks affect the output of plain text blocks too.

Please note that you need to “end” the Code Block by using the “#>”, and therefor the text inside the braces will be identified as a Text Block. Then, re-open a code block, just to put the final brace “}” of the IF statement. Separating it into two different Code Blocks doesn’t prevent the IF from doing its job…

Other useful kinds of Code Blocks

As you can see, the <# … #> labels define the start and end of code blocks that should be parsed and evaluated. Anything outside those labels is considered text blocks. There are other kinds of code blocks, as explained here:

  • Expression code blocks (<#= … #>): They evaluate an expression, and convert the result to string. Some examples:
    1. <#= 2 + 3 #> … will output a “5”
    2. <#= numberOfEntries * 2#> … Where numberOfEntries is a valid variable on that scope, will output the result of the addition.
    3. etc.
  • Class feature code blocks (<#+ … #>): Allow to define properties or helper methods. They can be defined in separate files. The following example defines the property RootNamespace and the helper method EmitEnum, available in all the template.


  • Importing namespaces is also very easy, you just need to put in the top of the file statements like the following:

<#@ import namespace="System.Xml" #>

I think that there’s not too much magic in here, so I won’t bore you with more detail. Everything is really simple to follow, and is really well explained in the above links, so I guess the best way to show a real T4 Template is with an example!

Example: Custom strong-typed access to resources with a T4 template

What we need

In this example, we will used the mentioned T4 templates to give a full-featured, strong-typed access to strings in resource files. I did it to meet my own needs, but using it as a starting point, it will very easy for you to adapt it to your own.

The goal is to be able to customize the following aspects directly from the resX file:

  • Access modifier of the class: public, private, internal
  • Namespace where the class is defined
  • Generate (if wanted), an enumeration with all the keys of the entries
  • Modify the return type of the properties. Does this make any sense? Yes (read below).
  • Allow ResX files to use Conditional Compilation:
    1. It would be fantastic if we could specify different values for strings, depending on conditional compilation symbols
    2. And it would be even greater, if we could specify different return types, depending on the same conditional compilation symbols.

Does it make any sense to modify return types?

In my scenario, it does. I’ll explain it, so you can see one example. Then it’s up to you to decide if that’s useful also in other situations…

I was writing a piece of code, related to 3D graphics, that I wanted to run in both Windows Phone and Android. That code has contents (bitmaps, etc), which are identified differently in Windows Phone (XNA) projects, and Android.

In the first one, contents are identified with Asset Names, which are strings. In the second one, contents are identified with Integer IDs. In fact, Android automatically generates a class like the ones we are creating here to give strong-type access to those integers.

Well, I wanted to centralize the loading of contents, so it was obvious that I would need to unify content identification with my own IDs. I simply didn’t want to have #if #endif blocks all around my code.

Question is, that I can write two versions of methods like LoadTexture(), one for each platform, and keeping the specifics inside the Content Repository, but the problem is that Android identifies contents with a different type (ints instead of strings), and that makes my code end up with a different interface for each version. Something like this:

        public static void LoadTexture(int pResourceID)
        public static void LoadTexture(string pAssetName)

I have no problem with writing two versions of the method (that’s inevitable). But having two different interfaces is bad. Really bad.

Why? Because then, every single point in my code where I use this method will need a #if #endif code block too. And I hate that. I want this contents repository to expose a single interface. How do we achieve that?

If both platforms used strings to identify contents, I could create a table to map my own resource identifiers to that ones. But Android uses ints. And what is worse, they are automatically generated. I can see what IDs Android gave to a content, but I cannot guarantee that the ID will be consistent over time, as it’s generated by an automatic tool. In addition to that, I would need to maintain that table by hand, what is horrible and very bug prone.


Seems that the only solution is writing code, with methods or properties that map my own resource IDs to: string assets in the case of XNA, and resource IDs in the case of Android. Something like:

        public static int Button1
                return Resource.Drawable.Button1;
        public static string Button1
                return @"Contents\Textures\UI\Button1";

Having a repository like this, would allow me to eliminate the #if #endif blocks when calling methods like LoadTextures, as I could use: LoadTextures ( Respository.Button1 );

If we are compiling to ANDROID, Button1 will return an int and LoadTextures() will expect an int, so no problem. If we are compiling to Windows Phone, both will give and expect a string. Everything fine again.

The problem with that is that a single project can have hundreds, or thousands of resources, an maintaining the file manually can be a nightmare. If only it could be done automatically…

That’s where the variable return type of my template kicks in. It will give us precisely that, with the particularity that when on ANDROID (being the return type an int), the template will not insert string, but a call to the Android Repository.

This way, I get rid of having to deal manually with Android int IDs, and just work with their strong-typed names.

See below for more…

The implementation

The behavior of the template we have developed, to achieve all of this is:

  • It is designed to be placed inside your projects, just by the file it will process. It has to be in the same folder and needs to have the same name. So, if you want to process the file Textures.resx, you will end up with something like this in your solution:

Note 1: You can easily modify it to parse all the ResX files it finds in the project at once, but this time I needed it to work this way.

Important Note 2: To avoid duplicity of generated code, and compilation errors, when you add the template to a resource file, you should disable the default parsing of that ResX file, by removing the default custom tool (ResXFileCodeGenerator) and by setting BuildAction = None.

  • It will generate strong-typed properties to access all the strings it finds in the resX file
  • It can be instructed to generate an enumerate with all the keys in the file too
  • It will automatically generate the well formatted XML comments for the properties
  • It supports some special keywords (entries starting by “#C#_”), to allow customizing the generation process:
    1. CT4_ACCESS_MODIFIERS (public, private, internal): By default, the generated class will be public, but you can include this entry to modify this behavior. You can set the following values: public, private or internal.


    1. CT4_OVERRIDE_NAMESPACE (namespace name): By default, the class will be in the default namespace of the project, but you can include this entry to override that behavior, setting the desired namespace in the value of the entry:


  1. CT4_GENERATE_ENUM (enum name): If this entry is included, the template will create an Enumeration with all the key names of the ResX file, and also an special version of the GetResourceString() method, accepting as parameter one of those enumerations. You can specify the name of the enumeration in the Value field.


  1. CT4_DEFAULT_RETURNTYPE (string, int, etc): Allows to specify the default return type for all properties. The default return type if string.


  1. CT4_CONDITIONAL_COMPILATION_SYMBOLXX (Symbol Name): Allows to use conditional compilation inside the resource files. To do so, you must first identify what conditional compilation symbols are used in your project. In this example, we will have two of them: WINDOWS_PHONE, and ANDROID. So, we will create two entries to let the generator know about them, like the following:


  1. CT4_CONDITIONAL_RETURNTYPE: If conditional compilation is being used, it allows to specify a different return type for each conditional symbol, with following syntax:

@COND_SYMBOL1:type_1;@COND_SYMBOL2:type_2 …

Where COND_SYMBOLXX is one of the conditional compilation symbols defined before, and type_XX is the return type desired for that symbol.

The following example a string return type for WINDOWS_PHONE, and an integer return type for ANDROID:


Once we have configured the generation process with the control entries, it’s time to put some data there. A normal string entry is entered as usual, with unique name, a value, and a comment if you want to. How to include conditional compilation entries?

Using conditional compilation in string entries

The name and the comment of the entry are the same as in normal ones. It’s in the Value where we put the information needed, very much like when defining specific return types for each conditional compilation. The syntax is:

@COND_SYMBOL1:value_1;@COND_SYMBOL2:value_2 …

Where COND_SYMBOLXX is one of the conditional compilation symbols defined before, and value_XX is the string value desired for that symbol.

So, the following example:


Will generate the following code:

   66         ///<span class="code-SummaryComment"><summary>

Note that the generator also takes into account the Comment field, and that the return types and values for each version of the property are different. Also, in the case of Android, note that the get method makes a Call to the Android resource repository class, with the strongly-typed properties that access the IDs.

The Template Code

The template is based on this other one, but with a modified behavior to meet my own needs. The code is:

    //  ----------------------------------------------------------------------------------------------
    //  Template: Generates C# code to give strongly-typed access to resource files
    //  Author: Inaki Ayucar
    //  Website:
    //  Based on the work of:
    //  Links: 
    //          MSDN about developing T4 files:
    //  ----------------------------------------------------------------------------------------------
    <#@ template debug="true" hostspecific="true" #>
    <#@ assembly name="System.Core" #>
    <#@ assembly name="System.Xml" #>
    <#@ assembly name="Microsoft.VisualStudio.Shell.Interop.8.0" #>
    <#@ assembly name="EnvDTE" #>
    <#@ assembly name="EnvDTE80" #>
    <#@ assembly name="VSLangProj" #>
    <#@ import namespace="System.Collections.Generic" #>
    <#@ import namespace="System.IO" #>
    <#@ import namespace="System.Linq" #>
    <#@ import namespace="System.Text" #>
    <#@ import namespace="System.Text.RegularExpressions" #>
    <#@ import namespace="System.Xml" #>
    <#@ import namespace="Microsoft.VisualStudio.Shell.Interop" #>
    <#@ import namespace="EnvDTE" #>
    <#@ import namespace="EnvDTE80" #>
    <#@ import namespace="Microsoft.VisualStudio.TextTemplating" #>
    <#  // --------------------------------------------------------------------------------------------
        // Get global variables
        // --------------------------------------------------------------------------------------------
        var serviceProvider = Host as IServiceProvider;
        if (serviceProvider != null)
            Dte = serviceProvider.GetService(typeof(SDTE)) as DTE;
        // Fail if we couldn't get the DTE. This can happen when trying to run in TextTransform.exe
        if (Dte == null) 
            throw new Exception("T4MVC can only execute through the Visual Studio host");
        Project = GetProjectContainingT4File(Dte);
        if (Project == null) 
            Error("Could not find the VS Project containing the T4 file.");
         AppRoot = Path.GetDirectoryName(Project.FullName) + '\\';
         RootNamespace = Project.Properties.Item("RootNamespace").Value.ToString();
        // --------------------------------------------------------------------------------------------
    // ---------------------------------------------------------------------------------------------------
    // <auto-generated>
    //     This code was generated by a tool.
    //     Changes to this file may cause incorrect behavior and will be lost if
    //     the code is regenerated.
    // </auto-generated>
    // ---------------------------------------------------------------------------------------------------
    using System.Threading;
            // We are storing in a List<ResourceEntry> (declared below) a list with all string entries 
            // of all files found matching our search criteria
            AllEntries = new List<ResourceEntry>();
            // Entries starting with "CT4_", are declared as "control" entries, defining keywords or data 
            // that will modify the source code generation behavior
            ControlEntries = new List<ResourceEntry>();
            // Find files on our project that match our search criteria (recursively), and store every 
            // string entry on those files
            FindResourceFilesRecursivlyAndRecordEntries(Project.ProjectItems, "");
            AllEntries.Sort( new Comparison<ResourceEntry>( (e1, e2) => (e1.Path + e1.File + 
                                     e1.ValidIdentifierName).CompareTo(e2.Path + e2.File + e2.ValidIdentifierName)));
            // Parse control entries
            string overrideNameSpace = "";
            string classAccessModifier = "public";
            string generateEnumName = "";
            string defaultReturnType = "string";
            Dictionary<string, string> returnTypesForConditionalCompilation = new Dictionary<string, string>();
            List<string> conditionalCompilationSymbols = new List<string>();
            List<string> conditionalCompilationSymbolsInValues = new List<string>();
            foreach(ResourceEntry entry in ControlEntries)
                if(entry.OriginalName == "CT4_OVERRIDE_NAMESPACE")
                    overrideNameSpace = entry.Value;
                if(entry.OriginalName == "CT4_ACCESS_MODIFIERS")
                    classAccessModifier = entry.Value.ToLower();
                    if(classAccessModifier != "public" && 
                       classAccessModifier != "private" && 
                       classAccessModifier != "internal")
                        Error("Invalid CT4_ACCESS_MODIFIERS found: Only public, private or internal are allowed");
                if(entry.OriginalName == "CT4_GENERATE_ENUM")
                    generateEnumName = entry.Value;
                    conditionalCompilationSymbolsInValues.Add(string.Format("@{0}:", entry.Value));
                    defaultReturnType = entry.Value;
                    bool hasCondCompilation = StringValueHasCompilationSymbols(entry.Value, 
                        Error("CT4_CONDITIONAL_RETURNTYPE entry found, but no conditional symbols were found in value");
                    Dictionary<string, string> parts = SplitStringForConditionalCompilationSymbols(entry.Value, 
                    foreach(string symbol in parts.Keys)
                        returnTypesForConditionalCompilation.Add(symbol, parts[symbol]);
            // Foreach string entry found, add it's code
            string currentNamespace = "";
            string currentClass = "";
            bool thisIsFirstEntryInClass = true;
            List<string> names = new List<string>();        
            for(int i=0;i<AllEntries.Count;i++)
                ResourceEntry entry = AllEntries[i];
                var newNamespace = overrideNameSpace == "" ? RootNamespace: overrideNameSpace;
                var newClass = entry.File;
                bool namesapceIsChanging = newNamespace != currentNamespace;
                bool classIsChanging = namesapceIsChanging || newClass != currentClass;
                // Close out current class if class is changing and there is a current class
                if(classIsChanging && currentClass != "")
                // Check if there is a namespace change
                    // Close out current namespace if one exists
                    if( currentNamespace != "" )
                    currentNamespace = newNamespace;
                    // Open new namespace
                    WriteLine(string.Format("namespace {0}", currentNamespace));
                // Check if there is a class Change
                    currentClass = newClass;
                    WriteLine(string.Format("\t" + classAccessModifier + " class {0}", currentClass));
                    thisIsFirstEntryInClass = true;
                    // Only if the class changed, Emit code for the ResourceManager property and 
                    // GetResourceString method for the current class
                    private static global::System.Resources.ResourceManager resourceMan;
                    /// <span class="code-SummaryComment"><summary>

Et voilà ! An input and output example

The above template, applied to the following input:


Produces the following output class:

// ------------------------------------------------------------------------------------------------------
    // <auto-generated>
    //     This code was generated by a tool.
    //     Changes to this file may cause incorrect behavior and will be lost if
    //     the code is regenerated.
    // </auto-generated>
    // ------------------------------------------------------------------------------------------------------
    using System.Threading;
    namespace GDNA.PencilBurst
    public class Textures
            private static global::System.Resources.ResourceManager resourceMan;
            /// <span class="code-SummaryComment"><summary>

Other Use Cases

The possibilities are almost endless. You don´t need to stick to Resource Files (ResX) only. You can do this operations with almost anything. For example:

  • You can write a T4 Template for a “Contents” projects, that searches for Textures or Bitmaps in the project, and generates a Class that strong-types the names and/or paths of those textures. Creating your own Content Manager.
  • You can generate your own classes to give strong-type access to your Data-Sets, in a totally customized way.
  • Or you can generate a class that bases it’s strong type access in an enumeration, instead properties, something like the following:
internal class TexturesByEnum
        private static global::System.Resources.ResourceManager resourceMan;
        /// <span class="code-SummaryComment"><summary>

This way, access to resources would be:

string aux = Textures[eTextureIDs.Button1];
  instead of…
  string aux = Textures.Button1;

As you can see, the customization possibilities are huge, and the examples countless.

So use your imagination !!

Cheers !


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Inaki Ayucar
Software Developer (Senior)
Spain Spain
Inaki Ayucar is a Microsoft MVP in DirectX/XNA, and a software engineer involved in development since his first Spectrum 48k, in the year 1987. He is the founder and chief developer of The Simax Project ( and is very interested in DirectX/XNA, physics, game development, simulation, C++ and C#.

His blog is:

To contact Inaki:

You may also be interested in...

Comments and Discussions

Suggestionsome spell mistake is there,its not a major one but to get the clear picture just modify deviart to devart Pin
satishdeevi6-Jul-14 0:06
membersatishdeevi6-Jul-14 0:06 
Generalreally good one Pin
satishdeevi4-Jul-14 23:41
membersatishdeevi4-Jul-14 23:41 
GeneralMy vote of 5 Pin
dharmbhav29-Apr-13 21:36
memberdharmbhav29-Apr-13 21:36 
QuestionSuch an excellent article and so few votes! Pin
visalia5-Sep-12 0:53
membervisalia5-Sep-12 0:53 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web02 | 2.8.170118.1 | Last Updated 17 Oct 2011
Article Copyright 2011 by Inaki Ayucar
Everything else Copyright © CodeProject, 1999-2017
Layout: fixed | fluid