Ticklish Techs

What’s the problem?

First of all I have to explain to everybody what I’m talking about:

With Visual Studio 2010 Microsoft introduced a new way to deploy extensions to Visual Studio. Instead of creating a setup.exe that copies files, writes to the registry and calls devenv.exe with the /setup option one only needs such a VSIX file that does all that is necessary to install an extension.

When working with the T4 (Template Transformation Toolkit) system one creates tt files with some kind of script that is used to generate source code within a user’s Visual Studio project. The Microsoft DSL Tools do the same: every DSL project contains a number of tt files that will generate all the code. If you take a look at such a file, you will only see two lines:

<#@ Dsl processor="DslDirectiveProcessor" requires="fileName='..\DslDefinition.dsl'" #>
<#@ include file="Dsl\Diagram.tt" #>

The magic happens with the include command. The real template code sits in the included file and not within every single project. When installing the DSL Tools extension to Visual Studio all these include files get installed somewhere where they can be found by the tt engine.

For my own DSL Languages I would like do the same: the user projects should only contain such two line tt files and include the rest of the template from other files.

How to deploy tt template files?

The following steps will show you how to deploy additional files with you DSL extension.

I will start from a newly created Domain-Specific Language Designer project. Such a project contains a Dsl and a DslPackage project where the DslPackage project creates besides of the DslPackage.dll a vsix file to install the designer onto another machine.

Our goal will be to add some tt files to the vsix and make them includable on the installed machine.

1. Add a folder to the DslPackage project and name it TextTemplates (or any other name)
2. Add the tt files to this folder.
   • In the properties windows clear the “Custom Tool” property; otherwise Visual Studio will try to execute these templates within the DslPackage project.
   • set “Build Action” to “Content”
   • set “Include in VSIX” to “True”
3. Add a file called Additional.pkgdef to the DslPackage project with the following content and
   • set “Build Action” to “Content”
   • set “Include in VSIX” to “True”
     

     [$RootKey$\TextTemplating\IncludeFolders] [$RootKey$\TextTemplating\IncludeFolders\.tt] "IncludeMyDsl"="$PackageFolder$\TextTemplates"

     Replace “IncludeMyDsl” by a unique name for your DSL but make sure it starts with the word “Include”.

4. Edit the source.extension.tt in the DslPackage project and add the following line within the Content tag:

   <VsPackage>Additional.pkgdef</VsPackage>

With these changes the tt files from the TextTemplates folder get packaged into the vsix file and will be accessible using the <include> tag on the machine where this extension is installed.