Creating Visual Studio item templates

In Visual Studio terms, an item is anything that can be added to a project. Some examples of project items include:

  • a file containing a class or interface
  • a physical folder
  • a solution folder (“virtual folder”)
  • a configuration file

When adding items to solutions and projects alike, Visual Studio uses prepackaged templates to determine what files to generate and whether or not to post-process the content of these files. Examples are based on Visual Studio 2010.

Reason

Using company specific item templates helps reinforce coding paradigms, and eleviates some of the repetitious tasks common to the creation of e.g. classes, interfaces and web controls. Being very easy to create, the ROI of such templates can be tremendous.
The following is an example of a simple item template used to create a class which inherits from Sitecore.Data.Items.CustomItem.

Code

A Visual Studio item template is deployed as a simple ZIP-archive. To be recognized as an item template the archive must contain a single file with the “vstemplate”-extension. This file contains the “template definition”, providing name, description and similar miscellaneous information alongside a description of the template contents.
The contents are in XML-format, following the guidelines found on MSDN.

<VSTemplate Version="3.0.0" xmlns="http://schemas.microsoft.com/developer/vstemplate/2005" Type="Item">
  <TemplateData>
    <!-- Template name shown in "Add new item" dialog -->
    <Name>Sitecore Custom Item</Name>
    <!-- Description shown in "Add new item" dialog -->
    <Description>Creates an empty class based on Sitecore.Items.CustomItem.</Description>
    <!-- Default file name shown in "Add new item" dialog -->
    <DefaultName>CustomItem.cs</DefaultName>
    <!-- If set to false, the template will not be shown in "Add new item" dialog. Useful for e.g.  hiding templates intended purely for code generation. -->
    <ShowByDefault>true</ShowByDefault>
    <ProjectType>CSharp</ProjectType>
    <SortOrder>10</SortOrder>
    <Icon>reasoncodeexample.ico</Icon>
  </TemplateData>
  <TemplateContent>
    <!-- Custom "replacement tokens" -->
    <CustomParameters>
      <CustomParameter Name="$company$" Value="Reason→Code→Example"/>
      <CustomParameter Name="$companyurl$" Value="https://reasoncodeexample.com/"/>
    </CustomParameters>
    <ProjectItem SubType="Code" TargetFileName="$fileinputname$.cs" ReplaceParameters="true">CustomItem.cs</ProjectItem>
  </TemplateContent>
</VSTemplate>

Alongside the template definition itself, the archive can contain any number of other files – these either serve as “content blueprints” or serve some other purpose  related to the item (e.g. “.ascx.cs” and “.ascx.designer.cs” for a web control).
The term “blueprint” simply means a text file which contains token values (“parameters”) that start and end with a dollarsign, e.g. $tokenname$. An example of a file containing such tokens is provided below.

/*
Copyright 1980 - $year$ $company$
Visit us at $companyurl$
Created by: $username$
*/

using System;
using Sitecore.Data.Items;
using Company.Proprietary.Stuff;
using Other.Commonly.Used.Stuff;

namespace $rootnamespace$
{
  public class $safeitemname$ : CustomItem
  {
    public $safeitemname$(Item innerItem) :
      base(innerItem)
    {
    }

    public static implicit operator $safeitemname$(Item innerItem)
    {
      return new $safeitemname$(innerItem);
    }
  }
}

When a template is used to create an item, Visual Studio creates copies of all files which are listen in a “ProjectItem”-node in the package definition, and then replaces any tokens found in these files with default and custom tokens (given that the “ReplaceParameters”-attribute contains the value “true”).
Replacement values are drawn from both a set of default values and from the “custom parameters” node in the template definition. Visual Studio provides various default tokens, some of which are listed on MSDN.

The template definition and contents are packaged and deployed as described in Deploying Visual Studio templates.

Example

Given the example above, Visual Studio would place a copy of the file “CustomItem.cs” in the current project, named according to the value specified in the “Add New Item”-dialog, and then replaces all tokens within the file with their replacement values as shown below.

Visual Studio "Add new item"-dialog

Class created from Custom Item template

3 thoughts on “Creating Visual Studio item templates

  1. Hi!
    It is possible to make item template parameters uppercase?
    For example if parameter safeitemname is “t_animal” to be replaced with “T_ANIMAL”?

    • Hi Ben,
      As far as I know there’s no built-in way of doing post processing (e.g. converting to upper case) via the standard template engine, at least I didn’t come across such a feature when I wrote this article and haven’t since.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s