Visual Studio Project Templates #1: Creating template projects

This is not a purely mobile-related topic as it rather concerns .NET programming in general, but it might still be helpful if you’re planning to create template projects of your mobile apps content and make them available online.

Visual Studio project templates that appear in the New Project wizard in Visual Studio. This allows you to provide yourself (or your colleagues, customers, etc.) with project stubs that can be used for each new App project, without the need of re-creating the set up of project files. In addition, these project template can be made available online – but that another topic which will be covered in part 2! Let’s first take a look at how to create and use project templates locally:

  1. Simply create a new Visual Studio project and add and adapt all the files you want your project template to contain, which means do all the project setup that is necessary when starting a new App project – this includes all steps you wish to be already done when building a new project based on the template in the future.

    If your project template depends on external libraries, the best solution is to include them using the Nuget Package Manager, as this allows your template users to automatically restore all external packages when using the template.

  2. Select “Export Template…” from the Visual Studio File menu, and select the “Project Template” option and the newly created project from the drop-down list. In the next screen, you are asked for the template name (this will be suggested as the project name in the future, usually followed by a “1”), as well as for optional descriptive text, preview and icon images. (The icon image will be displayed next to your project type, it might be useful to assign an illustrative icon in order to quickly identify your template from the long list of potential project types in the future.)

    Be sure to de-select the “Automatically import the template into Visual Studio” option, as we want to refine the template with some customizations and manually import it in a later step.

  3. Visual Studio creates a ZIP file – extract the contents of this file into an empty folder. You will notice that the contents look exactly like the project created in step 1, except for the additional MyTemplate.vstemplate file (as well as icon and image files, if you specified these in the export wizard). The MyTemplate.vstemplate file is structured in XML, which means that for future project templates you don’t really need the export wizard but can simply create the MyTemplate.vstemplate file on your own and pack it into a ZIP file together with all the necessary project files.

    The MyTemplate.vstemplate file’s structure is rather self-explanatory: It contains of a TemplateData section that contains all the template’s meta data (e.g., the given template name and description and the icon’s path), which is followed by a TemplateContent section. The TemplateContent section lists all files that are part of the template (and therefore are part of the ZIP package).

  4. In most cases, you’ll want to further customize your template. Visual Studio provides a set of parameters that can be used both within code and as part of file names, and which are automatically replaced whenever some user creates a new project based on your template. For example, the AssemblyInfo.cs file still will contain information about your name organization, however you’ll want to replace that by the template user’s details. To do so, you can for example replace the line

    [assembly: AssemblyCompany("YOUR_ORGANIZATION")]

    with

    [assembly: AssemblyCompany("$registeredorganization$")]

    This applies to all other lines too, e.g. the copyright statement could look like this:

    [assembly: AssemblyCopyright("Copyright $registeredorganization$ $year$")]

    Of course, you can also use those parameters within other parts of the code, e.g. adapt all the contained classes’ namespaces to start with the user-chosen project name. To do so, open all code files within the ZIP package and change the namespace declarations to something like

    namespace $safeprojectname$.Packagename

    A list of all the predefined parameters that can be used is available as part of the MSDN Library.

    One final warning: It is very important that for all files you’ve just adapted with parameter, the according ReplaceParameters attribute within the MyTemplate.vstemplate file is set to true, as for example in the following line:

    AssemblyInfo.cs

    In most cases this will already be set automatically, but this seems not to be the case for certain file types, such as *.appxmanifest files.

  5. Finally, re-package all the files and folders as ZIP file.

Now you’re ready to use your project templates within Visual Studio! Custom project templates are usually located at

C:\Users\[UserName]\Document\Visual Studio 2012\Templates\ProjectTemplates\Visual C#\

(of course, you’ll need to include your user name and adapt the path to other versions of visual studio, or change the last part if you’re workin with Visual Basic or other project types.)

Copy your ZIP file to this folder, restart Visual Studio, select File -> New -> Project… and look for your project template under the Visual C# category (or whatever folder you used). If you’d like to see your template in one of the sub-categories, simply create a new folder at the path specified above, name ot corresponding to one of the existing sub-categories, and move the ZIP file there. You can even create a new sub-category be assigning a unique name to the new folder – the folder name will be presented as new sub-category in the New Project wizard!

That’s a nice way to allow re-using your existing project setup by simply adding it as project template to Visual Studio. But what if you’d like to pass on your templates to colleagues or customers? They would need to manually add ZIP files to some random folder in ther file system, and restart Visual Studio in order to see the templates listed in the New Project wizard – there must be a better way to distribute Visual Studio project templates? Well, there is – read more about template installers in the second part: Visual Studio Project Templates #2: Uploading to Visual Studio Gallery