In this series of posts, I’m showing how to create a Visual Studio 2012 Project Template. Specifically, we want a Template that creates unit-testing projects, so developers can easily follow the standards I enumerated in the introduction.

Let’s begin by seeing what Visual Studio 2012 gives us with no extra work at all. If you want to follow along in your own copy of Visual Studio 2012 without having to type anything yourself, you can download the completed solution here: ProjectTemplateTutorial.zip (271.98 kb). It contains not only the project I'll outline in this post, but the result of this entire series.

Creating the Unit-Test Project

The first step in creating a unit-testing Project Template is to create a unit-testing project in the usual way. In a blank solution, use the Add -> New Project command and then choose Installed -> Templates -> Visual C# -> Test -> Unit Test Project.

In keeping with our standards, we’ll call it Fws.VS2012.UnitTestProject.Template and we want it to go in the C:\Software\Fws\VS2012\UnitTestProject\Template directory. The standards require the correlation between the project name and the directory structure.

Already we have run into trouble. Visual Studio did not put our project in a directory called Template, but in one called Fws.VS2012.UnitTestProject.Template, and we had no way to control that. We could have named the project Template and put it in the correct directory, but then our assembly name and default namespace would have also been just Template -- not what we want. It’s exactly this sort of thing that our new Project Template will correct.

But in the meantime, we must close the solution, rename the directory to Template, reload the solution, and reload the project from the renamed directory. Ugh.

Now let's make the project conform to our standards.

1) To sign it with C:\Software\Fws\Signing\Fws.snk:

Right-click on the project and choose Add -> Existing Item.

Navigate to the Fws.snk file.

Press the down-arrow on the Add button and choose Add as Link.

Bring up the Project Properties and then select the Signing tab.

Check Sign the assembly and choose the snk file from the combo box.

You might have a different way of using key files, but I belabor this because it will end up illustrating a problem that Visual Studio templates have when they point to many kinds of files that are outside the direct purview of the solution. We’ll need some custom code to correct it.

2) To choose warning level 4, and treat errors as warnings:

On the Build tab of Project Properties, make sure warning level 4 is selected and, under Treat warnings as errors, choose All.

3) Finally, remove the UnitTest1.cs file from the project.

The project should now compile cleanly. By the way, a clean compile is one advantage of the approach I'm outlining over some other ways of creating Project Templates. The project that forms the basis for the Template actually compiles. In other approaches, the project has embedded template-substitution variables that make an ordinary compile fail.

Exporting the Template

Now we’re ready to export the Project Template.

On the main menu, choose File -> Export Template.

The first page of the Export Template Wizard will be as you want it: Project template is checked, and the sole project in the solution is selected in the combo box. Press Next.

On the next page of the wizard, enter the Template name and Template description shown below. So that we have a chance to learn the inner workings of the template system, we will import the template by hand, so un-check the Automatically import the template box. Leave the other box checked.

Note the Output location. We'll go there when it's time to import the Template.

When you press Finish, the wizard will create a Template for you, putting it in the output location. The Template is nothing more than a ZIP file.

The wizard has also opened a Windows Explorer on the output location. You’ll find the ZIP file there. It’s worth taking a moment to see what’s in it.

It contains

• The contents of the project itself (the .csproj file and the Properties folder with its AssemblyInfo.cs).
• A default icon (we could have specified our own on the second page of the wizard).
• A .vstemplate file. I’ll have more to say about the .vstemplate file in the next post, but basically it contains instructions for displaying the template in Visual Studio’s Add New Project dialog, as well as some instructions for how Visual Studio should create a project from the template.

Installing the Template

Making the template available in Visual Studio is deceptively simple. Just copy the ZIP file to the location named in Tools -> Options -> Projects and Solutions -> General -> User project templates location – actually, for our Unit Test Project Template, we want the Visual C#\Test directory under that; this will cause the template to appear in the Visual C# -> Test area of Add -> New Project.

Using the Template

We can now create a Unit-Testing project by right-clicking on the solution and choosing Add -> New Project. We can navigate to the Installed -> Visual C# -> Test area and see our template.

The description we entered appears nicely, but the name of the template is somewhat stupidly the name of the ZIP file. We'll do better in subsequent posts.

Let's pretend that we want to unit-test an assembly in C:\Software\Fws\Common. According to the standards in the introductory post, that means we want our unit-testing assembly to go in a Test directory under that. So, we enter a Name of Test.

Once we press OK, we do indeed get an unit-testing project. It has some of what we want, but not all. It is set up to treat warnings as errors, and it is in the correct directory, but...

• The assembly is called Test, not Fws.Common.Test.
• The default namespace is also Test instead of Fws.Common.Test.
• Most mysteriously, the link to the signing key is broken. Instead of pointing to the file with a relative directory, it points somwhere in the user's AppData directory. Note the yellow triangle in the project.

Invoking the Properties window on Fws.snk shows the full path:

This is one of many ways that the out-of-the-box Project Templating process can go wrong with linked paths. Apparently Visual Studio creates the new project from the Template under the AppData directory (or, more precisely, the directory named in your TEMP environment variable) and then copies the project to its ultimate location -- but without fixing up all the paths.

Later in this series, we'll see how some custom code can correct all these deficiencies.

But first, let's see what we can do about the clunky export / import process. Wouldn't it be nice if the export were to happen as part of the build? In the next post, we'll create a command-line program that does the export. In Part 4, we'll hook that up in the pre-build step of the deployment project.