Creating Project Templates Using the Project Template Generation Tool (Projectgen.exe)

Creating Project Templates Using th...

Visual Studio Tools for Applications

Visual Studio Tools for Applications includes the Project Template Generation tool (Projectgen.exe), which generates all of the files that make up a Visual Studio project template. For more information about project template files, see Creating Project Templates (Visual Studio Tools for Applications).

Projectgen.exe is available in two modes, depending on whether you want to use a graphical user interface:

Wizard mode
Command-line mode

Wizard Mode

The Project Template Wizard steps you through the process of creating a project template. Before you run Projectgen.exe in wizard mode, you must complete the following prerequisites:

Register your host application. For more information, see How to: Register the Host Application.
Create a proxy DLL that describes the object model of your host application. The proxy DLL can be generated using the Proxy Generation tool. For more information, see Creating Proxies and Proxy Generation Tool (ProxyGen.exe).
You must add the proxy DLL to the global assembly cache. For an example of adding a proxy DLL to the global assembly cache, see Walkthrough: Creating a Project Template Using the Project Template Wizard.

Starting and Running the Wizard

To start the Project Template Wizard, double-click the Projectgen.exe executable file. You can also start the Project Template Wizard by running Projectgen.exe from the command line without passing any parameters.

Use the Project Template Wizard to specify a host identifier, host item, and proxy assembly.

Host Identifier

The host identifier is a key that is stored in the registry whenever a host application is registered on the computer. For information about registering a host application, see Host Configuration Registry Key Settings. The host identifier is a required field in the Projectgen.exe wizard; therefore, you must register the host application before you run Projectgen.exe. A valid host identifier is required to ensure that users create a valid descriptor file.

Host Item

You can specify the name of one host item in the Project Template Wizard. You can manually add multiple host items to the XML project descriptor file if required.

A host item is a class in an add-in project that provides a starting point for add-in developers to write their code. Add-in developers use host items to access the object model of the application and to obtain all the objects they use to automate the host application. For example, an add-in developer might have access to a host item class named ThisApplication, and could use a Documents property of this class to get a Document object.

Host items in add-in projects derive from entry point classes in the proxy assembly. An entry point is a proxy type that provides direct access to an object in the object model of the host application. The entry point type is instantiated when the host application loads an add-in. Typically, the entry point is a proxy for a host type at the top of the object model hierarchy, such as an Application class.

You define entry points for your application when you create proxies for the object model of the host application. For more information, see Defining Entry Points and Other Proxy Changes.

Proxy Assembly

Proxies in Visual Studio Tools for Applications wrap a COM type library or a managed assembly to make the object model of the host application accessible to an add-in. The Proxy Generation tool (Proxygen.exe) generates a proxy DLL that contains a proxy for each object in your application's object model. The proxy DLL is used by the Project Template Wizard to create project templates.

For more information about the Proxy Generation tool, see Proxy Generation Tool (ProxyGen.exe).

Template Parameters

You can use template parameter variables in the wizard so that key parameters can be supplied at run time. This is useful in cases where you do not want to hard code absolute paths in the project templates. You can provide the template parameters in the Debug Command Line box of the Project Properties page of the wizard or by manually modifying the project template.

Note:
The project template that Projectgen.exe generates contains paths to files based on the file locations on your computer. If end user computers might have different file locations, you must modify the project template so that it uses correct paths. For example, you can replace paths with variables. For more information about variables, see Project Template Generation Tool (Projectgen.exe).

Project Template Wizard Output

The Project Template Wizard generates both a project template and an XML project descriptor file. After you have an XML project descriptor file, you can run Projectgen.exe from the command line. The XML project descriptor file that is generated by the Project Template Wizard is a required input parameter when you run Projectgen.exe from the command line.

You specify the location where you want to store the template project in the Project Template Wizard. This location should be the same location specified by the ProjectTemplatesLocation registry key that was created when you registered the host, but you can modify the location. The Project Template Wizard generates project templates for Visual Basic and Visual C#. The wizard adds subfolders under the directory that you specify. The subfolders are Language\HostID\LocaleID. The project template is named TemplateName.zip.

If you select the Register template with host application check box in the Project Template Wizard, Projectgen.exe automatically registers the templates so that they appear in the Visual Studio Tools for Applications integrated development environment (IDE). You can also register the templates with the host application by registering the host application again. If you specify a location for the project templates that is different from the location that is specified in the registry and you choose to register the templates, Projectgen.exe copies the templates to both file locations. For more information about registering a host application, see How to: Register the Host Application.

Command-Line Mode

The command-line mode is useful if you want to automate project template creation as part of the build process. Before you run Projectgen.exe in command-line mode, you must complete the following prerequisites:

Register your host application. For more information, see How to: Register the Host Application.
Create a proxy DLL that describes the object model of your host application. The proxy DLL can be generated by using the Proxy Generation tool (Proxygen.exe). For more information, see Creating Proxies and Proxy Generation Tool (ProxyGen.exe).
Create an XML project descriptor file. The Project Template Generation wizard generates this file automatically, so you can run Projectgen.exe in wizard mode and then use the output file as input for command-line mode. You can also create the file manually. For more information, see Descriptor Schema for Projectgen.exe.

Running Projectgen.exe from the Command Line

When you run Projectgen.exe from the command line, you must pass the necessary input and output parameters, in addition to any optional parameters. The XML project descriptor file is a required input parameter. For more information, see Project Template Generation Tool (Projectgen.exe).

You specify the location where you want to store the template project in an output parameter. This location should be the same location specified by the ProjectTemplatesLocation registry key that was created when you registered the host, but you can modify the location.

Projectgen.exe Output

Projectgen.exe generates project templates for Visual Basic and Visual C# and then saves the templates in subfolders of the project template location you specified. For example, the following command uses an XML project descriptor file named projectdescriptor.xml to create project templates under C:\MyApp\ProjectTemplates.

projectgen.exe /i:"C:\MyApp\projectdescriptor.xml" /o:"C:\MyApp\ProjectTemplates\"

You can register the templates with the host application by registering the host application. If you specify a location for the project templates that is different from the location that is specified in the registry, you must copy the project templates to the location specified in the registry before registering the host application. For more information about registering a host application, see How to: Register the Host Application.

XML Project Descriptor File

The XML project descriptor file contains the data needed to create a project template, including the following information:

A <TemplateProperties> node that contains information about the template, such as the name of the template as it will appear in the Visual Studio Add Project dialog box, a description of the template, and the icon to be associated with the template.
A <ProjectProperties> node that contains information about the project, such as the project name as it will appear in Project Explorer, the host identifier, and information about any host items in the project. This section of the XML project descriptor file also contains any references to managed assemblies and COM assemblies.
The location of the proxy DLL, indicated in the <ProxyAssemblyName> node.

The XML project descriptor file must be based on a specific schema. For more information, see Descriptor Schema for Projectgen.exe. The following is an example of an XML project descriptor file.

<ProjectGen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <TemplateProperties>
    <Name>ShapeAppMFC Add-in</Name>
    <Description>A project for creating add-ins for
      ShapeAppMFC</Description>
    <DefaultProjectName>ShapeAppMFC</DefaultProjectName>
    <Icon>C:\ShapeAppSamples\ShapeAppIcon.ico</Icon>
  </TemplateProperties>
  <ProjectProperties>
    <HostName>ShapeAppMFC</HostName>
    <DebugInfoExeName>C:\ShapeAppSamples\ShapeAppMFC\
      debug\ShapeAppMFC.exe</DebugInfoExeName>
    <DebugInfoCommandLine />
  <HostIdentifier>ShapeAppMFC</HostIdentifier>
  <IconImageList />
  <HostItems>
    <HostItem>
      <ProxyAssemblyName>C:\ShapeAppSamples\ShapeAppMFCLib\
        ShapeAppMFCLib\bin\Debug\ShapeAppMFCLib.dll</ProxyAssemblyName>
      <HostItemName>ThisApplication</HostItemName>
        <BaseType>ShapeApp.Proxy.ApplicationEntryPoint</BaseType>
        <PrimaryCookie>ThisApplication</PrimaryCookie>
      </HostItem>
    </HostItems>
    <References>
      <Reference Include="System.Windows.Forms" />
    </References>
    <COMReferences>
      <COMReference Include="MAPI">
        <Guid>3fa7dea7-6438-101b-acc1-00aa00423326</Guid>
        <VersionMajor>1</VersionMajor>
        <VersionMinor>21</VersionMinor>
        <WrapperTool>Tlbimp</WrapperTool>
      </COMReference>
    </COMReferences>
  </ProjectProperties>
</ProjectGen>