Yippeee!

Starting in Beta 2, precompiled T4 templates support the parameter directive:

<#@ template language =" VB " inherits =" TemplateCommon.DotNetBase " #>

<#@ import   namespace =" Universal.TemplateCommon " #>

<#@ import   namespace =" AppVenture.Common " #>

<#@ parameter name =" Fred " type =" System.String " #>

Parameters aren’t supported yet in Intellisense (the add-in needs to catch up) and they aren’t highlighted with my set of Add-Ins. But the code above produces:

       Private _FredField AsString

        ''' <summary>

        '''Access the Fred parameter of the template.

        ''' </summary>

        Private ReadOnly Property Fred() AsString

            Get

                Return Me._FredField

            End Get

        End Property

And the Initializer attempts to assign the value to the parameter :

       Public Overrides Sub Initialize()

            MyBase.Initialize()

            If (Me.Errors.HasErrors = False) Then

                Dim FredValueAcquired AsBoolean = False

                If Me.Session.ContainsKey("Fred") Then

                    If (GetType(String).IsAssignableFrom(Me.Session("Fred").GetType) = False) Then

                        Me.Error("The type 'System.String' of the parameter 'Fred' did not match the type of the da" & _

                                "ta passed to the template.")

                    Else

                        Me._FredField = CType(Me.Session("Fred"), String)

                        FredValueAcquired = True

                    End If

                End If

                If (FredValueAcquired = False) Then

                    Dim data AsObject = Global.System.Runtime.Remoting.Messaging.CallContext.LogicalGetData("Fred")

                    If (Not (data) IsNothing) Then

                        If (GetType(String).IsAssignableFrom(data.GetType) = False) Then

                            Me.Error("The type 'System.String' of the parameter 'Fred' did not match the type of the da" & _

                                    "ta passed to the template.")

                        Else

                            Me._FredField = CType(data, String)

                        End If

                    End If

                End If

            End If

        End Sub

Thanks to Gareth Jones for listening to the occasionally loud input and making this happen!

Preprocessed templates are very cool (see this post). When I explained them to Karl Shifflett on the phone one day, once he got it he got excited and said “wow, this is just what I’ve been waiting for”. Preprocessed templates are very cool.

But, what if you don’t want to commit your entire development to Visual Studio 2010? What if you don’t want beta software on every dev machine. Preprocessed templates are part of Visual Studio. Ah, what to do?

Do what I do. Down target to 3.5.

The core concept of preprocessed templates is that when the custom tool runs you create a normal, normal, normal, normal .NET class that when run will produce your artifact (such as code). It’s a normal class (really). The custom tool runs either when you save, or when you explicitly run the tool. Take a look at the code so you understand the simplicity of what’s happening. But realize the specific code will change in Beta 2, so don’t get caught up by the current messiness.

You control the references and the project properties of this completely normal .NET class and assembly. You can set the target for this assembly to .NET 3.5. Every single thing you do in your development process, except the editing of templates and saving them, can be done in Visual Studio 2008 and .NET 3.5 (or potentially below, but LINQ is powerful in templates). You only need to have one boot or VPC in your organization that deals with the VS 2010 betas. I’m running it side by side on my dev box, but I would recommend you follow all the Microsoft warnings unless rebuilding systems is a favorite pastime.

Assuming you build the MEF preview against .NET 3.5, you can also use MEF in your templates.

This doesn’t mean you can directly use the “custom-tool-does-it-all” approach encouraged by VS 2008 (which is an approach I dislike). You still need a harness of some sort, and I really owe a blog post on that. But I’m heading to Nepal so it may be a while. In the meantime, perhaps one of the custom tool geeks can create a custom tool that knows how to run preprocessed templates, possibly through MEF. Oh, dear, that’s another post…and really, I need to pack… you would not want me to forget slippers…

Here is the initial public alpha release of the Community Generation Harness

AppVenture has two tools. AppVenture Foundations is the core tool we use in our business. We'd love to talk to you about it, but it's an entirely different lineage than the Community Generation Harness.

The Community Generation Harness is a freely available tool which we will move to an open source site if it gathers a community. It leans out over the cutting edge to show you what's possible with code generation and MEF. It's misnamed a bit, because it is actually a general purpose processing engine. Watch for more blog posts on how to customize it for your own use. And don't miss the ReadMe file. It explains what to do with the download.

OK, really, it’s cooler than sliced bread.

When you create any file in Visual Studio you have the option to run a custom tool. Visual Studio and add-ins use this tool to do extra work – often generating a dependent file. In Visual Studio 2010, if you create a T4 template there are two options for the custom tool that runs.

Option 1 – Text Template

This style is consistent with VS 2008 and the DSL Toolkit.

The plain style of T4 templates evaluates the template places the result as an output file. If you create a T4 template that is “Hello World” you get a dependent file with the specified extension that contains “Hello World”.

There are two steps of metadata to artifact transformation going on here. First, the template is transformed into normal .NET code. This code is emitted and run to produce the result. The result as a string is output into the file you see.

There are two transformation steps and two .NET compile steps (although the full compile of your output is delayed in C#). For example, if you output “Hello World” as a C# code, it’s not legal code so you get a compile error. You can also create templates that have .NET errors in the code of the template, and this creates errors in the interim emitted code when it is compiled.

Option 2 – Preprocessed Text Template

The second option is to create a preprocessed template, which uses a different custom tool than the text template. This custom tool does the first step – creates .NET code which when run will create your output. This code is output as the dependent file. If you create a “Hello World” template, you’ll see a bunch of gunk that runs the template and a TransformText method. Within the TransformText method, you’ll see GenerationContext.AppendLine(“Hello World”).

The class contains a good deal of additional gunk which frees the base class. You can inherit from any class you want. You can define the alternate base class either with the inherits attribute of the template directive, or in a separate partial class.

You need external code, a template harness of some sort, to create your actual output. This is very simple code: it creates an instance of your templates class, runs the TransformText method, and outputs the result to a file. More on harnesses coming here soon.

You can also define additional code in a partial class for your template. This can include attributes, such as MEF attributes. It can also can include properties that can be set from the outside when the template is run, or attributed to be automatically filled with MEF.

This is VS 2010 Beta 1 behavior. The code output as the preprocessed template will change significantly in Beta 2. A logical enhancement would be including support for a parameter directive which would automatically create this property for you. You’ll still have to supply data.

Why are Preprocessed Templates this so Cool?

The primary reason is that they let you get your hands on that emitted code. This is the code that actually runs, and code which frequently will contain compiler errors because of some dumb thing you do in the template. Often, the T4 engine correctly backtracks these errors into the template, and/or provides enough debugging. But both of these tasks sometimes come up short leaving you with a compile or debugging challenge. I also frequently drop into this code to take advantage of native Intellisense, then copying the code back into the T4 template.

It also makes running the T4 template much easier.

If you’re running within Visual Studio directly to get output, you’ll find many challenges around accessing your metadata. While the T4 Toobox on CodePlex.com does an amazing job circumventing these issues, it results in complex brittle templates that have a serious separation of concerns issue as they simultaneously access metadata, manage and output files, and define output code.

Instead, you can run templates through a harness of some type. This makes the process similar to that using tools such as CodeSmith or CodeBreeze. Unfortunately, the design of T4 and the single file generator that is used by Visual Studio combine to make writing a T4 harness for plain T4 templates extremely challenging and just mucky.

Preprocessed templates redefine this process. The preprocessed code is a normal .NET class and the harness calls its TransformText template like any other .NET code, grabs the string, and outputs the file. Outputting multiple files is simple, and the harness can adopt additional sophistication, such as MEF provided metadata or overwrite protection.

Eleven Great Things about Preprocessed T4 Templates

The first great thing about T4 preprocessed templates is that you get a syntax check on save, and a full compiler check as soon as you run the compiler (or on save in VB). With traditional templates, you know about problems in the template when you attempt to output code.

The second great thing about T4 preprocessed templates is that you have access to a base class. A custom base class can manage all the metadata for a family of templates using the same metadata and significantly improve reuse.

The third great thing about T4 preprocessed templates is that you have a partial class for any additional code or class attributes you might want to include.

The fourth great thing about T4 preprocessed templates is that they make writing a harness for T4 templates a few order of magnitude easier – making it very simple to do.

The fifth great thing about T4 preprocessed templates is that you can include T4 transformations within your application. It’s just .NET code – you can run it whenever, however, why-ever you want. This means T4 templates are not just for code anymore. You can use them for any metadata to artifact generation, such as form letters, as long as you can recompile and redeploy template changes. MEF can help here as well because you just need to distribute small dlls with the changes and variations.

The sixth great thing about T4 preprocessed templates is that they run equally well in the main .NET framework and Silverlight. Or even mobile.

The seventh great thing about T4 preprocessed templates is that they are easier to debug. You have access to the code that will actually run, allowing you to debug the actual failing code, not the T4 template from which that code was derived.

The eighth great thing about T4 preprocessed templates is understanding what’s really happening when you run your template code. The logic of your template can sometimes be obscured by the overlay of T4 template logic and output code logic. The preprocessed code let’s you better understand the logic you wrote into your template.

The ninth great thing about T4 preprocessed templates is that you can get Intellisense directly within the preprocessed output, regardless of the AddIns you have in play.

The tenth great thing about T4 preprocessed templates is that they are NOT restricted to .NET 4.0. By down-targeting the preprocessed output, you create a dll which can be run in any appropriate version of the .NET framework. A .NET 3.5 harness can easily run preprocessed templates. You ONLY need the VS 2010 Beta when you are altering templates. The rest can be done on machines running only VS 2008.

The eleventh great thing about T4 preprocessed templates is that they remain T4. They use the same simple ASP.NET template style. Microsoft is making an increasing commitment to T4 with its use in LINQ to Entities, and MVC. I anticipate T4 will crop up in many additional tools from both within in and outside Microsoft – with CodeBreeze already making a commitment to support it in the next version.

You can get a different take on preprocessed templates on the Clarius blog here and here.

Wow, I’m starting my second blog!

I plan to continue blogging about general .NET stuff and new technologies like Workflow and MEF on my personal blog at www.msmvps.com/blogs/kathleen. But I want to consolidate the code generation posts along with the AppVenture Community Generation Harness in a single location. My goal with this harness is to let it grow into an open source tool, and share the thinking behind it. I think the best location for this is the AppVenture site.

For clarity, AppVenture has two tools (which is not in itself very clear). AppVenture Foundations is our core tool which we use in business partnerships/consulting/etc. I’m very proud to be associated with this tool which pushes boundaries in interesting ways.

But both personally and with the full support of the rest of the AppVenture leadership team we want a tool available that offers a jumping off point for industry wide evolution of code generation. We think the community tool is an important first step.

I also plan to generally use this blog to post slides and sample code from user group talks.

Welcome!