Creating a Template Using Subproject Wizards
Collapse the table of content
Expand the table of content
The document is archived and information here might be outdated

Walkthrough: Creating a Template Using Subproject Wizards

Visual Studio .NET 2003

Enterprise Template projects support the ability to point to wizards to create subprojects, rather than pointing to static project prototypes. By creating a wizard-based template, you can use built-in script support to customize the project at creation time. The standard distributed application templates use this feature to generate appropriate namespace and assembly names.

When creating a template using static prototypes, you can create the initial structure in Solution Explorer and then convert it to a template. When working with a template using wizards, the process is more manual. This section describes how to create the same initial project structure shown in Walkthrough: Creating a New Enterprise Template, but you create that project structure using Subproject Wizards. The initial steps are familiar because they match the ones provided in Walkthrough: Creating a New Enterprise Template for using static project prototypes. They are repeated here for clarity. For more information, see Enterprise Template Projects and the ETP Schema.

The initial parts of the process involved in creating a template are the same as for creating a distributed application. After creating the structure and associating a policy file with it, you edit some files and refine the structure so it better reflects its purpose as a template on which to base future applications.

To create the initial application structure

  1. Launch Visual Studio.
  2. On the File menu, point to New, then click Project.
    The New Project dialog box displays.
  3. In the Project Types pane, expand the Other Projects folder and select the Enterprise Template Projects folder. The Templates pane displays a number of icons. Select Enterprise Template Project. Avoid double-clicking it so that you can assign a custom name before creating the project.
    Note   Do not expand the Enterprise Template Projects folder and select one of the subfolders in the left pane. Those folders contain language projects that are used as building blocks, rather than as entire templates.
  4. Replace the default project name with MyWizTemplate.
  5. Take note of the pathname in the Location box. In a later step, you will copy the project to another location. Click OK. The MyWizTemplate project now populates Solution Explorer.

Continue creating the structure of this template by adding the nested .etp projects.

To create the nested Enterprise Template (.etp) projects

  1. Select MyWizTemplate in Solution Explorer.
  2. On the File menu, point to Add Project, then click New Project.
    The Add New Project dialog box appears.
  3. Select Enterprise Template Projects, and then select Enterprise Template Project in the Templates pane.
  4. Change the project name to BackendProjects, and then click OK.
    The BackendProjects project appears in Solution Explorer.
  5. Repeat this process two times, changing the name to UIProjects the first time and to UtilityProjects the second time.

You should now have the basic structure of a template for a distributed application.

Associating Policy With the Initial Application Structure

Before converting this application structure into a Template you need to associate a policy file with it. You could create a policy file from scratch, which is explained in detail in the documentation. For more information about policy files, see Enterprise Template Policy Overview. However, in most situations, the quickest and least error-prone way to associate a policy file with an application is to simply rename a copy of the DAP.tdl file and customize it as needed. In this walkthrough, you take a shortcut by cloning the DAP.tdl file, renaming your copy, and then modifying it as necessary.

To associate a policy file with your project

  1. If the Properties window is not already visible, select the MyWizTemplate node in Solution Explorer (not Solution 'MyWizTemplate'), right-click, and select Properties.
  2. In the Properties window, locate Policy File in the left column of the grid. Click in the blank field to the right of the Policy File field and an ellipsis button (...) appears in the field.
  3. Click the ellipsis button to open the Select a TDL File dialog box.
  4. If you already created MyPolicy.tdl while working through Walkthrough: Creating a New Enterprise Template, skip ahead to step 7. Otherwise, in the dialog box, select the DAP.tdl file and press Ctrl+C to copy it.
  5. Press Ctrl-V to paste a copy of the file so it appears with the other .tdl files.
  6. Right-click on the copy you just made and rename it MyPolicy.tdl.
  7. Select MyPolicy.tdl and click Open to associate MyPolicy.tdl with the current application.
  8. When prompted to reload the project, click Yes.
    In the Properties window, the field to the right of Policy File now displays MyPolicy.tdl when you select MyWizTemplate in Solution Explorer.

At this point, you have created the initial application structure and it is ready to convert and save as a template on which to base your own distributed application projects. Next, you need to convert the initial project structure into the beginnings of a template.

To organize folders and files

  1. Locate the initial application structure you created in Visual Studio. The default install point for MyWizTemplate should look like the following:
    C:\Documents and Settings\UserName\My Documents\Visual Studio Projects\MyWizTemplate 
    
  2. Copy the entire MyWizTemplate folder into the following folder:
    C:\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Projects
    

Cleaning up the Project Structure

Unlike distributed applications, templates such as the one you are creating do not use all the files and folders that appear in the project's directory structure. When a development team creates a distributed application from the template, the folders and files are created again for the particular application. Accordingly, you should remove these folders and files to prevent later confusion.

To remove unnecessary folders and files

  1. Within MyWizTemplate's .etp projects (BackendProjects, UIProjects, and UtilityProjects), the subfolders each contain ".eto" files. Delete these files.
  2. In the folder named MyWizTemplate, delete the *.sln and *.suo files.

Editing the .etp Project File

You need to make a few minor edits in ...\EnterpriseFrameworks\Projects\MyWizTemplate\MyWizTemplate.etp

Removing the project GUID

  1. Open MyWizTemplate.etp in Notepad or any text editor and remove the 3 <GUIDPROJECTID> lines. Each line will look similar to the following:
       <GUIDPROJECTID>{4CB5C3A7-3FBC-4B47-ADEB-F19768CB91C3}</GUIDPROJECTID>
    
  2. Save and close the file.

Adding a UserProperty/Project Global value to the Project Files

The next step is to prepare the project files with information that allows your policy file, MyPolicy.tdl, to identify them as ELEMENT nodes. To accomplish this, you need to add a UserProperty/project global value to each project file.

The following table lists the affected files and the necessary additions. You can use Notepad or any text editor to make these changes.

Filename Change Details
MyWizTemplate.etp To the <GLOBALS> section, add an additional GLOBALENTRY node.
<GLOBALS>
  <GLOBALENTRY>
    <NAME>TDLFILE</NAME>
    <VALUE>MyPolicy.tdl</VALUE>
  </GLOBALENTRY>
  <GLOBALENTRY>
    <NAME>TDLELEMENTTYPE</NAME>
    <VALUE>etpMyWizTemplate</VALUE>
  </GLOBALENTRY>
</GLOBALS>

BackendProjects.etp To the <GLOBALS> section, add an additional GLOBALENTRY node.
<GLOBALS>
  <GLOBALENTRY>
    <NAME>TDLFILE</NAME>
    <VALUE>MyPolicy.tdl</VALUE>
  </GLOBALENTRY>
  <GLOBALENTRY>
    <NAME>TDLELEMENTTYPE</NAME>
    <VALUE>etpBackendProjects</VALUE>
  </GLOBALENTRY>
</GLOBALS>

UIProjects.etp Add to the <GLOBALS> section an additional GLOBALENTRY node.
<GLOBALS>
  <GLOBALENTRY>
    <NAME>TDLFILE</NAME>
    <VALUE>MyPolicy.tdl</VALUE>
  </GLOBALENTRY>
  <GLOBALENTRY>
    <NAME>TDLELEMENTTYPE</NAME>
    <VALUE>etpUIProjects</VALUE>
  </GLOBALENTRY>
</GLOBALS>

UtilityProjects.etp To the <GLOBALS> section, add an additional GLOBALENTRY node.
<GLOBALS>
  <GLOBALENTRY>
    <NAME>TDLFILE</NAME>
    <VALUE>MyPolicy.tdl</VALUE>
  </GLOBALENTRY>
  <GLOBALENTRY>
    <NAME>TDLELEMENTTYPE</NAME>
    <VALUE>etpUtilityProjects</VALUE>
  </GLOBALENTRY>
</GLOBALS>

At this point, you have the initial template structure. Now you need to connect the subproject wizards up by manually editing the ETP files.

Using Subproject Wizards

The easiest way to create a subproject wizard is to copy one of the existing Visual Studio wizards and then customize it as needed. For this walkthrough, you will be basing the three language projects on the standard wizards for an XML Web service created using ASP.NET, a Windows Application project, and a Class Library project. Although this walkthrough uses the Visual C# versions, you could just as easily use Visual Basic.

Inside the EnterpriseFrameworks folder is a folder called EFWizards. Your Subproject wizards reside in this folder. CSharpDllWiz creates a Class Library, and CSharpExeWiz creates a Windows Application. Instead of using the standard Wizards in the EFWizards folder, you can make copies that you can customize to meet your own project needs.

To create customizable copies of the standard Enterprise Template wizards

  1. Locate the EFWizards folder in Visual Studio. The default install point for it is as follows.
    C:\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\EFWizards
    
  2. Copy the csharpdllwiz folder and paste a copy (in the EFWizards folder), renaming it "utilitylibwiz".
  3. Copy the csharpexewiz folder and paste a copy, renaming it "winappwiz".
  4. Copy the csharpwebservicewiz folder and paste a copy, renaming it "webservicewiz".

You now have local copies of the wizards that you can customize for your template. The project structure for wizards is as follows:

WizardFolder

    Scripts

        langid

    Templates

        langid

The Scripts\langid folder contains the custom script for this wizard. The standard script (and the majority of the script used during project creation) is the standard Visual C# project script. Probably the most useful piece of the script that can be changed is the OnFinish() function.

The Templates\langid folder contains the project items that are added to the project by the wizard. Examine the code files and notice the use of [!output SAFE_NAMESPACE_NAME] and [!output SAFE_CLASS_NAME]. These are replaceable parameters that will be populated by the wizard at project creation time. Before you can connect your wizards to the template, you must create both initial .csproj files and a .vsz file for each wizard that specifies the parameters to be passed to the wizard.

To create the necessary .csproj files

  1. Locate the EnterpriseFrameworks\Projects\CSharp Building Blocks folder in Visual Studio. The default install point for it is as follows.
    C:\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Projects\CSharp Building Blocks
    
  2. Make a copy of "BusinessFacade.csproj" in the same folder and name the copy "UtilityLibrary.csproj". Make a copy of "WinUI.csproj" and name the copy "WinApp.csproj". Make a copy of "WebService.csproj" and name the copy "WebSvc.csproj". These are empty project files to which the wizard adds project items.
  3. Edit each of the new files as follows, changing the TDLFILE and TDLELEMENTTYPE UserProperties:
    Filename Change Details
    WebSvc.csproj After the <Files></Files> section and before the closing </CSHARP> tag, edit the <UserProperties> section.
        </Files>
        <UserProperties
            TDLFILE = "MyPolicy.tdl"
            TDLELEMENTTYPE = "WebService"
        />
    
    </CSHARP>
    
    
    WinApp.csproj After the <Files></Files> section and before the closing </CSHARP> tag, edit the <UserProperties> section.
        </Files>
        <UserProperties
            TDLFILE = "MyPolicy.tdl"
            TDLELEMENTTYPE = "WinApp"
        />
    
    </CSHARP>
    
    
    UtilityLibrary.csproj After the <Files></Files> section and before the closing </CSHARP> tag, edit the <UserProperties> section.
        </Files>
        <UserProperties
            TDLFILE = "MyPolicy.tdl"
            TDLELEMENTTYPE = "UtilityLibrary"
        />
    
    </CSHARP>
    
    

To create the necessary .vsz files

  1. Find the location of the ProxyProjects\CSharp Building Blocks folder in Visual Studio. The default install point for it is as follows.
    C:\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\ProxyProjects\CSharp Building Blocks
    
  2. Make a copy of "CSharpDistributedApplicationProjects.vsdir" in the same folder, name the copy "MyBlocks.vsdir", and edit the resulting file to look as follows:
    ..\..\Projects\csharp building blocks\UtilityProject.vsz|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|MyUtilityProject|10|Utility Project Wizard|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|127|0|UtilityLibrary
    ..\..\Projects\csharp building blocks\WebSvc.vsz|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|MyWebService|60|Web Service Wizard|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|131|1|WebService|web
    ..\..\Projects\csharp building blocks\WinApp.vsz|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|MyWindowsApplication|70|Windows Application Wizard|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|132|0|WinApp
    
  3. Locate the EnterpriseFrameworks\Projects\CSharp Building Blocks folder in Visual Studio. The default install point for it is as follows.
    C:\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Projects\CSharp Building Blocks
    
  4. Create 3 new empty files named "WebSvc.vsz", "WinApp.vsz", and "UtilityLibrary.vsz". Add the following content to each file as specified below:
    File Contents
    UtilityLibrary.vsz
    VSWIZARD 7.0
    Wizard=VsWizard.VsWizardEngine
    Param="WIZARD_UI = FALSE"
    Param="WIZARD_NAME = utilitylibwiz"
    Param="PROJECT_TYPE = ETPROJ"
    Param="SCRIPT_COMMON_RELATIVE_PATH = CSPROJ"
    
    Param="EFT_PROTOTYPE = UtilityLibrary.csproj"
    
    
    WinApp.vsz
    VSWIZARD 7.0
    Wizard=VsWizard.VsWizardEngine
    Param="WIZARD_UI = FALSE"
    Param="WIZARD_NAME = winappwiz"
    Param="PROJECT_TYPE = ETPROJ"
    Param="SCRIPT_COMMON_RELATIVE_PATH = CSPROJ"
    
    Param="EFT_PROTOTYPE = WinApp.csproj"
    
    
    WebSvc.vsz
    VSWIZARD 7.0
    Wizard=VsWizard.VsWizardEngine
    Param="WIZARD_UI = FALSE"
    Param="WIZARD_NAME = webservicewiz"
    Param="PROJECT_TYPE = ETPROJ"
    Param="SCRIPT_COMMON_RELATIVE_PATH = CSPROJ"
    
    Param="EFT_PROTOTYPE = WebSvc.csproj"
    
    

To connect the wizards to the Template:

  1. Locate the Projects\MyWizTemplate\BackendProjects folder in Visual Studio. The default install point for it is as follows.
    C:\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Projects\MyWizTemplate\BackendProjects
    
  2. Edit the BackendProjects.etp file as shown in the following. Changes to the original are in bold.
    <?xml version="1.0"?>
    <EFPROJECT>
        <GENERAL>
            <BANNER>Microsoft Visual Studio Distributed Application Template FILE</BANNER>
            <VERSION>1.00</VERSION>
            <SUBPROJECTWIZARDS>
                <WIZARD>
                    <FILE>..\..\..\Projects\CSharp Building Blocks\WebSvc.vsz</FILE>
                    <REQUIRESURL>1</REQUIRESURL>
                </WIZARD>
             </SUBPROJECTWIZARDS>
            <Views>
                <ProjectExplorer>
                </ProjectExplorer>
            </Views>
            <References>
            </References>
        </GENERAL>
        <GLOBALS>
            <GLOBALENTRY>
                <NAME>TDLFILE</NAME>
                <VALUE>MyPolicy.tdl</VALUE>
            </GLOBALENTRY>
            <GLOBALENTRY>
                <NAME>TDLELEMENTTYPE</NAME>
                <VALUE>etpBackEndProjects</VALUE>
            </GLOBALENTRY>
        </GLOBALS>
    </EFPROJECT>
    
  3. Within the MyWizTemplate\UIProjects folder, edit UIProjects.etp as shown in bold as follows:
    <?xml version="1.0"?>
    <EFPROJECT>
        <GENERAL>
            <BANNER>Microsoft Visual Studio Distributed Application Template FILE</BANNER>
            <VERSION>1.00</VERSION>
            <SUBPROJECTWIZARDS>
                <WIZARD>
                    <FILE>..\..\..\Projects\CSharp Building Blocks\WinApp.vsz</FILE>
                </WIZARD>
             </SUBPROJECTWIZARDS>
            <Views>
                <ProjectExplorer>
                </ProjectExplorer>
            </Views>
            <References>
            </References>
        </GENERAL>
        <GLOBALS>
            <GLOBALENTRY>
                <NAME>TDLFILE</NAME>
                <VALUE>MyPolicy.tdl</VALUE>
            </GLOBALENTRY>
            <GLOBALENTRY>
                <NAME>TDLELEMENTTYPE</NAME>
                <VALUE>etpUIProjects</VALUE>
            </GLOBALENTRY>
        </GLOBALS>
    </EFPROJECT>
    
  4. Within the MyWizTemplate\UtilityProjects folder, edit UtilityProjects.etp as shown in bold as follows:
    <?xml version="1.0"?>
    <EFPROJECT>
        <GENERAL>
            <BANNER>Microsoft Visual Studio Distributed Application Template FILE</BANNER>
            <VERSION>1.00</VERSION>
            <SUBPROJECTWIZARDS>
                <WIZARD>
                    <FILE>..\..\..\Projects\CSharp Building Blocks\UtilityLibrary.vsz</FILE>
                </WIZARD>
             </SUBPROJECTWIZARDS>
            <Views>
                <ProjectExplorer>
                </ProjectExplorer>
            </Views>
            <References>
            </References>
        </GENERAL>
        <GLOBALS>
            <GLOBALENTRY>
                <NAME>TDLFILE</NAME>
                <VALUE>MyPolicy.tdl</VALUE>
            </GLOBALENTRY>
            <GLOBALENTRY>
                <NAME>TDLELEMENTTYPE</NAME>
                <VALUE>etpUtilityProjects</VALUE>
            </GLOBALENTRY>
        </GLOBALS>
    </EFPROJECT>
    

The above edits connect your wizards to the Template. When the Template is instantiated, the wizard runs, creating the appropriate subprojects (and their corresponding project items).

Two final steps remain to make this new wizard-based template available in the New Project dialog box.

To make MyWizTemplate available in the New Project dialog box

  1. Locate the EnterpriseFrameworks\ProxyProjects folder in Visual Studio. The default install point for it is as follows.
    C:\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\ProxyProjects
    
  2. Within this folder, make a copy of ProxyProjects.vsdir, name the copy "MyProjects.vsdir", and edit the file as shown in the following:
    ..\Projects\MyWizTemplate\MyWizTemplate.etp|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|MyWizTemplate|1|A sample wizard-based template|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|121|0|WizTemplateProject
    
  3. To test your new template, launch Visual Studio, open the New Project dialog box, and select the icon labeled "MyWizTemplate".
  4. If you encounter errors or simply want to double-check your work, see Enterprise Template Walkthrough File Group 4.

See Also

Walkthrough: Adding Building Blocks to the Template | Walkthrough: Creating a New Enterprise Template | Custom Template Walkthroughs | Policy Walkthroughs with TDL Files

Show:
© 2016 Microsoft