Technorati Tags: Visual Studio 2010 Extension,T4 Template,VSIX,Item Template Wizard This blog post briefly introduces creation of
an item template as a Visual studio 2010 extension. Problem specification Assume you are writing a Framework for data-oriented applications and you decide
to include all your application messages in a SQL server database table. After creating the table, your
create a class in your framework for getting messages with a string key specified. var message = FrameworkMessages.Get("ChangesSavedSuccess"); Everyone would say this code is so error prone, because message keys are not strong-typed, and might
create errors in application that are not caught in tests. So we think of a way
to make it strong-typed, i.e.
create a class
to use it like this: var message = Messages.ChangesSavedSuccess; in Messages class the code looks like this: public string ChangesSavedSuccess { get { return FrameworkMessages.Get("ChangesSavedSuccess"); } } And clearly, we are not going
to create the Messages class manually; we need a class generator for it. Again assume that the application(s) that intend
to use our framework, contain multiple sub-systems. So each sub-system need
to have it’s own strong-typed message class that call FrameworkMessages.Get method. So we would like
to make our code generator
an Item Template so that each developer would easily add the item
to his project and no other works would be necessary. Solution We
create a T4 Text Template
to generate our strong typed class from database. Then
create a Visual Studio Item Template with this generator and publish it. What Are T4 Templates You might be already familiar with T4 templates. If it’s so, you can skip this section. T4 Text Template is a fine Visual Studio file type (.tt) that generates output text. This file is a mixture of text blocks and code logic (in C# or VB). For example, you can generate HTML files, C# classes, Resource files and etc with use of a T4 template. Syntax highlighting In Visual Studio 2010 a T4 Template by default will no be syntax highlighted and no auto-complete is supported for it. But there is a fine visual studio extension named ‘Visual T4’ which can be downloaded free from VisualStudioGallery. This tool offers IntelliSense, syntax coloring, validation, transformation preview and more for T4 templates.
How Item Templates work in Visual Studio Visual studio extensions allow us
to add some functionalities
to visual studio. In our case we need
to create a .vsix file that adds a template
to visual studio item templates. Item templates are zip files containing the template file and a meta-data file with .vstemplate extension. This .vstemplate file is
an XML file that provides some information about the template. A .vsix file also is a zip file (renamed
to .vsix) that are open with visual studio extension installer. (Re-installing a vsix file requires that old one
to be uninstalled from VS: Tools > Extension Manager.) Installing a vsix will need Visual Studio
to be closed and re-opened
to take effect. Visual studio extension installer will easily find the item template’s zip file and copy it
to visual studio’s template items folder. You can find other visual studio templates in [<VS Install Path>\Common7\IDE\ItemTemplates] and you can edit them; but be very careful with VS default templates.
How Can I
Create a VSIX file 1. Visual Studio SDK depending on your Visual Studio’s version, you need
to download Microsoft Visual Studio SDK. Note that if you have VS 2010 SP1, you will need
to download and install VS 2010 SP1 SDK; VS 2010 SDK will not be installed (unless you change registry value that indicated your service pack number). Here is the link for VS 2010 SP1 SDK. After downloading, Run it and follow the wizard
to complete the installation. 2.
Create the file you want
to make it
an Item Template
Create a project (or use
an existing one) and add you file, edit it
to make it work fine. Back
to our own problem, we need
to create a T4 (.tt) template. VS-Prok: Add > New Item > General > Text Template Type a file name, ex. Message.tt, and press Add.
Create the T4 template file (in this blog I do not intend
to include T4 syntaxes so I just write down the code which is clear enough for you
to understand) <#@ template debug="false" hostspecific="true" language="C#" #> <#@ output extension=".cs" #> <#@ Assembly Name="System.Data" #> <#@ Import Namespace="System.Data.SqlClient" #> <#@ Import Namespace="System.Text" #> <#@ Import Namespace="System.IO" #> <# var connectionString = "server=Maziar-PC; Database=MyDatabase; Integrated Security=True"; var systemName = "Sys1"; var builder = new StringBuilder(); using (var connection = new SqlConnection(connectionString)) { connection.Open(); var command = connection.CreateCommand(); command.CommandText = string.Format("SELECT [Key] FROM [Message] WHERE System = '{0}'", systemName); var reader = command.ExecuteReader(); while (reader.Read()) { builder.AppendFormat(" public static string {0} {{ get {{ return FrameworkMessages.Get(\"{0}\"); }} }}\r\n", reader[0]); } } #> namespace <#= System.Runtime.Remoting.Messaging.CallContext.LogicalGetData("NamespaceHint") #> { public static class <#= Path.GetFileNameWithoutExtension(Host.TemplateFile) #> { <#= builder.ToString() #> } } As you can see the T4 template connects
to a database, reads message keys and generates a class. Here is the output: namespace MyProject.MyFolder { public static class Messages { public static string ChangesSavedSuccess { get { return FrameworkMessages.Get("ChangesSavedSuccess"); } } public static string ErrorSavingChanges { get { return FrameworkMessages.Get("ErrorSavingChanges"); } } } } The output looks fine but there is one problem. The connectionString and systemName are hard coded. so
how can I
create an flexible item template? One of features of item templates in visual studio is that you can
create a designer wizard for your item template, so I can get connection information and system name there. now lets go on creating the vsix file. 3.
Create Template In visual studio click on File > Export Template a wizard will show up. if first step click on Item Template on in the combo box select the project that contains Messages.tt. click next. Select Messages.tt from list in second step. click next. In the third step, you should choose References. For this template, System and System.Data are needed so choose them. click next. write down template name, description, if you like add a .ico file as the icon file and also preview image. Uncheck automatically add the templare … . Copy the output location in clip board. click finish. 4.
Create VSIX Project In VS, Click File > New > Project > Extensibility > VSIX Project Type a name, ex. FrameworkMessages, Location, etc. The project will include a .vsixmanifest file. Fill in fields like Author, Product Name, Description, etc. In Content section, click on Add Content. choose content type as Item Template. choose source as file. remember you have the template file address in clipboard? now paste it in front of file. click OK. 5. Build VSIX Project That’s it, build the project and go
to output directory. You see a .vsix file. you can run it now. After restarting VS, if you click on a project > Add > New Item, you will see your item in list and you can add it. When you add this item
to a project, if it has not references
to System and System.Data they will be added. but the problem mentioned in step 2 is seen now. 6.
Create Design Wizard for your Item Template
Create a project i.e. Windows Application named ‘Framework.Messages.Design’, but better change its output type
to Class Library. Add References
to Microsoft.VisualStudio.TemplateWizardInterface and envdte Add a class Named MessagesDesigner in your project and Implement IWizard interface in it. This is what you should write: using System; using System.Collections.Generic; using System.Linq; using System.Text; using Microsoft.VisualStudio.TemplateWizard; using EnvDTE; namespace Framework.Messages.Design { class MessageDesigner : IWizard { private bool CanAddProjectItem; public void RunStarted(object automationObject, Dictionary<string, string> replacementsDictionary, WizardRunKind runKind, object[] customParams) { // Prompt user for Connection String and System Name in a Windows form (ShowDialog) here // (try
to provide good interface) // if user clicks on cancel of your windows form return; string connectionString = "connection;string"; // Set value from the form string systemName = "system;name"; // Set value from the form CanAddProjectItem = true; replacementsDictionary.Add("$connectionString$", connectionString); replacementsDictionary.Add("$systemName$", systemName); } public bool ShouldAddProjectItem(string filePath) { return CanAddProjectItem; } public void BeforeOpeningFile(ProjectItem projectItem) { } public void ProjectFinishedGenerating(Project project) { } public void ProjectItemFinishedGenerating(ProjectItem projectItem) { } public void RunFinished() { } } } before your code runs replacementsDictionary contains list of default template parameters. After that, two other parameters are added. Now build this project and copy the output assembly
to [<VS Install Path>\Common7\IDE] folder. your designer is ready. The template that you had created is now added
to your VSIX project. In windows explorer open your template zip file (extract it somewhere). open the .vstemplate file. first of all remove <ProjectItem SubType="Code" TargetFileName="$fileinputname$.cs" ReplaceParameters="true">Messages.cs</ProjectItem> because the .cs file is not
to be intended
to be a part of template and it will be generated. change value of ReplaceParameters for your .tt file
to true
to enable parameter replacement in this file. now right after </TemplateContent> end element, write this: <WizardExtension> <Assembly>Framework.Messages.Design</Assembly> <FullClassName>Framework.Messages.Design.MessageDesigner</FullClassName> </WizardExtension> one other thing that you should do is
to edit your .tt file and remove your .cs file. Lines 8 and 9 of your .tt file should be: var connectionString = "$connectionString$"; var systemName = "$systemName$"; this parameters will be replaced when the item is added
to a project. Save the contents
to a zip file with same file name and replace the original file. now again build your VSIX project, uninstall your extension. close VS. now run .vsix file. open vs, add
an item of type messages
to your project, bingo, your wizard form will show up. fill the fields and click ok, values are replaced in .tt file added. that’s it. tried so hard
to make this post brief, hope it was not so long… Cheers Maziar
