[Profoundly Esoteric Image]

What’s new with T4 in Visual Studio 2012 Release Candidate

GarethJones — Tue, 05 Jun 2012 01:52:40 GMT

I’m a bit quicker off the mark than I was with our Beta as this is my first day back from vacation after our Release Candidate has launched. We have one final significant T4 feature to add for Visual Studio 2012 in addition to all of the stuff from out beta and developer previews, and it’s a doozy!

T4 template debugging

In past releases of Visual Studio, debugging T4 templates has been a little more work than we’d like, so we’ve addressed that in this release with a simple to use but full-featured debugging experience:

You’ll see the ‘Debug T4 Template’ menu item above on the context menu for the template in the Solution Explorer. There’s no need to set the debug flag on the template directive or any other special magic; just set a breakpoint in your T4 template and launch the debugger. You’ll have full access to step through your template code and look at variables in the locals window.

There’s also new service interface, IDebugTextTemplating, to allow folks who use T4’s Visual Studio API to call T4 asynchronously under the debugger and so build equivalent debugging facilities into their tools, plus a couple of new support pieces under the hood to enable all this whilst maintaining backward compatibility on our existing interfaces.

I hope you enjoy the new productivity of debugging your T4 templates in our release candidate!

Technorati Tags: T4,Visual Studio 2012,Release Candidate,Debugging

What’s new with T4 in Visual Studio 11 Beta?

GarethJones — Tue, 03 Apr 2012 02:14:01 GMT

Our beta release has been available for a couple of weeks now, so I thought it was about time I updated folks on what’s new for T4.

Everything below is in addition to the features and changes I noted in my previous post, What’s new with T4 in the Developer Preview of Visual Studio 11?

OK, here goes…

Directive processors are MUCH easier to build and more flexible
Directive processors are T4’s plug-in mechanism. They allow you to inject code into a template to pass and initialize parameters, or provide standard constructs within a template in a language-agnostic manner. However, they’ve been a bit fiddly to set up in the past and haven’t seen a lot of use. This time, we’ve made them much cleaner and easier.
- Directive processors can now be deployed as simple MEF components in a standard Visual Studio VSIX container. This means you can easily publish them on the Visual Studio gallery. There are new attributes [DirectiveProcessor] and [SupportedDirective] to make this easy. Look out for an example soon.
- Directive processors can now be built to run across Visual Studio versions as they only need to implement the new immutable interface type, IDirectiveProcessor.
- Directive processors can now add custom attributes to the underlying T4 class. For example, it’s now really easy to create a directive processor to decorate a runtime template with MEF exports. You simply implement the new method GetTemplateClassCustomAttributes(). I expect Kathleen to be all over this one!
Cleanliness features for runtime templates
We’ve finished the name transition from Preprocessed to Runtime templates in the beta including renaming the item templates and, as we’re now seeing a lot more usage of runtime templates, we’ve added a few cleanup features.
- You can now control the visibility of the generated class, using the new visibility property on the <#@ template #> directive with values public or internal. This means that if you’ve got runtime templates as part of a published assembly, they no longer have to be part of your public API.
- You can now turn off line pragmas for runtime templates with the new linePragmas property on the <#@ template #> directive with values true or false. This gives you more debugging options, as you can choose to either debug the original template or the generated code. This can also help if you’re finding the absolute filenames in pragmas are causing distracting merges under source code control.
UI Simplification
As part of Visual Studio 11’s overall effort to simplify the UI, we’ve moved the Transform All Templates button out of the previously cluttered Solution Explorer toolbar. You’ll now find it on the build toolbar and the build menu. It also blocks the UI a bit less than it used to when you have lots of templates in your solution.

We hope you enjoy these new features. As always, please give us feedback via Connect or UserVoice.

Technorati Tags: T4,Visual Studio 11 Beta,Code Generation

Some nice new getting started with T4 videos

GarethJones — Wed, 30 Nov 2011 01:22:51 GMT

Kalle over at abstractiondev has a nice series of videos getting started with T4 and developing a rich set of metadata to drive systematic generation.

http://abstractiondev.wordpress.com/demo-videos/

He’s also not afraid to promote his ideas with conviction, which is refreshing these days!

Technorati Tags: T4,Videos

What's new with T4 in the Developer Preview of Visual Studio 11?

GarethJones — Sun, 25 Sep 2011 12:03:33 GMT

In among all the excitement of new ALM features like integrated Code Review and MyWork to manage your daily workflow in the developer preview, there are, of course, a few nice new features for T4.

First of all, a naming change that's underway. We've heard from you that 'Preprocessed' isn't the clearest choice of name for our templates, so we've switched to a new naming scheme:

Design-time templates - Templates that run in the VS IDE to produce output based directly on the template content
Run-time templates - Templates that are preprocessed in the VS IDE to produce a class that you incorporate into your application for use at runtime. Calling a method on the class produces output based on the template content.

For the Developer Preview, you'll see this change mostly in our documentation; the new terms will find their way into the product UI in time for Beta.

Now on to new features we've added in the preview:

1) Improved template inheritance for runtime templates that need access to features of the host

Previously, if you had a runtime template that declared itself as host-specific,

<#@ template hostSpecific="true" #>

it was hard to reuse the template through inheritance cleanly. Derived templates that also declared host-specific would create a second 'Host" member that would hide the one from the base class, giving a warning.
To address this, we've added a third value for host-specific, "TrueFromBase", that makes the engine generate a host specific template, but expects the 'Host" property to come from the base class.

We've also made the comments generated from runtime templates more helpful.

2) Better error processing for design-time templates

When your design-time template gets past the compile stage and starts to run the compiled code, T4 now accurately reports line numbers for any exceptions that get thrown.
Don't forget to set debug="true" to make sure the compiler is emitting line number information.

3) COM Service helper

For folks using host-specific templates to access VS services, there've been a few reports of exceptions being thrown for one or two specific services.
Typically, it turns out that these services are written in managed code, but exposed over COM and then marshaled to T4's AppDomain over .Net Remoting. (Phew!)

This rather complex path leads to the exceptions, so we've included a simple extension method on IServiceProvider that you can use to get hold of those services and force them to behave properly:

    public static class ServiceProviderExtensions
    {
        public static Object GetCOMService(this IServiceProvider provider, Type type)
    }

Just call this method instead of the regular GetService() method and your COM troubles should be over.

4. Item templates now support LINQ out of the box.

We've updated our VS item templates, so when you add a new T4 template to your VS project, you'll automatically get all the directives you need to use LINQ right off the bat.

<#@ assembly name="System.Core" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="System.Text" #>
<#@ import namespace="System.Collections.Generic" #>

5. Correct disposal of MEF container when T4 AppDomain recycles.

We provide a simple helper method (CompositionServices.InitializeServices() ) to set up a MEF composition container in the T4 AppDomain if you want to use VS' MEF components from your template.

T4 has a heuristic that decides when to recycle the secondary AppDomain for design-time templates. This one is really more of a bug fix, but I'll mention it just because not many folks know about the MEF setup helper.
The fix is that now when the AppDomain gets recycled, the MEF container is correctly Disposed.

We'll have some more features to talk about once the Beta comes along, but in the mean time, I hope you enjoy these improvements to T4 in our Developer Preview.

Technorati Tags: T4,VS11,Visual Studio

DevArt joins the T4 Template Editor Fray

GarethJones — Thu, 02 Jun 2011 01:32:34 GMT

We’ve now got a third contender in the Visual Studio T4 Editor space. The good folks over at DevArt have joined the race. From their press release:

Devart today releases a new powerful Visual Studio add-in for editing T4 templates with syntax highlighting, intellisense, code outlining, and all features of first-class text editor add-in for Visual Studio. It provides very high performance and makes creating T4 templates easier and faster.

With this new add-in, Devart offers a fast and easy way to create and edit T4 templates with multilevel template including, convenient template navigation, and rich code editing features.

So here’s my updated table of T4 editors (still in strictly alphabetical order)

	Visual Studio 2010	Visual Studio 2008
Clarius Consulting	Get it	Get it
DevArt	Get It	Get It
Tangible Engineering	Get it	Get it

Keep on transforming those templates.

Technorati Tags: T4,VST4,T4 Editor,Visual Studio

Pluralcast Podcast on T4

GarethJones — Fri, 06 May 2011 20:22:56 GMT

A few weeks ago, I recorded a podcast about T4, and how it’s being used inside and outside Microsoft with the estimable David Starr, who I happened to meet up with at the recent MVP Summit.

You can check it out in the PluralSight Pluralcast blog. Enjoy.

http://www.pluralsight-training.net/community/blogs/pluralcast/archive/2011/04/07/pluralcast-39-t4-with-gareth-jones.aspx

Technorati Tags: T4,PluralCast,PodCast,VST4

New T4 blog and new T4 samples

GarethJones — Thu, 14 Apr 2011 01:04:51 GMT

Some of you may have noticed that we’ve launched a new T4 official blog over at http://blogs.msdn.com/b/t4.

We wanted a single place to consolidate information about T4, whether it be from my team that produces the core T4 engine or the teams within Microsoft that build on top and use T4 as their code generation strategy such as ADO.Net Entity Framework, WCF RIA Services, ASP.Net MVC Scaffolding, TFS Team Test, etc. I’ll probably cross-post T4 entries there from now on.

Mårten Rånge has posted a great series of T4 educational samples to help folks get off to a good start. Check them out!

Technorati Tags: T4,VST4,Visual Studio,Code Generation

Hiring again

GarethJones — Fri, 25 Mar 2011 07:33:13 GMT

Folks, if you want to work on Visual Studio, here's your chance.

We've two openings for senior developers on my team working on building WPF-based experiences and the underlying infrastructure for agile/enterprise team dev tools.

http://bit.ly/gb8P76 && http://bit.ly/gjHsqC

Apply through the jobs site and ping me or just get in touch directly.

C'mon, let's see those resumes.

Technorati Tags: Hiring,Vacancies,Visual Studio,agile,enterprise team,WPF

T4 vs Razor – what’s the skinny?

GarethJones — Fri, 11 Mar 2011 02:43:30 GMT

You might have noticed in the recent storm of Web Tools releases that there’s a groovy new kid on the template engine block – Razor.

A few customers have been asking folks on both teams some questions around this, such as the following.

Why do you have two engines?
When should I use each of these two engines?
When can I expect <feature X> from one engine to appear in the other one?

So the T4 and Razor teams got ourselves together in a room and came up with a common way to express how we think about some of these things. Here’s what we came up with:

	T4	Razor
Design-time hosting	Visual Studio & co-installed tools	Anywhere
Runtime options	Preprocessed templates	Rehost Razor engine
Recommended for generating which file types?	Not markup	Markup
Optimized for	Generating arbitrary code assets	Efficient HTML generation
Productivity aids	Class feature blocks (virtual methods) Include directive (template fragment libraries)	Helpers (static standalone code) Sections (overridable content)
Extensibility	Custom directives VS Service Custom host	Customize or replace most elements of the stack Custom host
Editing	3rd party editors	VS built-in (HTML output optimized)
Core control languages	C#/VB	C#/VB

In short, we have two engines ‘cos they’re optimized for different use cases.

Razor uses its implicit knowledge of the type of output it’s generating to allow it to disambiguate control code from output markup and so use a much terser and more pleasing syntax.
T4 is designed to generate arbitrary text output, which often means that the output you’re generating and the control language will be the same; consequently, it has to use more explicit demarcation syntax.

We’ll keep adding individual syntax and features that make sense for those separate use cases, but we’ll try and avoid being different at a conceptual level just for the sake of it.

Technorati Tags: T4,Razor,Visual Studio,Template Engines

Scaffold your ASP.NET MVC 3 project with the MvcScaffolding package and customize with T4

GarethJones — Sat, 15 Jan 2011 23:15:01 GMT

Steve Sanderson has a nice post up about a project he's working on with the estimable Scott Hanselman.

It's a NuGet package that provides an even easier on-ramp to development with the just-released ASP.NET MVC3 framework.

In their words, it quickly generates a basic outline of your software that you can then edit and customize.

And even cooler, what it generates can itself be customized by editing a bunch of T4 templates. Sweet!

Check it out by installing the package with NuGet: Install-Package MvcScaffolding.

Technorati Tags: T4,ASP.NET,MVC3

VS2010 SP1: T4 Improvements Summary

GarethJones — Sat, 15 Jan 2011 00:43:44 GMT

Over the last few posts, I've talked about the exciting improvements we've made to T4 Text Templating in Service Pack 1 for Visual Studio 2010.

Here's a quick roundup:

Firstly, T4 no longer locks referenced assemblies in memory, meaning it's much easier to use reflection in T4 templates and to use compiled helper libraries.

Then I posted a series explaining how to use template inheritance for greater template reuse and easier template customization

In Part I, I started by setting the scene of why you'd want inheritance and setting up some metadata to drive an example template from.

In Part II, I put together a T4 preprocessed template that's designed to be reusable and customizable with natural override points.

In Part III, I showed how to exploit the customization points to produce code that's specific to a new project reusing a base template.

In Part IV, I wrapped up by showing how to use a helper class to apply the same technique used in preprocessed templates with regular T4 templates.

I hope you're as excited as we are about these improvements - we really think they make working with T4 a smoother experience.

Technorati Tags: T4,Visual Studio 2010 SP1

VS2010 SP1: T4 Template Inheritance Part IV – Regular template inheritance

GarethJones — Tue, 04 Jan 2011 09:29:46 GMT

I promised in the last post that I’d show how to do template extensibility and customization using inheritance with regular templates, rather than the preprocessed kind, so here goes.

The preprocessed solution was a three-layer design.

The base preprocessed template, DataClass.tt provided the code generation smarts to spit out a customizable C# class from some type description metadata.
The Author.tt and Book.tt preprocessed templates provided specializations of this template for metadata instances (for Book and Author in some imaginary library system) and allowed application-level customization.
Finally the preprocessed templates were used at an application level via simple harness templates, BookConsumer.tt and AuthorConsumer.tt

This system works quite well, but it’s a bit clumsy, needing as it does harness templates to call the preprocessed ones and smearing application concepts (Book and Author) across two of its layers. It would be nice to move to just two layers

The base layer – provides application-independent template base classes as preprocessed templates
The application layer – adds application concepts and provides application-wide customizations

I scratched my head for a couple of hours and came up with this:

Much cleaner! So what’s different that’s enabled us to dispense with the intermediate ‘Templates’ project?

Application-level templates (Book.tt, Author.tt) derive directly from DataClass.tt preprocessed template class.
DataClass.tt preprocessed template class derives from custom adapter class TextTransformation.cs
TextTransformation.cs derives from T4’s built-in base class TextTransformation.
BaseTemplates project references T4’s SDK assembly (You’ll need the Visual Studio 2010 SDK for this variant)

Here’s how that inheritance hierarchy looks:

OK, so that’s all the dirty mechanics; let’s take a look at the new, single-layer application templates:

   1: <#@ template debug="false" hostspecific="false" language="C#" inherits="BaseTemplates.DataClass" #>

   2: <#@ assembly name="$(SolutionDir)\BaseTemplates\$(OutDir)\BaseTemplates.dll" #>

   3: <#@ import namespace="BaseTemplates" #>

   4: <#@ include file="ProjectSpecific.t4" #>

   5: <#@ output extension=".cs" #>

   6: <#

   7: this.Description = new TypeDescription

   8:             {

   9:                 Name="Author",  Description="A class to carry data about an author in a library system.",

  10:                 Properties=

  11:                 {

  12:                     new TypePropertyDescription{Name="ID",              Type="string",    Description="The ID of the author."},

  13:                     new TypePropertyDescription{Name="GivenName",     Type="string",    Description="The given name of the author."},

  14:                     new TypePropertyDescription{Name="FamilyName",    Type="string",    Description="The family name of the author."},

  15:                 }

  16:             };

  17: #>

  18: namespace TemplateUse

  19: {

  20:     using System;

21:

  22: <#

  23:     PushIndent();

  24:     base.TransformText();

  25:     PopIndent();

  26: #>

  27: }

This is essentially a coalescing of the Book.tt and BookConsumer.tt templates from the previous version of the solution, but with much less T4 infrastructure on show. Once again, the project-specific customizations for richer comments and Serialization are included from ProjectSpecific.t4, which is unchanged, and all of the application-level code is now in a single, clean layer.

I think this gives us a really nice pattern now.

Package up your reusable, extensible templates as preprocessed templates in a design-time support library.
Use template inheritance from either regular OR preprocessed templates, as your solution demands.

Here’s the updated demo solution :

For the curious, what’s going on under the hood here? The key to this variation is that regular T4 templates MUST be derived ultimately from the built-in T4 base class, Microsoft.VisualStudio.TextTemplating.TextTransformation (top left in the class diagram). Preprocessed templates were specifically designed NOT to take a dependency on Visual Studio, so they lift this restriction and instead rely on duck-typing. They simply require a base class with the same set of methods as the built-in one.

So why can’t DataClass inherit directly from the built-in base? It turns out that the duck-typing match is not exact and in particular, the calls to a utility class, ToStringHelper, are instance-based in the case of preprocessed templates and static in the case of regular templates. The adapter class simply reroutes instance-based calls to the static class. With this one little trick, regular templates can inherit from any preprocessed template that in turn inherits from the adapter class.

Technorati Tags: T4,Visual Studio 2010 SP1

VS2010 SP1: T4 Template Inheritance Part III – Customizing The Template

GarethJones — Tue, 04 Jan 2011 02:56:16 GMT

Last time, in Part II, I described a highly structured approach to creating and harnessing a preprocessed template to generate a simple C# class from metadata. I put lots of nice extensibility points in that template and now we’re going to exploit them to show how easy it gets to be to customize a template once you have such a structure in place.

Here’s an edited reminder of the code we wanted to generate:

   1: /// <summary>

   2: /// A class to carry data about a book in a library system.

   3: /// </summary>

   4: /// <remarks>

   5: /// This code generated by the DataClass.tt template - DO NOT MODIFY THIS CODE.

   6: /// </remarks>

   7: [Serializable]

   8: internal partial class Book

   9: {

  10:     /// <summary>

  11:     /// The title of the book.

  12:     /// </summary>

  13:     /// <remarks>

  14:     /// This code generated by the DataClass.tt template - DO NOT MODIFY THIS CODE.

  15:     /// </remarks>

  16:     public string Title { get; set; }

17:

  18:   … More methods elided …

41:

  42: }

We’d like all of the summary comments to contain a reminder not to edit generated code and we need our class to be marked as internal and Serializable.

If we take a look at the customization points in our base template, DataClass.tt, we’ll see we have what we need. We can override Summary() and ClassHeader() to add the extra text we need:

   1: <#+

   2: // ---------------------------------------------

   3: // Override some of the snippet methods from DataClass.tt to change the template's behavior.

   4: // ---------------------------------------------

5:

   6: /// <summary>

   7: /// Override the summary method to remind readers more regularly that this code is auto-generated by a tool

   8: /// </summary>

   9: public  override void Summary(string comment)

  10: {

  11:     base.Summary(comment);

  12: #>

  13: /// <remarks>

  14: /// This code generated by the DataClass.tt template - DO NOT MODIFY THIS CODE.

  15: /// </remarks>

  16: <#+

  17: }

18:

  19: /// <summary>

  20: /// Override the class header method to make the generated class partial, internal and Serializable

  21: /// </summary>

  22: public  override void ClassHeader(TypeDescription type)

  23: {

  24: #>

  25: [Serializable]

  26: internal partial class <#= type.Name #>

  27: <#+

  28: }

  29: #>

Note that Summary() ‘s override is purely additive, as it calls the base implementation to get the regular summary before adding the extra comment. By contrast, the override of ClassHeader()redefines the output snippet. It does this as the accessibility of the type isn’t independently customizable without replacing the whole declaration line. If you keep your output snippets down to a few lines of code at a time, then this kind of thing generally doesn’t compromise maintainability, and means that you don’t need to try and anticipate every last customization need in advance.

The next question is, where to put these overrides? The virtual methods are defined in DataClass.tt and then individual template classes derived from that are created in Book.tt and Author.tt where the specific metadata is defined. As these would be project-wide customizations, I put them in a separate file, ProjectSpecific.t4. To activate customization, it’s then a simple matter of including that file with a single line in each template class definition. In the sample I posted as part of Part II, I only included it in the Author.tt file, not Book.tt in order to demonstrate the difference in generated code with and without it. An alternative would have been to put the overrides in an intermediate base class, but that seemed overkill for this sample – either way, there is only a single source for the code.

To see the difference with and without, first you regenerate the Templates project, to take advantage of template changes, then build that project to compile the precompiled templates. Finally regenerate the simple harness templates in the TemplateUse project. You could use the T4/msbuild integration from the Visualization and Modeling SDK to automate this process. To be clear, you don’t need to separate the Templates and BaseTemplates projects; I just wanted to illustrate the idea of a central repository of templates being customized on a per-project basis.

We’ve now seen how to use the new assembly non-locking and T4 preprocessed template inheritance features in Visual Studio 2010 SP1 together to set out a clean, structured approach to template reuse and extensibility for medium-scale code generation projects.

Can we go further and apply the same techniques to regular T4 templates? I’ll look at that next time…

Technorati Tags: T4,Visual Studio 2010 SP1

VS2010 SP1: T4 Template Inheritance Part II – The Core Template

GarethJones — Tue, 04 Jan 2011 02:12:02 GMT

Last time, I outlined my scenario – we have a template that produces a very vanilla C# class from metadata and we’d like to customize it to produce something more directly applicable to our current project. Of course, we could always just copy the standard template into our project and hack around a little until it meets our needs. With simple templates, that’s often the right thing to do, however once you start to do a lot of code generation, copy/paste reuse just doesn’t cut it and you need some structure. You can find my complete sample attached to this post.

The first thing I did was to switch to precompiled templates (introduced in Visual Studio 2010) for my core class-generating template. A precompiled template gives me a class that you can instantiate and then call the TransformText() method on. This method will then produce the same output as a regular template and you can use a simple harness to call it and write the output to disk. I’m using a regular T4 template as my harness because it’s the easiest way to get a string written to disk as a file in the project system inside Visual Studio. You can add a preprocessed T4 template from the Visual Studio 2010 Project/Add New Item dialog.

Here’s the regular harness template, using a preprocessed template class called Book, generated from a preprocessed template called Book.tt

   1: <#@ template debug="false" hostspecific="false" language="C#" #>

   2: <#@ output extension=".cs" #>

   3: <#@ assembly name="$(SolutionDir)Templates\$(OutDir)Templates.dll" #>

   4: <#@ assembly name="$(SolutionDir)BaseTemplates\$(OutDir)BaseTemplates.dll" #>

   5: <#@ Import namespace="Templates" #>

   6: <#@ Include File="$(SolutionDir)BaseTemplates\Helpers.t4" #>

   7: namespace TemplateUse

   8: {

   9:     using System;

  10: <#

  11:     var book = new Book();

  12:     this.PushIndent();

  13:     this.WriteLine(book.TransformText());

  14:     this.PopIndent(); #>

  15: }

I generally put preprocessed templates in a separate project/assembly as you don’t usually want them leaking into your actual application. Here you can see I’ve put them in the Templates and BaseTemplates projects which I’m referring to via VS 2010’s new ability to reference assemblies via project macros such as $(SolutionDir). This style of working is much, much easier now with Visual Studio 2010 SP1, as we’ve fixed the assembly locking issues that meant you had to keep restarting your IDE.

I’m using a helper function from my standard function library (Helpers.t4) to make indenting the code a bit more standardized and customizable – I’ll come back to that as a customization point in another post. The main thrust of this wrapper is that it simply uses WriteLine() to spit out the code from the preprocessed template class.

So what’s in the Book class? Let’s have a look at the preprocessed template that generated it:

   1: <#@ template debug="false" hostspecific="false" language="C#" inherits="BaseTemplates.DataClass" #>

   2: <#@ assembly name="$(SolutionDir)\BaseTemplates\bin\debug\BaseTemplates.dll" #>

   3: <#@ import namespace="BaseTemplates" #>

   4: <#@ output extension=".cs" #>

   5: <#

   6: // Copyright (C) Microsoft Corporation.  All rights reserved.

   7: this.Description = new TypeDescription

   8:             {

   9:                 Name="Book",  Description="A class to carry data about a book in a library system.",

  10:                 Properties=

  11:                 {

  12:                     new TypePropertyDescription{Name="Title",         Type="string",    Description="The title of the book."},

  13:                     new TypePropertyDescription{Name="AuthorID",      Type="string",    Description="The ID of the author of the book."},

  14:                     new TypePropertyDescription{Name="ISBN",          Type="string",    Description="The standard ISBN number of the book."},

  15:                     new TypePropertyDescription{Name="CopiesOwned",   Type="int",       Description="The number of copies the library owns."}

  16:                 }

  17:             };

  18: base.TransformText();

  19: #>

You can see straightaway that this is mostly just the metadata set-up we described last time. All of the real work is being done in the base template that’s referenced in the <#@ template inherits=BaseTemplates.DataClass” #> directive. That template defines a contract (in the loosest sense of the word) that says you have to set its Description property to a piece of metadata before calling the base’s TransformText() and it will generate a matching class for you. Here it is:

   1: <#@ template language="C#" #>

   2: <#@ import namespace="System.Collections.Generic" #>

   3: <#@ include file="CSharpHelpers.t4" #><#

   4: // -----------------------------------------------------------------------------

   5: // Template to create a simple C# data carrier class from an instance of datatype description metadata

   6: // -----------------------------------------------------------------------------

7:

   8: if (this.Description == null)

   9: {

  10:     this.Error("Set the Description property on this template to an instance of the class TypeDescription.");

  11: }

  12: else

  13: {

  14:     // Define the overall structure of a class.

  15:     // Generally this should have no template boilerplate in it, so the structure is clear and simple.

  16:     Summary(this.Description.Description);

  17:     ClassHeader(this.Description);

  18:     OpenBrace();

  19:     foreach (var property in this.Description.Properties)

  20:     {

  21:         Property(property);

  22:         NewLine();

  23:     }

  24:     CloseBrace();

  25: }

  26: #>

  27: <#+

28:

  29: // Control properties that drive the template

  30: public TypeDescription Description { get; set; } // Description that this template uses.

31:

  32: // -----------------------------------------------------------------------------

  33: // Template snippet functions for the individual pieces of a class

  34: // Snippets are not indented at all - it is the responsibility of the calling structural method to set correct indenting.

  35: // -----------------------------------------------------------------------------

36:

  37: /// <summary>

  38: /// Generation method to define the template snippet for a summary comment

  39: /// </summary>

  40: public virtual void Summary(string comment)

  41: {

  42: #>

  43: /// <summary>

  44: /// <#= comment #>

  45: /// </summary>

  46: <#+

  47: }

48:

  49: /// <summary>

  50: /// Generation method to define the template snippet for a property declaration

  51: /// </summary>

  52: public virtual void Property(TypePropertyDescription property)

  53: {

  54:     Summary(property.Description);

  55: #>

  56: public <#= property.Type #> <#= property.Name #> { get; set; }

  57: <#+

  58: }

59:

  60: /// <summary>

  61: /// Generation method to define the template snippet for the declaration line of a class

  62: /// </summary>

  63: public virtual void ClassHeader(TypeDescription type)

  64: {

  65: #>

  66: public class <#= type.Name #>

  67: <#+

  68: }

  69: #>

The key here is structure. The template has an initial control block that validates its metadata and then defines the logic for generating a class from the metadata provided. That logic is written as ordinary procedural code and has no template boilerplate in it at all. I find this separation of core control logic from output text to be key in keeping larger templates maintainable. The control code uses a few simple helpers (OpenBrace, CloseBrace, NewLine) to avoid clumsy WriteLine statements and literal strings. This could form the start of a language-agnostic approach to structuring templates, although I’m not going to go down that path here.

The control code then calls out to various methods defined in class feature blocks that write snippets of the output using standard boilerplate syntax. Notice that each of these methods is defined as a virtual method. Here we have the key to our extensibility story. We can derive from this template class and replace just the pieces of output generation that we want without disturbing any others or the core logic. In fact, it’s probably a good idea to move that core logic into a virtual method of its own as well so it can be independently customized without disturbing the snippets.

Notice that none of the ouput snippet methods do any indenting – they all assume zero external indentation and leave their callers to manage it. That way you can build up a library of output methods and mix and match them from different pieces of control logic. You could also break down their parameters to only use simple types so they were independent of specific forms of metadata – it’s a balance between readability and reuse here.

This time, we’ve seen how the core template works to generate vanilla class code in a structured, extensible manner. Next time we’ll look at taking advantage of that extensibility to create the custom class we asked for in Part I.

Technorati Tags: T4,Visual Studio 2010 SP1

VS2010 SP1: T4 Template Inheritance Part I – Sample Metadata

GarethJones — Tue, 04 Jan 2011 00:48:05 GMT

We’ve done a bunch of work on T4 in Visual Studio 2010 SP1 to enable template inheritance.

A reasonable question at this point would be

“Why would you want inheritance in your text templates?”

Well, the typical reason would be the same as with any other code – because you want reuse and extensibility between a family of templates that have some significant similarities. It’s really nice to be able to customize a template just by overriding a method as you would with any other O-O system. Oleg Sych has an example of such a system on his excellent blog that works well with previous versions of T4 using nested classes, but I like to think the latest version of T4 makes it all a little bit easier.

I’m going to walk through a couple of examples of using inheritance with a themed sample, so let’s have a look at it. I’ve previously discussed using simple C# data structures to drive a template. This time I’ve got a couple of classes to provide metadata for simple data structures:

   1: public class TypeDescription

   2:   {

   3:       public string Name { get; set; }

   4:       public string Description { get; set; }

   5:       public List<TypePropertyDescription> Properties =

   6:                  new List<TypePropertyDescription>();

   7:   }

8:

   9:   public class TypePropertyDescription

  10:   {

  11:       public string Name { get; set; }

  12:       public string Type { get; set; }

  13:       public string Description { get; set; }

  14:   }

To keep things simple, a type is essentially jus a named and described bunch of properties. You can imagine using something like this to generate C# DAL classes, SQL schema creation scripts, ORM mappings and other typical application paraphernalia.

Here’s an example of populating the structure:

   1: this.Description = new TypeDescription

   2: {

   3:   Name="Book",  Description="A class to carry data about a book in a library system.",

   4:   Properties=

   5:   {

   6:     new TypePropertyDescription{Name="Title",         Type="string",    Description="The title of the book."},

   7:     new TypePropertyDescription{Name="AuthorID",      Type="string",    Description="The ID of the author of the book."},

   8:     new TypePropertyDescription{Name="ISBN",          Type="string",    Description="The standard ISBN number of the book."},

   9:     new TypePropertyDescription{Name="CopiesOwned",   Type="int",       Description="The number of copies the library owns."}

  10:   }

  11: };

Let’s say I’m going to generate a simple C# class from this metadata and I have a standard template that generates the following class:

   1: /// <summary>

   2: /// A class to carry data about a book in a library system.

   3: /// </summary>

   4: public class Book

   5: {

   6:     /// <summary>

   7:     /// The title of the book.

   8:     /// </summary>

   9:     public string Title { get; set; }

10:

  11:     /// <summary>

  12:     /// The ID of the author of the book.

  13:     /// </summary>

  14:     public string AuthorID { get; set; }

15:

  16:     /// <summary>

  17:     /// The standard ISBN number of the book.

  18:     /// </summary>

  19:     public string ISBN { get; set; }

20:

  21:     /// <summary>

  22:     /// The number of copies the library owns.

  23:     /// </summary>

  24:     public int CopiesOwned { get; set; }

25:

  26: }

Now on a new project, I decide that I need my data class to be serializable and that I want regular reminders not to edit the generated code (people don’t pay a lot of attention to the top of the file as it turns out). I’d like the following:

   1: /// <summary>

   2: /// A class to carry data about a book in a library system.

   3: /// </summary>

   4: /// <remarks>

   5: /// This code generated by the DataClass.tt template - DO NOT MODIFY THIS CODE.

   6: /// </remarks>

   7: [Serializable]

   8: internal partial class Book

   9: {

  10:     /// <summary>

  11:     /// The title of the book.

  12:     /// </summary>

  13:     /// <remarks>

  14:     /// This code generated by the DataClass.tt template - DO NOT MODIFY THIS CODE.

  15:     /// </remarks>

  16:     public string Title { get; set; }

17:

  18:     /// <summary>

  19:     /// The ID of the author of the book.

  20:     /// </summary>

  21:     /// <remarks>

  22:     /// This code generated by the DataClass.tt template - DO NOT MODIFY THIS CODE.

  23:     /// </remarks>

  24:     public string AuthorID { get; set; }

25:

  26:     /// <summary>

  27:     /// The standard ISBN number of the book.

  28:     /// </summary>

  29:     /// <remarks>

  30:     /// This code generated by the DataClass.tt template - DO NOT MODIFY THIS CODE.

  31:     /// </remarks>

  32:     public string ISBN { get; set; }

33:

  34:     /// <summary>

  35:     /// The number of copies the library owns.

  36:     /// </summary>

  37:     /// <remarks>

  38:     /// This code generated by the DataClass.tt template - DO NOT MODIFY THIS CODE.

  39:     /// </remarks>

  40:     public int CopiesOwned { get; set; }

41:

  42: }

Next time, I’ll show you how to achieve this customization without substantially modifying the original template.

Technorati Tags: T4,Visual Studio 2010 SP1

VS2010 SP1: T4 no longer locks assemblies in memory

GarethJones — Sat, 11 Dec 2010 09:56:00 GMT

I’m pleased to say that we made a few nice improvements to our T4 text templating engine in Visual Studio 2010 SP1 (you can find the beta here).
Chief among them is resolving an assembly locking issue that more than a few customers have told us has caused them pain.

The most typical cases for folks to run across this are:

when you have a library of code gen helper functions that you want to use from various templates scattered across your solution
when you’re using reflection inside a template to generate one part of your solution from the output of another part.

The problem manifests when you use the <#@ assembly #> directive to load one of your assemblies into a template. You find yourself stuck next time you try to build your solution. The template has locked that assembly in memory and when you make a change to update a helper, you get a build error as the locked assembly can’t be overwritten.

In Service Pack 1, we’ve borrowed the ASP.NET assembly shadowing technique, so a temporary copy of your assembly is always loaded rather than the original binary – hey presto, your build should always work now.

Are there any gotchas?

For most folks, the shadowing behavior should just work invisibly. However, if your template happens to take a dependency on the exact physical path of a referenced assembly (perhaps to sneakily load another assembly in a related directory), then you’re going to find a change in behavior. You’ll now be getting a path somewhere under %TEMP%, which is probably not what you were expecting. If it’s not convenient to refactor your logic, you can turn off shadowing by setting a value under the following registry key (the Wow6432Node piece is only for 64-bit OSes):

HKEY_LOCAL_MACHINE\SOFTWARE\[Wow6432Node]\Microsoft\VisualStudio\10.0\TextTemplating

Set the string value ShadowCopy=false and you’ll be returned to the pre service pack behavior.

Enjoy…

Technorati Tags: T4,Visual Studio 2010 SP1,Assembly Locking

WCF RIA Services updates T4 Code Generator

GarethJones — Fri, 03 Dec 2010 00:22:47 GMT

As it’s the Silverlight Firestarter event today, the very cool WCF RIA Services team have released a new version of their toolkit.

You can get the general skinny at Jeff Handley’s blog, but the bit that caught my attention was that they have updated their T4 code generator templates.

You can get more detail on that at Varun Puranik’s blog.

Nice.

Technorati Tags: T4,RIA Services,Silverlight

Maintenance-Free Mocking for Unit Testing with EntityFramework 4.0

GarethJones — Sat, 21 Aug 2010 05:23:26 GMT

Rab Hallett has a nice tool in the VS Gallery that uses T4 templates to generate mocks for unit-testing EF-based applications

Maintenance-Free Mocking for Unit Testing with EntityFramework 4.0

Technorati Tags: T4,Entity Framework,Unit Testing,Mock Objects

Visualization and Modeling Feature Pack with T4 Code Generation

GarethJones — Tue, 08 Jun 2010 00:26:03 GMT

As Jason Zander and Cameron have announced, we've just released the first Feature Pack for Visual Studio 2010, the Visualization and Modeling Feature Pack.

This pack is available to all MSDN subscribers and among a host of other great features, adds T4-based code generation to our UML static class diagrams.

This add-in works with the C# profile that we shipped with Visual Studio to generate code.

It's a great example of how you can rather easily build a profile yourself to add yet more metadata to your UML model and enrich the code generation further.

You can find all the detail on editing and customizing the templates here: http://msdn.microsoft.com/library/ff657795.aspx

Enjoy.

Technorati Tags: Visual Studio,T4,UML,Code Generation

What's new in T4 in Visual Studio 2010

GarethJones — Thu, 15 Apr 2010 08:54:22 GMT

OK, Visual Studio 2010 is well and truly released, so I thought I'd better catalog what goodness is in the box for all you T4 fans out there..

For template authors:

Preprocessed templates to allow embedding of template-based generation in arbitrary applications without a runtime T4 dependency. There is a new custom tool, new service APIs and new engine APIs to support this feature.
Runtime error handling is improved, with better handling of null expression blocks and fewer exceptions being eaten.
Include directives and Assembly directives now support both Windows environment variables and VS Macro variables.
Include directives and Assembly directives now resolved from VSIX Visual Studio extensions downloaded from VS gallery.
Include directives are now also resolved relative to the file that they are declared in to support libraries with relative includes.
Templates always use C#/VB 4.0 and .Net 4.0 types - language version is no longer needed.
Project/Add item templates for C# and VB and Web projects for both regular and preprocessed templates.
T4 now works in Web Site projects.
Generate All Files only runs the T4 custom tools in your project, not arbitrary ones like WPF.
The service tag project stamp is no longer written willy-nilly by T4.
New CompilerOptions flag to the template directive allows arbitrary flags to be sent to the template compiler, allowing optionstrict, optioninfer, optionexplicit etc. to be set for VB.
VS's Custom Tool Namespace is available in CallContext with the tag "NamespaceHint".
Templates no longer support the neutral culture, rather they always go to the invariant culture.
T4-MsBuild to transform your templates at build time.
The parser requires that templates with a class feature block finish with a class feature block to avoid boilerplate write statements hanging free at the end of the class causing hard-to-debug errors.
T4's assembly set is completely separated from the containing project's assembly set to avoid picking up the wrong assemblies when a project targets previous framework versions. Project assemblies are no longer used to resolve template assembly directives.
Assembly references will resolve from Visual Studio's PublicAssemblies folder.
WindowsBase.dll automatically referenced from templates.
Ability to use VS MEF components in the T4 AppDomain - also new CompositionServices helper class to make setting this up simple.
The options page is fully localized.
Better error messages when templates are included from internet zones or downloaded templates are included.
The Generate All Files button is disabled while a build is in progress so there aren't any clashes.

For custom tool builders:

Hosts can implement ITextTemplatingSessionHost to signal to the engine that they can provide a dictionary of arbitrary user data for the lifetime of the processing session. The data is accessed via a new Session property on the TextTransformation base class.
The built-in VS host implements ITextTemplatingSessionHost and provides a default session implementation to pass data from custom tools into templates while they run in the secondary appdomain, including resolving any necessary assemblies.
New "Parameter" directive with Name and Type properties, similar to the one in the GAX host. This allows custom tools to pass data to templates in a standard way. It resolves from the Session dictionary, the Host via ResolveParameterValue or the CallContext.
T4 interfaces have been split out into a separate assembly to facilitate longer term versioning without taking a dependency on T4's implementation assemblies.
RequiresProvidesDirectiveProcessor uses a new order for processing required parameters to support richer overriding.
BaseCodeGeneratorWithSite now exposes both GlobalServiceProvider and SiteServiceProvider members.
New base class BaseTemplatedCodeGenerator makes it even simpler to create a T4-based custom tool with one override.
ProvideCodeGeneratorExtension attribute makes it easy to hook up custom tools to the web site project system.
Public access to the CacheAssembliesOptionsString in the Engine class to help control caching without magic strings.
Directive Processors support IRecognizeHostSpecific interface to participate in decisions around forcing this flag on.
The correct system implementation of IVsSingleFileGenerator is used rather than a T4 internal one.
Access to the internals of the Visual Studio built-in host via ITextTemplatingComponents service interface.

For DSL Tools users:

ModelBus support in templates.

Phew, that's a long list - you can see that Visual Studio 2010 is a big release for T4.

I'll come back and edit this post to include live links as I fill in more details about some of these topics.

Technorati Tags: T4,Visual Studio 2010,What's New,Text Templating

Oleg on T4-MSBuild Integration

GarethJones — Wed, 14 Apr 2010 07:28:07 GMT

The newly released Visualization and Modeling SDK for Visual Studio 2010 includes support for integrating T4 with msbuild. (yay!)

The ever-diligent Oleg Sych has the full skinny here.

Technorati Tags: T4,msbuild,Visual Studio 2010

Bending T4 to be a textual DSL host

GarethJones — Thu, 11 Mar 2010 10:10:52 GMT

The estimable MVP and T4 enthusiast, Kathleen Dollard has a new post where she's using T4's ability to spit arbitrary text as a host for a textual DSL.

She's set up a small DSL for describing contract interfaces for a MEF framework:

         new Interface()

            Name = "ISearchModelBase",

            Scope = Scope.Public,

            CompositionInfo =

               new Property() {Name="TargetType", PropertyType="Type"}

},

            Members =

               new Property() {Name="DisplayName", PropertyType="string"},

               new Property() {Name="DataName", PropertyType="string"}

         }.Output()

Hosting this in T4 with a couple of lines of wrapper code spits out the following output, codifying her standard implementation pattern for MEF contracts and custom attributes:

Option Strict On

Option Explicit On

Option Infer On

Imports System

Imports System.Collections.Generic

Imports System.Linq

Imports System.ComponentModel.Composition

public Interface ISearchModelBase

   Property DisplayName As string

   Property DataName As string

End Interface

public Interface ISearchModelBaseComposition

   Readonly Property TargetType As Type

End Interface

< MetadataAttribute() > _

< AttributeUsage(AttributeTargets.Class, AllowMultiple:=False) > _

public Class SearchModelBaseAttribute

   Inherits ExportAttribute

   Implements ISearchModelBaseComposition

   Public Sub New( ByVal targetType As Type)

      MyBase.New(GetType(ISearchModelBase))

      _targetType = targetType

   End Sub

   Private _targetType As Type

   Public Readonly Property TargetType As Type Implements ISearchModelBaseComposition.TargetType

Get

         Return _targetType

      End Get

   End Property

End Class

Fascinating stuff, especially when you see that these days, populating such a structure in C#4.0 is such a snap with the new initializer syntax.

Peeking under the covers, at the attachment to Kathleen's blog entry, the code combines the DSL structure definition with the code output for VB in a way that's a bit too printf-ish for my personal taste, so I was tempted to T4 it up a bit.

The original template passes a StringBuilder down the call tree and builds code using AppendLine():

 private void AppendOpen(System.Text.StringBuilder sb)

         sb.AppendLine("Option Strict On");

         sb.AppendLine("Option Explicit On");

         sb.AppendLine("Option Infer On");

         sb.AppendLine("");

         sb.AppendLine("Imports System");

         sb.AppendLine("Imports System.Collections.Generic");

         sb.AppendLine("Imports System.Linq");

         sb.AppendLine("Imports System.ComponentModel.Composition");

Instead of this, I wanted to use regular T4 syntax with a class feature block:

      private void AppendOpen()

#>

Option Strict On

Option Explicit On

Option Infer On

Imports System

Imports System.Collections.Generic

Imports System.Linq

Imports System.ComponentModel.Composition

<#+

However, this code is inside a nested class, so the underlying Write statements needed by T4 aren't present. To get around this, I whipped up a trivial base class that supplies all of the necessary plumbing for T4 to be happy. This works because this part of T4 doesn't rely on a specific type, rather it just expects access to the members it needs and any class will do. In my implementation I simply delegate all of the calls back out to the main T4 template.

The only changes necessary to the DSL definition classes are to derive from my DslBase class and to add a trivial constructor to supply the main template to each DSL class instantiation:

public class Interface : DslBase

    public Interface(Microsoft.VisualStudio.TextTemplating.TextTransformation outer) : base(outer)

I've attached the base class code and a modified version of Kathleen's template for you to play with here. Enjoy.

Technorati Tags: T4,Textual DSL

Peter on UML Tools Extensibility

GarethJones — Tue, 27 Oct 2009 18:56:23 GMT

My esteemed colleague Peter Provost – whom I consistently fail to convince that I’m not into process engineering ;-) - has the first in what I’m sure will be a very informative series on extending the UML designers in Visual Studio 2010 Ultimate Edition

Technorati Tags: UML,Visual Studio 2010,Ultimate Edition

DTE and T4 - Better Together

GarethJones — Fri, 25 Sep 2009 21:27:57 GMT

A couple of folks out there have put together some really neat T4 templates that use the host-specific flag and then access Visual Studio's DTE object model to read state from other code in the project and use that as metadata for code generation.

Daniel Vaughan started out with a nice post on using DTE to explore the source constructs within your project using the CodeModel and thence using that data to introduce compile time strong-typing to WPF binding expressions.

To borrow Daniel's example, to switch from this weakly typed case

<StackPanel DataContext="{Binding Source={StaticResource Person}}">
    <TextBlock >Name:</TextBlock>
    <TextBox Text="{Binding Name}" />
</StackPanel>

to this strongly typed one which gives compile-time errors if you get the name wrong

<StackPanel DataContext="{Binding Source={StaticResource Person}}">
	<TextBlock >Name:</TextBlock>
	<TextBox Text="{Binding Path={x:Static Metadata:PersonMetadata.NamePath}}"/>
</StackPanel>

He then also talks about using the same technique to generate implementations of INotifyPropertyChange that are robust to refactoring without the problems of embedded strings or the performance hit of reflection. Code generation and declarative programming are often criticized for not having good support for refactoring, so it's nice to see a use case that actually helps support refactoring.

Daniel has now expanded this into a full article on The Code Project.

Last time, I talked about Colin Eberhardt's article for generating Dependency Properties from an xml file. Daniel's approach inspired Colin to go back and rework his example to use DTE replacing his external XML file with custom attributes on classes to simply add dependency properties like so:

[DependencyPropertyDecl("Maximum", typeof(double), 0.0)]
[DependencyPropertyDecl("Minimum", typeof(double), 0.0)]
public partial class RangeControl : UserControl
{
    ...
}

Very cool stuff.

Technorati Tags: T4,DTE,Visual Studio 2008,Code Generation,Dependecy Property,Databinding,Strongly-typed

T4 and Silverlight in Visual Studio 2008

GarethJones — Fri, 25 Sep 2009 20:32:23 GMT

Colin Eberhardt has a nice article on The Code Project walking through using a small textual DSL encoded in XML to define a set of dependency properties and then using that as a data source for T4 to generate all of the necessary boilerplate code.

Apart from being intrinsically cool, he's also doing this in a Silverlight project, and he includes the small amount of special sauce needed to get T4 generation working in a Silverlight project inside Visual Studio 2008.

BTW, in Visual Studio 2010, T4 in Silverlight should "just work".

Technorati Tags: T4,SIlverlight,Visual Studio,Visual Studio 2008,Dependecy Property