Skip to content

Commit a0fd7e9

Browse files
gewarrengewarren
authored
Merge pull request #383 from peteraritchie/patch-2
More realistic flow of steps, with project template detail
2 parents 061909e + f13ef75 commit a0fd7e9

File tree

1 file changed

+71
-45
lines changed

1 file changed

+71
-45
lines changed

‎docs/ide/how-to-create-multi-project-templates.md

Lines changed: 71 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -22,69 +22,95 @@ ms.workload:
2222
---
2323
# How to: Create Multi-Project Templates
2424
Multi-project templates act as containers for two or more projects. When a project based on a multi-project template is created from the **New Project** dialog box, every project in the template is added to the solution.
25+
26+
A multi-project template is two-or more project templates along with a root template of type `ProjectGroup`.
27+
28+
Multi-project templates also behave differently than normal templates. Multi-project templates have the following unique characteristics:
2529

26-
A multi-project template must include the following items, compressed into a .zip file:
27-
28-
- A root .vstemplate file for the entire multi-project template. This root .vstemplate file contains the metadata that the **New Project** dialog box displays, and specifies where to find the .vstemplate files for the projects in this template. This file must be located at the root of the .zip file.
29-
30-
- One or more folders that contain the files that are required for a complete project template. This includes all code files for the project, and also a .vstemplate file for the project.
30+
- Individual projects in a multi-project template cannot be assigned names by the **New Project** dialog box. Instead, use the `ProjectName` attribute on the `ProjectTemplateLink` element to specify the name for each project. For more information, see the first example in the following section.
3131

32-
For example, a multi-project template .zip file that has two projects could have the following files and directories:
32+
- Multi-project templates can contain projects written in different languages, but the entire template itself can only be put in one category by using the `ProjectType` element.
3333

34-
MultiProjectTemplate.vstemplate
34+
### To create a multi-project template
3535

36-
\Project1\Project1.vstemplate
36+
1. Create the projects to include in the multi-project template:
37+
1. Create a project.
3738

38-
\Project1\Project1.vbproj
39+
> [!NOTE]
40+
> Use only valid identifier characters when naming a project that will be the source for a template. A template exported from a project named with invalid characters can cause compilation errors in future projects based on the template. For more information on valid identifier characters, see [Declared Element Names](/dotnet/visual-basic/programming-guide/language-features/declared-elements/declared-element-names).
3941
40-
\Project1\Class.vb
42+
2. Edit the project until it is ready to be exported as a template.
4143

42-
\Project2\Project2.vstemplate
44+
3. As appropriate, edit the code files to indicate where parameter replacement should take place. For more information on parameter replacement, see [How to: Substitute Parameters in a Template](../ide/how-to-substitute-parameters-in-a-template.md).
4345

44-
\Project2\Project2.vbproj
46+
4. On the **Project** menu, click **Export Template**. The **Export Template** wizard opens.
4547

46-
\Project2\Class.vb
48+
5. Click **Project Template**.
4749

48-
The root .vstemplate file for a multi-project template differs from a single-project template in the following ways:
50+
6. If you have more than one project in your current solution, select the projects you want to export to a template.
4951

50-
- The `Type` attribute of the `VSTemplate` element contains the value `ProjectGroup`. For example:
52+
7. Click **Next**.
5153

52-
```
53-
<VSTemplate Version="2.0.0" Type="ProjectGroup"
54-
xmlns="http://schemas.microsoft.com/developer/vstemplate/2005">
55-
```
54+
8. Select an icon and a preview image for your template. These will appear in the **New Project** dialog box.
5655

57-
- The `TemplateContent` element contains a `ProjectCollection` element that has one or more `ProjectTemplateLink` elements that define the paths to the .vstemplate files of the included projects. For example:
56+
9. Enter a template name and description.
5857

59-
```
60-
<TemplateContent>
61-
<ProjectCollection>
62-
<ProjectTemplateLink>
63-
Project1\Project1.vstemplate
64-
</ProjectTemplateLink>
65-
<ProjectTemplateLink>
66-
Project2\Project2.vstemplate
67-
</ProjectTemplateLink>
68-
</ProjectCollection>
69-
</TemplateContent>
70-
```
71-
72-
Multi-project templates also behave differently than normal templates. Multi-project templates have the following unique characteristics:
73-
74-
- Individual projects in a multi-project template cannot be assigned names by the **New Project** dialog box. Instead, use the `ProjectName` attribute on the `ProjectTemplateLink` element to specify the name for each project. For more information, see the first example in the following section.
75-
76-
- Multi-project templates can contain projects written in different languages, but the entire template itself can only be put in one category by using the `ProjectType` element.
77-
78-
### To create a multi-project template
79-
80-
1. Create the projects to include in the multi-project template.
81-
82-
2. Create .vstemplate files for every project. For more information, see [How to: Create Project Templates](../ide/how-to-create-project-templates.md).
58+
10. Click **Finish**. Your project is exported into a .zip file and placed in the specified output location, and, if selected, imported into [!INCLUDE[vsprvs](../code-quality/includes/vsprvs_md.md)].
8359

60+
2. Extract the .vstemplate file from the generated zip file into the same directory as the project file used to export the template.
61+
8462
3. Create a root .vstemplate file that to contain the metadata for the multi-project template. For more information, see the first example in the following section.
8563

8664
4. Select the files and folders to include in your template, right-click the selection, click **Send To**, and then click **Compressed (zipped) Folder**. The files and folders are compressed into a .zip file.
8765

66+
> [NOTE!]
67+
> A multi-project template must include the following items, compressed into a .zip file:
68+
>
69+
> - A root .vstemplate file for the entire multi-project template. This root .vstemplate file contains the metadata that the **New Project** dialog box displays, and specifies where to find the .vstemplate files for the projects in this template. This file must be located at the root of the .zip file.
70+
>
71+
> - One or more folders that contain the files that are required for a complete project template. This includes all code files for the project, and also a .vstemplate file for the project.
72+
>
73+
> For example, a multi-project template .zip file that has two projects could have the following files and directories:
74+
>
75+
> MultiProjectTemplate.vstemplate
76+
>
77+
> \Project1\Project1.vstemplate
78+
>
79+
> \Project1\Project1.vbproj
80+
>
81+
> \Project1\Class.vb
82+
>
83+
> \Project2\Project2.vstemplate
84+
>
85+
> \Project2\Project2.vbproj
86+
>
87+
> \Project2\Class.vb
88+
>
89+
> The root .vstemplate file for a multi-project template differs from a single-project template in the following ways:
90+
>
91+
> - The `Type` attribute of the `VSTemplate` element contains the value `ProjectGroup`. For example:
92+
>
93+
> ```
94+
> <VSTemplate Version="2.0.0" Type="ProjectGroup"
95+
> xmlns="http://schemas.microsoft.com/developer/vstemplate/2005">
96+
> ```
97+
>
98+
> - The `TemplateContent` element contains a `ProjectCollection` element that has one or more `ProjectTemplateLink` elements that define the paths to the .vstemplate files of the included projects. For example:
99+
>
100+
> ```
101+
> <TemplateContent>
102+
> <ProjectCollection>
103+
> <ProjectTemplateLink>
104+
> Project1\Project1.vstemplate
105+
> </ProjectTemplateLink>
106+
> <ProjectTemplateLink>
107+
> Project2\Project2.vstemplate
108+
> </ProjectTemplateLink>
109+
> </ProjectCollection>
110+
> </TemplateContent>
111+
> ```
112+
>
113+
88114
5. Put the .zip template file in the [!INCLUDE[vsprvs](../code-quality/includes/vsprvs_md.md)] project template directory. By default, this directory is \My Documents\Visual Studio *Version*\Templates\ProjectTemplates\\.
89115

90116
## Example
@@ -153,4 +179,4 @@ Multi-project templates act as containers for two or more projects. When a proje
153179
[How to: Create Project Templates](../ide/how-to-create-project-templates.md)
154180
[Visual Studio Template Schema Reference](../extensibility/visual-studio-template-schema-reference.md)
155181
[SolutionFolder Element (Visual Studio Templates)](../extensibility/solutionfolder-element-visual-studio-templates.md)
156-
[ProjectTemplateLink Element (Visual Studio Templates)](../extensibility/projecttemplatelink-element-visual-studio-templates.md)
182+
[ProjectTemplateLink Element (Visual Studio Templates)](../extensibility/projecttemplatelink-element-visual-studio-templates.md)

0 commit comments

Comments
 (0)