This project is read-only.

Creating New Templates

Introduction

This document provides guidance for creating custom DocProject and DocSite templates. You won't need to modify the source code to create new templates; however, guidance for adding new templates to DocProject's Visual Studio solution is included here as well.

For general information about templates and the templates that DocProject installs, see DocProject Templates.

If you want your custom template included in the next release of the DocProject installer here on CodePlex, then please contact Dave Sexton with a request that contains a short description of your template, its coding language and whether it's a DocProject or DocSite. Templates will be added to DocProject at the sole discretion of the DocProject team.

Note: You should read the entire tutorial first before attempting to create a new template. You must choose whether you are going to add the template's project to the DocProject solution, which dynamically builds the Visual Studio Content Installer file (.vsi) from all of the solution's template projects, or a custom solution, in which case you can build the .vsi manually or not at all. Using the DocProject solution requires more steps to configure the solution for your template's project.

For help setting up DocProject's Visual Studio solution, see How To Use The Source Code.

Create a Project

To create a DocProject or DocSite template you must first create a standard Visual Studio project template based on an existing, built-in project template. The template that you choose for the new project will serve as the base type for the DocProject or DocSite template that you will create later. For example, if you choose Class Library under Visual C#, then you will have taken the first step to creating a DocProject template based in C# and you'll have the ability to include an optional Build Process Component in your template. If you choose an ASP.NET Web Application in Visual Basic, for example, then you can use it to create a DocSite template with an optional Build Process Component.

If you are planning on creating a DocSite template based on a Web Application, or if you want to use the DocSites that are installed along with DocProject, see How To Configure Visual Studio 2005 For DocProject for required updates to Visual Studio 2005. Not all versions of Visual Studio 2005 require the updates. You'll know if your system requires the updates when you try to add a new DocSite if Visual Studio shows a dialog stating that the project type is unsupported.

The supported languages for DocProject and DocSite templates are Visual C#, Visual Basic and Visual J# only.

Create the Template's Project
  1. Create or open an existing solution.
    1. Note: If you want to develop the new template in the DocProject solution then open that now. For help preparing the solution, see How To Use The Source Code.
  2. Add a new project.
    1. Use the naming conventions described below.
    2. Make sure that it isn't built along with the solution. Open the solution's Configuration Manager... and uncheck the Build column next to your project for both the Debug and Release configurations. If you're not planning on building the solution or using the solution after the template is created then you can skip this step.
    3. Note: If you are adding a new template to the DocProject solution then you should make sure that the project is created in a folder next to the other project folders in DocProject's solution's folder. It's important that your project folder's name is the name of the project.
Once you have created the project from which you will create a new template, you should modify it to your liking. Set project properties and add new project items until you are satisfied with your template.

Naming the Project
The name for your new project should follow the standard naming conventions as the other templates:
  1. Start with a language identifier: CSharp, JSharp or VB.
  2. Next, add a specialized identifier for the template that should indicate its purpose.
  3. Last, append either DocProjectTemplate or DocSiteTemplate, depending upon the type of the project. Use DocSiteTemplate if your project is an ASP.NET Web Application, otherwise use DocProjectTemplate.
For example, the appropriate name for a new DocProject template in Visual J# that is specialized for your organization, hypothetically named, Contoso Inc., should be named JSharpContosoDocProjectTemplate.

Default Build Process Component (Optional)
You can add a default Build Process Component to the template if you'd like. Both DocProjects and DocSites support a single Build Process Component.

To add a default Build Process Component to your new project you must add a reference to the Add-In assembly. A reference to the assembly in the GAC is preferable, unless you have added the new template project to the DocProject solution, in which case a project reference is desirable. If you aren't using the DocProject solution, and although this isn't recommended, you can reference the assembly installed in your program files folder by choosing Add Reference... from the Project menu in Visual Studio. By default, the installer copies the assembly to: C:\Program Files\Dave Sexton\DocProject\bin\DaveSexton.DocProject.dll.

Note: The steps in Configure the Template provide guidance for referencing the Add-In assembly in the GAC. Wait to design your Build Process Component after you have completed those steps if you want to have IntelliSense support.

To add a default Build Process Component to the project:
  1. Add a new code file to the project and name it BuildProcess, with the appropriate extension for your template's language, such as .cs for a C# project and .vb for a Visual Basic project.
    1. Note: You can skip all of these steps if you import a copy of the BuildProcess class from one of the DocProjects that are installed with the DocProject software. Of course, choose the language that matches the language of your project. (e.g., Visual C#, Visual Basic)
  2. Add a class that inherits from DaveSexton.DocProject.BuildProcessComponent.
  3. Provide an implementation for the abstract members. Users of your template will be able to modify the component when they use your template to create a new project, just like the built-in templates provided by the DocProject installer.
  4. Save the changes when you are finished.
Note: You'll want to register your default Build Process Component with your project template so that it's configured to execute when a project created from your template is built. (The steps to accomplish this are found in the Configure the Template section later in this tutorial.)

Export the Template

If you have added the template's project to DocProject's Visual Studio Solution, then follow these instructions before continuing on to Configure the Template, otherwise you should skip these instructions for now:

Once you have completed the previous steps and have a project as the basis for your template, you can use the Visual Studio Export Template wizard to create the necessary template files. For instructions see How to: Create Project Templates and Export Template Wizard.

Note: The export wizard will provide you with two options that should be configured accordingly: Make sure that you allow the wizard to browse to the created files when it's complete, but do not let it add the template into Visual Studio since there are still some modifications that have to be made manually.

For more information about Visual Studio Project Templates in general, see Visual Studio Templates.

At this point you should have a .zip file that contains your project file, content files and the new .vstemplate file. The .zip file may be located in your My Exported Templates folder, in which case you should move it to a different directory so that it's not loaded by Visual Studio just yet.

Configure the DocProject Solution

If you have added the template's project to DocProject's Visual Studio Solution, then follow these instructions before continuing on to Configure the Template, otherwise you can skip these instructions:

Note: You will need the DSZip utility. If you haven't done so already, download the DSZip utility from the Releases tab and install it.
  1. Add a new directory under the Contents directory in the DaveSexton.DocProject.InstallPrep project. It will contain the template's contents (herein, it will be referred to as the template content directory).
    1. The name of the directory should be the name of the project.
    2. Items that are added to your template's project will be included in the Visual Studio Content Installer file (.vsi) automatically. The .vsi is created by the InstallPrep project's post-build event. To exclude certain files, modify the xcopyx.txt file in the InstallPrep project. In the future, every time you add or remove files from the template project the changes will automatically be reflected in the new .vsi each time the InstallPrep project is built.
      1. Note: If you add or remove files from your project you'll have to either export a template for the project again (see Export the Template) or you can modify the .vstemplate file manually to include/exclude the appropriate project items. Read on for information about the .vstemplate file.
    3. Note: The project file isn't copied by the InstallPrep project when it's built. The version that you extract in the next step will be used in the .vsi each time. The reason for this is because the project files commonly contain information that needs to be removed or modified manually. You can modify the project file to exclude the source control information, or to make other modifications that Visual Studio can't process while working on the project in a solution, such as adding replacement tokens as the template's name, for example.
  2. Extract into the template content directory the project file and the .vstemplate file from the template's .zip file. Code and content files shouldn't be copied (see previous step), although you may want to copy the template icon (see next step).
  3. Copy the icon into the template content directory that was registered with the .vstemplate file by the Export Template Wizard.
    1. You should give the icon a meaningful name.
    2. Update the .vstemplate file to contain the name of the icon, without any path information. The icon is registered with an Icon element under the TemplateData element.
    3. If you didn't specify an icon when the template was generated then you should create or acquire one now and register it with the .vstemplate as specified above.
  4. Include the project file, template and icon as InstallPrep project items under the template content directory.
    1. Select the InstallPrep project in Solution Explorer.
    2. On the Solution Explorer command bar select Show All Files.
    3. Select each file while holding down the Ctrl key.
    4. Right-mouse click one of the files and select Include In Project.
  5. Save the InstallPrep project.
At this point you have prepared the solution and the InstallPrep project to dynamically include your template into the Visual Studio Content Installer file (.vsi) each time the InstallPrep project is built. Next, you have to get the InstallPrep project to actually include your template's contents.

Add the following near similar commands in the BatchOutput.bat file found in the InstallPrep project:

CALL :ZIP_TEMPLATE "%TemplateDirRoot%\ProjectName" TemplateName
IF %ERRORLEVEL% NEQ 0 EXIT

Make the following substitutions to the code:
  • ProjectName must be the name of the project's directory (it must exist under the solution's binding root). For example, JSharpContosoDocProjectTemplate.
  • TemplateName must be the actual template's name, which will be used to name the .zip file. (Normally, it's the same as ProjectName).
Next, you have to configure the installer (.vsi) to include your template. Update the Contents\Installer\DocProjectContent.vscontent file in the InstallPrep project to include the new template by adding a new Content element. The FileName element should contain the value specified for TemplateName in the modifications to the BuildOutput.bat file that you made previously, with .zip appended to the end.

Example:
<Content>
  <FileName>JSharpContosoDocProjectTemplate.zip</FileName>
  <DisplayName>Contoso DocProject Template (Visual J#)</DisplayName>
  <Description>
<![CDATA[Installs the Contso J# DocProject template, which builds a single compiled help file for all of its project references.

The template, "Contoso Project Documentation", appears under the Visual J# language projects.]]>
  </Description>
  <FileContentType>VSTemplate</FileContentType>
  <ContentVersion>1.0</ContentVersion>
  <Attributes>
    <Attribute name="ProjectType" value="Visual J#" />
    <Attribute name="ProjectSubType" value="DocProject"/>
    <Attribute name="TemplateType" value="Project"/>
  </Attributes>
</Content>

For more information about the .vscontent file see How to: Publish Project Templates and Visual Studio Content Installer Schema Reference.

You should make sure that everything works correctly before continuing:
  1. Build the InstallPrep project and check that the .vsi file is created successfully. Information about the build process and any error messages will be displayed in Visual Studio's build output window.
    1. Note: You will need the DSZip utility to perform this step. If you haven't done so already, download the DSZip utility from the Releases tab and install it.
  2. Browse to the .vsi file and double-click it to make sure that it's valid, but cancel the installation.
    1. The .vsi file will be located in the root of the InstallPrep project. Use the Show All Files command in Visual Studio's Solution Explorer to find it.
If you want to use the Installer project then you must add your template manually:
  1. Follow the steps above to have the InstallPrep project zip your template files.
  2. Select the Installer project node in Solution Explorer.
  3. Click the File System Editor toolbar icon above Solution Explorer.
  4. Browse to {App Folder}\Setup\Templates.
  5. Add your zipped template.
    1. If the InstallPrep project built successfully then your zipped template should appear in the {InstallPrep}\Contents\Templates directory.
You only have to perform these steps once. After you add the template to the installer, building the InstallPrep project will automatically update the Installer's sources. The Installer project will import the latest version of your template automatically each time it's built.

Configure the Template

To make the required changes to the project file:
  1. Make sure the project is saved if you aren't using the DocProject solution, otherwise it doesn't matter since you will be editing a copy of the project file instead.
    1. Note: Visual Studio will ask you to reload the project after you modify the file on disk (unless you're following the DocProject solution instructions).
  2. Open the project file (e.g., .csproj, .vbproj, .vjsproj) in notepad or Visual Studio.
    1. Note: If you have been following the instructions for adding a template to the DocProject solution then open the project file from the template content directory (see Configure the DocProject Solution).
  3. If you have added a default Build Process Component to your template (see Create a Project), then add an ItemGroup element to the Project element that references the Add-In assembly in the GAC. (See the example below.)
  4. To turn this plain old Visual Studio template into a DocProject or DocSite template, you must:
    1. add a reference to the DaveSexton.DocProject assembly. (This is only required if a default build process component is included in the template.)
    2. add an Import element that references DaveSexton.DocProject.targets.
    3. ensure that a UserProperties element is present with the appropriate attributes and values.
Here is an example project file with the required additions:

<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  [...]

  <ItemGroup>
    <Reference Include="DaveSexton.DocProject, Version=#.#.#.#, Culture=neutral, 
      PublicKeyToken=af1a4bab65cc4ece, processorArchitecture=MSIL">
      <SpecificVersion>False</SpecificVersion>
    </Reference>
  </ItemGroup>

  <!-- add the following line immediately after all other Import elements -->
  <Import Project="$(DocProjectBuildPath)\DaveSexton.DocProject.targets" />

  <ProjectExtensions>
    <VisualStudio>
      <UserProperties IsDocProject="true" />
    </VisualStudio>
  </ProjectExtensions>
</Project>

Note: For templates that target DocProject 2008, the DaveSexton.DocProject.targets import should be: <Import Project="$(DocProjectPath)\2008\bin\DaveSexton.DocProject.targets" />.

Make sure that you specify the latest version number of the assembly. To discover the latest version number, find the DaveSexton.DocProject assembly in the GAC by opening Windows Explorer and browsing to the GAC folder, commonly found at C:\windows\assembly. The version number will be listed in a column next to the assembly's name.

The IsDocProject attribute indicates that projects created from your template should be built by DocProject. This attribute is required for both DocProjects and DocSites.

Custom Configuration
You may want to configure some of your template files at this point, including the project file, to add replacement tokens. For more information, see How to: Substitute Parameters in a Template.

For example, you'll probably want the root namespace and assembly name for projects created from your template to be the name of the project given by the user when the project is created. You must update two elements as follows:

<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    [...]

    <RootNamespace>$safeprojectname$</RootNamespace>
    <AssemblyName>$safeprojectname$</AssemblyName>
  </PropertyGroup>
</Project>

The $safeprojectname$ token will insert the project name entered by the user, making sure that spaces and symbols are replaced with an underscore (). For code files such as a default Build Process Component_ you may have to update the source to replace the hard-coded namespace with the $safeprojectname$ token.

For example, a build process component in a C# application could be modified to look like this:

using System;
using DaveSexton.DocProject;
using DaveSexton.DocProject.Engine;

namespace $safeprojectname$
{
  public class BuildProcess : BuildProcessComponent
  {
    [...]
  }
}

These changes can be made to the code files directly in the project itself even though Visual Studio may add some warnings or errors to the task list. A template project is not intended to be built, so these warnings and errors can be safely ignored. For more information, see How To Use The Source Code, Troubleshooting.

Note: You must modify the .vstemplate file as well for any project items that require replacement tokens. For more information, see How to: Substitute Parameters in a Template.

Default Build Process Component (Optional)
If you have added a default Build Process Component to your template then you'll want to register it in the project file. Simply add a new ProcessComponentTypeName attribute to the UserProperties element in your project file. Specify the full type name of your component.

For example, if you have placed your default Build Process Component class named, BuildProcess, inside of the root namespace and you've modified the project file to use the $safeprojectname$ replacement token, then you would add a ProcessComponentTypeName attribute like this:

  [...]
  <ProjectExtensions>
    <VisualStudio>
      <UserProperties IsDocProject="true" ProcessComponentTypeName="$safeprojectname$.BuildProcess" />
    </VisualStudio>
  </ProjectExtensions>

Install the Template

You must install the new template into Visual Studio before you can use it to create a new project.

Using the DocProject Solution
If you have followed the instructions in this tutorial and added your template to the DocProject solution, then building the InstallPrep project will create a new Visual Studio Content Installer file (.vsi) that contains your template. Simply double-click the .vsi file and the wizard will install the template into Visual Studio. You'll find the .vsi file in the root directory of the InstallPrep project, although the file will not be included as a project item.

Note: You may want to uncheck the add-in and any existing templates when prompted by the wizard. The add-in cannot be overwritten; however, if you attempt to install existing templates again, the wizard will ask you if you want to skip the template or overwrite the existing one.

Using a Custom Solution
If you didn't use the DocProject solution:
  1. Follow the instructions in Export the Template now to extract a .zip file from your template project and then return to the next step.
  2. Read How to: Publish Project Templates for instructions on creating your own .vsi file.
    1. Alternatively, you can just copy the template's .zip file to the appropriate directory on your system, which is usually found at My Documents\Visual Studio 2005\Templates\ProjectTemplates\{language}\DocProject, where {language} is one of Visual Basic, Visual C# or Visual J#.

Test the Template

Open a new instance of Visual Studio to test your template after it has been installed.

If you have been using the DocProject solution then you can press F5 to start and attach to a new instance of Visual Studio. You still need to run the .vsi file to install your template before it will show up in the Add New Project... dialog, but you only need to do that once. If you make a modification to the project file, template file or any code or content files in the template's project then you must build the InstallPrep project and run the .vsi again, overwriting the existing template when you are prompted.

Create or open an existing solution and try to add a new project based on your template. For instructions see the tutorial: Creating a DocProject for a new solution.

Last edited Mar 6, 2008 at 11:32 AM by davedev, version 41

Comments

No comments yet.