ProjectItem Element (Visual Studio Project Templates)

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

Specifies a file that is included in the project template.

System_CAPS_ICON_note.jpg Note

The ProjectItem element accepts different attributes depending on whether the template is for a project or an item. This topic explains the ProjectItem element for project templates. For an explanation of the ProjectItem element for item templates, see ProjectItem Element (Visual Studio Item Templates).

<VSTemplate>
<TemplateContent>
<Project>
<ProjectItem>

<ProjectItem  
    TargetFileName="TargetFileName.ext"  
    ReplaceParameters="true/false"  
    OpenInEditor="true/false"  
    OpenInWebBrowser="true/false"  
    OpenInHelpBrowser="true/false"  
    OpenOrder="Value">  
        FileName.ext  
</ProjectItem>  

The following sections describe attribute, child elements, and parent elements.

Attributes

AttributeDescription
TargetFileNameOptional attribute.

Specifies the name and path of the project item when a project is created from the template. This attribute is useful for creating a directory structure different from the directory structure in the template .zip file, or for using parameter replacement to create an item name.
ReplaceParametersOptional attribute.

A Boolean value that specifies whether the item has parameter values that must be replaced when a project is created from the template. Default value is false.
OpenInEditorOptional attribute.

A Boolean value that specifies whether the item should be opened in its respective editor in Visual Studio when a project is created from the template.

The OpenInWebBrowser and OpenInHelpBrowser attributes are ignored on an item with an OpenInEditor value of true.

The default value is false.
OpenInWebBrowserOptional attribute.

A Boolean value that specifies whether the item should be opened the Web browser when a project is created from the template.

Only HTML files and text files that are local to the project can be opened in the Web browser. External URLs cannot be opened with this attribute.

The default value is false.
OpenInHelpBrowserOptional attribute.

A Boolean value that specifies whether the item should be opened in the Help viewer when a project is created from the template.

Only HTML files and text files that are local to the project can be opened in the Help browser. External URLs cannot be opened with this attribute.

The default value is false.
OpenOrderOptional attribute.

Specifies a numeric value that represents the order that items will be opened in their respective editors. All values must be multiples of 10. Items with higher OpenOrder values are opened first.

Child Elements

None.

Parent Elements

ElementDescription
ProjectSpecifies the files or directories to add to the project.

A text value is required.

A string that represents the name or path to a file in the template .zip file.

ProjectItem is an optional child of Project.

The TargetFileName attribute can be used to create a directory structure different from the directory structure in the template .zip file. For example, if the file MyFile.vb exists in the root of the template .zip file, but you want the file to be placed in a directory named CustomFiles in all projects created from the template, you would use the following XML:

<ProjectItem TargetFileName="CustomFiles\MyFile.vb">MyFile.vb</ProjectItem>  

The TargetFileName attribute can also be used to rename files that contain international characters in their filenames. For example, a template .zip file cannot contain file names with Unicode characters, so the file must be renamed before it can be compressed into a .zip file. The TargetFileName attribute can be used to set the file name back to the original Unicode file name.

The TargetFileName attribute can also be used to rename files with parameters. The following procedure explains how to rename the file MyFile.vb, which exists in the root directory of the template .zip file, to a file name based on the project name.

To rename files with parameters

  1. Use the following XML in the .vstemplate file:

    <ProjectItem TargetFileName="$safeprojectname$.vb">MyFile.vb</ProjectItem>  
    
    
  2. Open the project file (.vbproj for a Visual Basic project) in a text editor or Visual Studio.

  3. Locate the line in the project file that looks similar to the following XML:

    <Compile Include="MyFile.vb">  
    
    
  4. Replace the line of code with the following XML:

    <Compile Include="$safeprojectname$.vb">  
    
    

    When a project is created from this template, the file name will be based on the name the user entered in the New Project dialog box, with all unsafe characters and spaces removed. For more information, see Template Parameters.

The following example shows the metadata for a project template for a Visual C# application.

<VSTemplate Type="Project" Version="3.0.0"  
    xmlns="http://schemas.microsoft.com/developer/vstemplate/2005">  
    <TemplateData>  
        <Name>My template</Name>  
        <Description>A basic starter kit</Description>  
        <Icon>TemplateIcon.ico</Icon>  
        <ProjectType>CSharp</ProjectType>  
    </TemplateData>  
    <TemplateContent>  
        <Project File="MyStarterKit.csproj">  
            <ProjectItem ReplaceParameters="true">Form1.cs<ProjectItem>  
            <ProjectItem>Form1.Designer.cs</ProjectItem>  
            <ProjectItem>Program.cs</ProjectItem>  
            <ProjectItem>Properties\AssemblyInfo.cs</ProjectItem>  
            <ProjectItem>Properties\Resources.resx</ProjectItem>  
            <ProjectItem>Properties\Resources.Designer.cs</ProjectItem>  
            <ProjectItem>Properties\Settings.settings</ProjectItem>  
            <ProjectItem>Properties\Settings.Designer.cs</ProjectItem>  
        </Project>  
    </TemplateContent>  
</VSTemplate>  

Visual Studio Template Schema Reference
Creating Project and Item Templates
Template Parameters
ProjectItem Element (Visual Studio Item Templates)

Show: