Export (0) Print
Expand All

Walkthrough: Creating a New Enterprise Template

Visual Studio .NET 2003

In this walkthrough, you will create an Enterprise Template for creating distributed applications that includes backend projects, user-interface projects, and a library for utility programs. This walkthrough should be useful to anyone who wants to understand how Enterprise Templates simplify the process of developing distributed applications and especially for architects who want to develop their own templates to customize the Visual Studio integrated development environment (IDE) for their own projects and development teams.

This walkthrough contains the following sections:

Before You Begin this Walkthrough

Planning the Template's Initial Application Structure

Creating Initial Prototypes

Associating Policy With the Initial Application Structure

Converting the Initial Implementation into a Template

Making the Template Available to Users

Customizing Your Policy File

Applying Policy Using ELEMENTSET Nodes

Before You Begin this Walkthrough

The following points contain suggestions you should find helpful knowing before you actually begin this walkthrough.

Print the walkthrough

Print this walkthrough to simplify its use. This is particularly helpful if you are using a single machine to read the instructions and carry them out. You will be typing or copying and pasting a significant amount of XML and the easiest approach is to open and print the walkthrough. Keep the walkthrough open but use the hard copy to follow the instructions. When it is necessary to copy-and-paste a block of XML, switch to the walkthrough, find and copy the needed lines, and then paste using Paste as HTML on the Edit menu.

Another option for viewing this topic as you work is to display Help outside of the Visual Studio integrated development environment (IDE). On the Tools menu, select Options. Choose Help from the Environment folder, and then choose External help on the Help Settings page. Note that changes made on the Settings page do not take effect until the integrated development environment (IDE) is restarted.

Confirm or Install Internet Information Services (IIS)

As part of this walkthrough, you will create an XML Web service. The instructions assume you have installed IIS during your installation of Windows 2000 or Windows XP on the development machine you are using. Although IIS is not absolutely required, the steps in the walkthrough provide guidance based on this component. If you are unsure whether this component is already installed, you should take a moment to verify it.

To verify and/or install IIS on your machine

  1. In Windows 2000, click Start, then click Settings, and then click Control Panel. (In Windows XP and Windows Server 2003, there are various ways to open Control Panel, such as through My Computer or directly from the Start menu.)
  2. In Control Panel, find the Add/Remove Programs icon (this is called Add or Remove Programs in Windows XP and Windows Server 2003) and double-click it to display the Add/Remove Programs dialog box.
  3. On the left side of the dialog box, click Add/Remove Windows Components.
  4. In the Add/Remove Windows Components dialog box, find Internet Information Services. If the box is selected, IIS is already installed, and you can skip steps 5 and 6. If it is not selected, select it.
  5. Click Next to start the installation process.
  6. When installation is complete, click Finish to close the wizard.

Display hidden files, folders, and file extensions in Windows Explorer

When editing files in Windows Explorer, the correct items are sometimes difficult to find if files and folders are hidden or file extensions are not visible. Verify your settings in Windows Explorer and change them if necessary.

To display hidden files, folders, and file extensions

  1. Go to the Windows Explorer Tools menu and click Folder Options, then click View.
  2. Find Hidden files and folders, and select Show hidden files and folders.
  3. Find Hide file extensions for known file types and clear the check box.

Architecture of the Template in this Walkthrough

The architecture of the distributed application you create in this walkthrough and then convert to a template is composed of a structure built around a backend, a user interface, and a library of utilities. When you are finished, the template will be fully functional.

This walkthrough provides merely an example of what using a custom Enterprise Template can do for development teams that create distributed applications. You should remember, however, for your templates and distributed applications, that you are not tied to the same choices made in this walkthrough. Flexibility is an important part of the Enterprise Templates concept.

Planning an Enterprise Template

This walkthrough can be separated into several logical divisions, each of which contains smaller steps.

  • Plan the structure and naming scheme for the template.
  • Create an application structure to save as an Enterprise Template.
  • Create and associate a policy file with the application structure.
  • Convert the application structure and policy file into an Enterprise Template.
  • Make the template available to users in the New Project dialog box.
  • Customize the template to increase its usefulness.

Note   The names used in this walkthrough are arbitrary but are consistent with the conventions used in the DAP.tdl file. For more information about naming conventions, see Naming Conventions in Enterprise Templates.

One optional division not included in the list (between the fourth and fifth bullets) above is to connect custom project wizards to the template to generate customized project files. For more information, see Walkthrough: Creating a Template Using Subproject Wizards.

Planning the Template's Initial Application Structure

Creating an Enterprise Template for use with distributed applications involves laying out the structure of an application that meets your project needs and then creating that structure in the Visual Studio IDE. You should be able to leverage the concepts in the structure we show here, even if you completely change the purpose and implementation of your own template.

Structuring and Naming the Template's Parts

Determining in advance the names to use for each of the objects and projects in your Enterprise Template is vital. In this case, the root project is MyTemplate. Accidentally using a different name (etpMyProj, etpMyProject, or MyProj, for example) in other places in the application is a common source of errors. Obviously, you can choose any name but consider using MyTemplate to enhance the instructional value of this walkthrough and minimize distractions.

Enterprise Templates allow you to use two general project types: Enterprise Template projects (.etp file name extension), and language projects (C# in this case). Visual Studio appends the file name extension .etp to the name of each Enterprise Template project and provides a default directory structure complete with a set of files required in many Enterprise Template projects. The following shows the .etp extensions on each of the Enterprise Template projects and the .csproj file name extension on each C# language project:

    MyTemplate.etp

        BackendProjects.etp

            WebService.csproj

        UIProjects.etp

            WinApp.csproj

        UtilityProjects.etp

            UtilityLibrary.csproj

You can create this initial application structure for your template in more than one way. The first way uses static prototypes. It is the simplest process and is used in this walkthrough to provide basic familiarity with the issues involved. The other way uses subproject wizards and provides additional flexibility. For more information, see Walkthrough: Creating a Template Using Subproject Wizards.

Creating Initial Prototypes

The early 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 the solution, you edit some files and refine the structure 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 MyTemplate.
  5. Take note of the pathname in Location. In a later step, you will copy the project to another location. Click OK. The MyTemplate 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 MyTemplate 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 now have the basic structure of a template for a distributed application.

Creating the Language Projects

What you have, so far, is a lot of structure and little apparent functionality. This template's programming functionality is provided by three projects based on the C# language. The most obvious differences between these language projects and the Enterprise Template projects already created are their file extensions and the glyphs associated with them in Solution Explorer.

Since you are creating a template to be used by development teams creating distributed applications, the structure is going to be complex just through the nature of being for this kind of project. Enterprise Template projects (.etp projects) provide the means to enable a more complex structure.

To create the ASP.NET Web Service language project

  1. In Solution Explorer select BackendProjects.
  2. On the File menu, point to Add Project, then click New Project.
    The Add New Project dialog box appears.
  3. Select Visual C# Projects in the Project Types pane.
  4. In the Templates pane, select ASP.NET Web Service.
  5. In the Location box, accept or specify a valid URL and specify the name WebService. Click OK.
    The WebService project appears in Solution Explorer.
    Note   As shown at the beginning of this walkthrough, you should have Microsoft Internet Information Services (IIS) installed on your machine. If IIS is properly installed, your system automatically shows http://localhost next to Location. If an error occurs after clicking OK, check your IIS installation. For more information about installing IIS, see Before You Begin this Walkthrough.

To create the C# Windows Application language project

  1. In Solution Explorer select UIProjects.
  2. On the File menu, point to Add Project, and then click New Project. The Add New Project dialog box appears.
  3. Select Visual C# Projects in the Project Types pane.
  4. In the Templates pane, select Windows Application. Change the name to WinApp and click OK.
    The WinApp project appears in Solution Explorer.

To create the C# Class Library language project

  1. In Solution Explorer select UtilityProjects
  2. On the File menu, point to Add Project, and then click New Project. The Add New Project dialog box appears.
  3. Select Visual C# Projects in the Project Types pane.
  4. In the Templates pane, select Class Library. Change the name to UtilityLibrary and click OK.
    The UtilityLibrary project appears in Solution Explorer.

These prototype projects are used as the basis for actual applications, you (as architect) can specify application settings such as DefaultHTMLPageLayout or StartupObject. You can also specify build configuration settings such as WarningLevel or TreatWarningsAsErrors. The advantage of specifying these settings is that they allow the development team to start their work with the correct defaults.

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 MyTemplate node in Solution Explorer (not Solution 'MyTemplate'), 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. 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 reopen the project, click Yes.
    In the Properties window, the field to the right of Policy File now displays MyPolicy.tdl when you select MyTemplate 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.

Although the next section moves on to the process of converting the application into a template, you could add additional code, controls, and so on to your prototype projects before going on to that part of the process. You do not need to do so during the walkthrough.

Converting the Initial Implementation into a Template

For most project types, converting a structure, such as the one developed in this walkthrough, to a template is rather straightforward. Web projects (including ASP.NET Web Service projects), however, are a bit trickier than the other project types.

Close the solution, save all changes, and exit Visual Studio before proceeding through the following steps to prevent file-sharing problems. In the following procedures you copy the files and folders you created from their current locations to places that better reflect the logic behind the new template.

To locate your template project folders and files

  • In Windows 2000, right-click Start, then click Explore. If you performed default installations of Windows 2000 and Visual Studio .NET, you can locate the EnterpriseFrameworks folder in the directory structure in Windows Explorer under ...\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks. If you did not accept defaults when installing Windows 2000 and Visual Studio .NET, click the Search button in Windows Explorer and search for "EnterpriseFrameworks" on your local drives.

    The EnterpriseFrameworks folder contains a number of subfolders but the following procedures focus on three of them: Policy, Projects, and ProxyProjects.

To organize folders and files

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

    This copies all the files associated with MyTemplate except the WebService project, which has been created in a separate location.

  3. Identify your Web root to determine the location where your WebService project files were created. If you installed to default locations, the project is in the following location:
    C:\Inetpub\wwwroot\WebService 
    
  4. Copy the WebService folder into the BackendProjects folder at the following location:
    C:\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Projects\MyTemplate\BackendProjects
    

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.

Note   If you have not checked the Windows Explorer settings mentioned at the beginning of this walkthrough, do so before proceeding to ensure Windows Explorer displays all files, folders, and file extensions. For details, see Before You Begin this Walkthrough.

To remove unnecessary folders and files

  1. Within MyTemplate's .etp projects (BackendProjects, UIProjects, and UtilityProjects), the subfolders might contain bin or obj subfolders. You have the option of removing these folders, as well as any *.eto files in the BackendProjects, UIProjects, and UtilityProjects folders. Although these folders are unnecessary, their presence does not hinder project functionality.
  2. In the folder named MyTemplate, delete the *.eto, *.sln and *.suo files. Again, this is an optional step, as these files, though unnecessary, are benign.

Editing the .etp Project Files

You need to make a few minor edits in the following files.

  • ...\EnterpriseFrameworks\Projects\MyTemplate\MyTemplate.etp
  • ...\EnterpriseFrameworks\Projects\MyTemplate\BackendProjects\BackendProjects.etp
  • ...\EnterpriseFrameworks\Projects\MyTemplate\UIProjects\UIProjects.etp
  • ...\EnterpriseFrameworks\Projects\MyTemplate\UtilityProjects\UtilityProjects.etp

Removing the project ID

  • All four of the .etp project files contain a line that must be removed. The line occurs three times in MyTemplate.etp but only once each in of the other three. Open each .etp file in Notepad or any text editor and delete the line that resembles the following line:
                    <GUIDPROJECTID>{4CB5C3A7-3FBC-4B47-ADEB-F19768CB91C3}</GUIDPROJECTID>
    
    Note   The value for <GUIDPROJECTID> differs in each of the .etp project files, and the one shown here is an example only.

In addition to the changes made above, Web-related projects require additional modifications that point the Web project to the copy residing in your own projects directory structure, instead of to the single live instance. It is also necessary to provide information that informs the Enterprise Template project file to prompt for a URL when the project is instantiated.

To modify the Web project to prompt for a URL

  • Return to the BackendProjects.etp file and open it in Notepad. A portion of the existing text is shown below, followed by the text with the changes shown in bold:
            <Views>
                <ProjectExplorer>
                    <File>http://MachineName/WebService/WebService.csproj</File>
                </ProjectExplorer>
            </Views>
            <References>
                <Reference>
                    <FILE>http://MachineName/WebService/WebService.csproj</FILE>
                </Reference>
            </References>
    

    Change the file by editing and adding the lines shown in the following:

            <Views>
                <ProjectExplorer>
                    <File>WebService\WebService.csproj</File>
                </ProjectExplorer>
            </Views>
            <References>
                <Reference>
                    <FILE>WebService\WebService.csproj</FILE>
                    <REQUIRESURL>1</REQUIRESURL>
                </Reference>
            </References>
    

    Save and close the file.

Adding a UserProperty or 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 (in a language project) or project global value (in .etp projects) to the GLOBALS section of each project file, as shown below.

The following table lists the affected files and the necessary additions. You can use Notepad or any text editor to make these changes but when you edit your policy file, you should use Visual Studio's XML Designer because of its enhanced functionality.

Filename Change Details
MyTemplate.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>etpMyTemplate</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>

WebService.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>

You have now finished putting together the new template. The next step is to make the template available for creating applications from it. You first need to tell Visual Studio that the template exists and then display its icon in the Add New Project dialog box with the icons for the Enterprise Templates that ship with Visual Studio .NET.

Making the Template Available to Users

Making the template visible so it can be found and used easily for other projects is essential. By creating and editing a few files, your icon will become part of the Add New Project dialog box.

Creating a .vsdir File

Visual Studio .NET uses a .vsdir file to identify which projects display in the Add New Project dialog box. Each line in a .vsdir file indicates a file that identifies a valid Visual Studio project, including the relative path to that file. These project files typically have the extension .etp, but they can also have other extensions such as .vsz (for wizards) or .csproj (for Visual C# .NET project).

For more information about .vsdir files (and ProxyProjects.vsdir, in particular), see VSDir Files and the applicable sections of Making Custom Enterprise Templates a Default Option for New Project Creation.

To create a .vsdir file

  1. Within ..\EnterpriseFrameworks\ProxyProjects, create a copy of ProxyProjectsCSharp.vsdir called UserProjects.vsdir. The name is not important because Visual Studio searches for all files with the .vsdir file extension, but using a name you can remember is helpful.
  2. Edit the file (using Notepad or any other text editor) to delete all but the first line, which will look similar to the following:
    ..\Projects\CSharp Simple Distributed Application\CSharp Simple Distributed Application.etp|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|#5000|2|#5001|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|121|0|Project
    
  3. Each field is delimited with the vertical bar character. Modify the following fields to match the new values specified in the table.
    Field Name Current Value New Value
    RelPathName
    ..\Projects\CSharp Simple Distributed Application\CSharp Simple Distributed Application.etp
    
    ..\Projects\MyTemplate\MyTemplate.etp
    
    LocalizedName
    #5000
    
    MyTemplate
    
    SortPriority
    2
    
    0
    
    Description
    #5001
    
    An example user-created template
    
    SuggestedBaseName
    Project
    
    MyTemplateProject
    

    The line in the .vsdir file should now look similar to the following:

    ..\Projects\MyTemplate\MyTemplate.etp|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|MyTemplate|0|An example user-created template|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|125|0|MyTemplateProject
    

    This line points the New Project dialog box at the MyTemplate.etp file, labels the icon MyTemplate, gives it the description "An example user-created template", and assigns a default name to any project created from this template. This default name is MyTemplateProjectn (n is a sequential number assigned by Visual Studio). By specifying a 0 in the SortPriority, your icon appears first in the list of available templates. Higher numbers place the icon lower in the list.

  4. Save the changes to the file and close it.

Now test your work to this point. Launch Visual Studio and create a new project. If you encounter errors or simply want to double-check your work thus far, see Enterprise Template Walkthrough File Group 1.

To create a new project using your template

  1. In the New Project dialog box, select MyTemplate under Enterprise Template Projects, name the project MyTemplate, take note of the path name in Location, and click OK.

    You are prompted for a URL location for the WebService project during project creation.

  2. Close the solution and save all changes.

Customizing Your Policy File

If you are an architect of distributed applications that are used within your own firm or by your customers, you have probably lamented the steepness of the learning curve for new developers when they begin writing code and making choices within your development environment. This part of the walkthrough demonstrates how you can give your own development team, and those of your customers, intelligent guidance. By implementing policy in your template, you can significantly reduce the amount of time developers spend trying to choose the most appropriate controls and so on.

What Policy Accomplishes in MyTemplate

In a broad context, you can use policy to reduce the total cost of ownership associated with using MyTemplate to develop distributed applications. One way to do that is to provide guidance that eliminates developers' need to choose between those project types that can be used within your desired architecture and those that should not even be considered. For more conceptual information about policy, see the applicable sections of Advantages of Using Enterprise Templates to Create Distributed Applications.

By determining which project types are suitable for MyTemplate, you can improve productivity without depriving your developers of feeling like they still have control of their project.

Adding ELEMENT Nodes to the Policy File

Before you can use policy to provide guidance for the development team using MyTemplate, you need to prepare your policy file (MyPolicy.tdl). This involves adding ELEMENT nodes to the file that identify the projects in your new template.

Recall that the last change made to each project (each .etp and .csproj file) incorporated the TDLELEMENTTYPE. This differentiates each project as your own specific entity rather than as something generic. For example, UtilityLibrary is an instance of a class library that has been renamed and is a unique part of MyTemplate. Since you already added the necessary identification (TDLELEMENTTYPE) to each project file, you can now edit MyPolicy.tdl file and identify each of the projects as ELEMENT nodes.

To create an ELEMENT that identifies the top-level node

  1. In Visual Studio, click the File menu, then point to Open and click File.

    In the Open File dialog box, navigate to the Policy folder (C:\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy) and open MyPolicy.tdl. Opening the file in Visual Studio's XML Designer provides enhanced functionality and is more efficient than using a general text editor.

  2. Near the beginning of MyPolicy.tdl, find the <POLICYMODE> tag and change the attribute from PERMISSIVE to RESTRICTIVE.
  3. You can remove the unneeded ELEMENT definitions that were specific to the DAP.tdl file. Search for the following element definitions and delete them from the opening <ELEMENT> tag of each through the closing </ELEMENT> tag that matches:
    • etpDistributedApplicationSimple
    • etpDistributedApplicationFull
    • etpBusinessFacade
    • etpBusinessRules
    • etpDataAccess
    • etpSystem
    • etpWebService
    • etpWebUI
    • etpWinUI
    • projBusinessFacade
    • projBusinessRules
    • projDataAccess
    • projSystem
    • projWebService
    • projWebUI
    • projWinUI
  4. Locate a convenient place to insert your edits into MyPolicy.tdl. At the beginning of the file is an example ELEMENT definition. Scroll to the end of the example and add the following lines of TDL to MyPolicy.tdl. You might prefer to type these lines character by character but, to simplify the process, you can copy the lines from this documentation and paste into MyPolicy.tdl. When pasting the lines, use Paste as HTML on the Edit menu.
    Note   You might find it helpful to add a comment at your insertion point to simplify finding it later.
        <ELEMENT>
            <ID>etpMyTemplate</ID>
            <IDENTIFIERS>
                <IDENTIFIER>
                    <TYPE>PROJECT</TYPE>
                    <IDENTIFIERDATA>
                           <NAME>GLOBAL:TDLELEMENTTYPE</NAME>
                        <VALUE>etpMyTemplate</VALUE>
                    </IDENTIFIERDATA>
                </IDENTIFIER>
            </IDENTIFIERS>
            <ELEMENTSET>
                <DEFAULTACTION>INCLUDE</DEFAULTACTION>
                <ORDER>INCLUDEEXCLUDE</ORDER>
            </ELEMENTSET>
            <PROTOTYPES>
                <PROTOTYPE>
                    [EF]\Projects\MyTemplate\MyTemplate.etp
                </PROTOTYPE>
            </PROTOTYPES>
        </ELEMENT>
    
    Note   The bold entries apply specifically to this ELEMENT.

These lines of TDL specify the following:

TDL Node Explanation
ID A unique identifier for this ELEMENT that can be referenced at other points in the policy file.
TYPE Specifies whether this element is a Project, Project Item, Reference, Code, Code Variable, or HTML entity. The specified TYPE determines which Names are allowed as part of the Name/Value pairs within the IDENTIFIERDATA section of the policy file.
IDENTIFIERDATA A name/value pair that refers to the specific project identified as an ELEMENT in the policy file. This is a global identifier for this ELEMENT. To find this ELEMENT, for example, look for projects that contain a global value or UserProperty named TDLELEMENTTYPE with a value of etpMyTemplate.
ELEMENTSET Although more information could be included in this node, DEFAULTACTION and ORDER specify the criteria necessary to restrict users from adding project types as child nodes of MyTemplate. Since DEFAULTACTION specifies INCLUDE and ORDER specifies INCLUDEEXCLUDE, no restrictions are present at this time.
PROTOTYPE Provides the relative location of this ELEMENT in the directory structure.

This provides a pattern for the information you must provide for the remaining projects. This information creates an association between the project files and the policy file. Once this association is established, then you can provide guidance for developers who use this template to create applications. For more information, see ELEMENTS and ELEMENT Nodes in TDL.

To create an ELEMENT node that identifies the remaining Enterprise Template (.etp) projects

  • Repeat the process shown above to identify each of the remaining .etp projects (BackendProjects, UIProjects, and UtilityProjects) as ELEMENT nodes in MyPolicy.tdl. Use the same sort of identification for these .etp projects as you did for etpMyTemplate (project globals) and point at the appropriate prototype.
        <ELEMENT>
            <ID>etpBackendProjects</ID>
            <IDENTIFIERS>
                <IDENTIFIER>
                    <TYPE>PROJECT</TYPE>
                    <IDENTIFIERDATA>
                           <NAME>GLOBAL:TDLELEMENTTYPE</NAME>
                        <VALUE>etpBackendProjects</VALUE>
                    </IDENTIFIERDATA>
                </IDENTIFIER>
            </IDENTIFIERS>
            <ELEMENTSET>
                <DEFAULTACTION>INCLUDE</DEFAULTACTION>
                <ORDER>INCLUDEEXCLUDE</ORDER>
            </ELEMENTSET>
            <PROTOTYPES>
                <PROTOTYPE>
                    [EF]\Projects\MyTemplate\BackendProjects\BackendProjects.etp
                </PROTOTYPE>
            </PROTOTYPES>
        </ELEMENT>
    
        <ELEMENT>
            <ID>etpUIProjects</ID>
            <IDENTIFIERS>
                <IDENTIFIER>
                    <TYPE>PROJECT</TYPE>
                    <IDENTIFIERDATA>
                           <NAME>GLOBAL:TDLELEMENTTYPE</NAME>
                        <VALUE>etpUIProjects</VALUE>
                    </IDENTIFIERDATA>
                </IDENTIFIER>
            </IDENTIFIERS>
            <ELEMENTSET>
                <DEFAULTACTION>INCLUDE</DEFAULTACTION>
                <ORDER>INCLUDEEXCLUDE</ORDER>
            </ELEMENTSET>
            <PROTOTYPES>
                <PROTOTYPE>
                    [EF]\Projects\MyTemplate\UIProjects\UIProjects.etp
                </PROTOTYPE>
            </PROTOTYPES>
        </ELEMENT>
    
        <ELEMENT>
            <ID>etpUtilityProjects</ID>
            <IDENTIFIERS>
                <IDENTIFIER>
                    <TYPE>PROJECT</TYPE>
                    <IDENTIFIERDATA>
                           <NAME>GLOBAL:TDLELEMENTTYPE</NAME>
                        <VALUE>etpUtilityProjects</VALUE>
                    </IDENTIFIERDATA>
                </IDENTIFIER>
            </IDENTIFIERS>
            <ELEMENTSET>
                <DEFAULTACTION>INCLUDE</DEFAULTACTION>
                <ORDER>INCLUDEEXCLUDE</ORDER>
            </ELEMENTSET>
            <PROTOTYPES>
                <PROTOTYPE>
                    [EF]\Projects\MyTemplate\UtilityProjects\UtilityProjects.etp
                </PROTOTYPE>
            </PROTOTYPES>
        </ELEMENT>
    

Creating ELEMENT nodes that identify each Visual C# project (.csproj)

Next, provide ELEMENT definitions for the three language projects: WebService, WinApp, and UtilityLibrary.

Note   Since element names must be unique in a policy file, delete the existing ELEMENT definition for "projWebService" from MyPolicy.tdl (you will create your own projWebService element definition).

To reduce the possibility of errors, you can copy the lines from this documentation and paste them into MyPolicy.tdl, but you can also copy and modify an existing ELEMENT definition, such as projBusinessFacade.

Note   When pasting these lines, use Paste as HTML on the Edit menu.

The ELEMENT definitions for the three language projects should look as follows.

    <ELEMENT>
        <ID>projWebService</ID>
        <IDENTIFIERS>
           <IDENTIFIER>
                <TYPE>PROJECT</TYPE>
                <IDENTIFIERDATA>
                       <NAME>GLOBAL:TDLELEMENTTYPE</NAME>
                    <VALUE>WebService</VALUE>
                </IDENTIFIERDATA>
           </IDENTIFIER>
        </IDENTIFIERS>
        <PROTOTYPES>
            <PROTOTYPE>
                [EF]\Projects\MyTemplate\BackendProjects\WebService\WebService.csproj
            </PROTOTYPE>
        </PROTOTYPES>
        <ELEMENTSET>
            <DEFAULTACTION>INCLUDE</DEFAULTACTION>
            <ORDER>INCLUDEEXCLUDE</ORDER>
        </ELEMENTSET>
    </ELEMENT>

    <ELEMENT>
        <ID>projWinApp</ID>
        <IDENTIFIERS>
           <IDENTIFIER>
                <TYPE>PROJECT</TYPE>
                <IDENTIFIERDATA>
                       <NAME>GLOBAL:TDLELEMENTTYPE</NAME>
                    <VALUE>WinApp</VALUE>
                </IDENTIFIERDATA>
           </IDENTIFIER>
        </IDENTIFIERS>
        <PROTOTYPES>
            <PROTOTYPE>
                [EF]\Projects\MyTemplate\UIProjects\WinApp\WinApp.csproj
            </PROTOTYPE>
        </PROTOTYPES>
        <ELEMENTSET>
            <DEFAULTACTION>INCLUDE</DEFAULTACTION>
            <ORDER>INCLUDEEXCLUDE</ORDER>
        </ELEMENTSET>
    </ELEMENT>

    <ELEMENT>
        <ID>projUtilityLibrary</ID>
        <IDENTIFIERS>
           <IDENTIFIER>
                <TYPE>PROJECT</TYPE>
                <IDENTIFIERDATA>
                       <NAME>GLOBAL:TDLELEMENTTYPE</NAME>
                    <VALUE>UtilityLibrary</VALUE>
                </IDENTIFIERDATA>
           </IDENTIFIER>
        </IDENTIFIERS>
        <PROTOTYPES>
            <PROTOTYPE>
                [EF]\Projects\MyTemplate\UtilityProjects\UtilityLibrary\UtilityLibrary.csproj
            </PROTOTYPE>
        </PROTOTYPES>
        <ELEMENTSET>
            <DEFAULTACTION>INCLUDE</DEFAULTACTION>
            <ORDER>INCLUDEEXCLUDE</ORDER>
        </ELEMENTSET>
    </ELEMENT>

Note that you are still using the same type of identification (project global) and are pointing at the language-project prototype in each case.

Before proceeding, save and close MyPolicy.tdl.

Verifying the Changes to MyPolicy.tdl

You can now verify that your changes to MyPolicy.tdl are showing up in the Visual Studio integrated development environment (IDE). Keep in mind that you have not set any policy yet; rather, you identified your projects as ELEMENT nodes. After verifying these identifications, you can make adjustments in MyPolicy.tdl that provide practical guidance to the development team using MyTemplate.

To examine the results of changes made to the policy file

  1. Go to the File menu, select New, and then click Project. The New Project dialog box displays.
  2. In the Project Types pane, expand Other Projects, and then click Enterprise Template Projects.
  3. In the Templates pane, select MyTemplate, accept the default project name, and click OK. If you made typing errors in the policy file, you might see error messages in the Task List while reloading. Read the error message carefully, then open the policy file and make the necessary edits. When all loading errors are resolved, you can examine the results of the changes.
  4. Select the top-level project in Solution Explorer and look in the Properties window.

    The Elements property has a value that matches the ID you gave the ELEMENT in MyPolicy.tdl above. Expand the Elements and Instances nodes. Note that the current selection matches the identification for the ELEMENT etpMyTemplate and that the identification used is GLOBAL:TDLELEMENTTYPE. In the Instances section, the selected item is a Project named MyTemplateProjectn.etp, where n is the sequential number assigned to the latest MyTemplateProject.etp by Visual Studio.

  5. Select each of the other nodes in the Solution Explorer. Notice the following in the Elements field:
    Solution Explorer selection Elements value
    MyTemplateProjectn etpMyTemplate
    BackendProjects etpBackendProjects
    WebService projWebService, projCSharpProject
    UIProjects etpUIProjects
    WinApp projWinApp, projCSharpProject
    UtilityProjects etpUtilityProjects
    UtilityLibrary projUtilityLibrary, projCSharpProject
  6. If you select nodes within the language projects (project items), you see the other definitions in MyPolicy.tdl (that you copied and renamed from the DAP.tdl file) identify each file type and associate them with the appropriate ELEMENT as follows.
    Solution Explorer selection Elements value
    WebService\AssemblyInfo.cs projItemCSharpFile
    WebService\Global.asax ProjItemGlobalApplicationClass
    WebService\Service1.asmx projItemWebService
    WebService\Web.Config projItemWebConfigFile
    WinApp\AssemblyInfo.cs projItemCSharpFile
    WinApp\Form1.cs projItemCsharpFile, codeWinForm, codeComponent
    UtilityLibrary\AssemblyInfo.cs projItemCSharpFile
    UtilityLibrary\Class1.cs projItemCSharpFile
    Note   Form1.cs maps to multiple ELEMENT nodes. It is a Visual C# file and it contains a Windows Form. Since the WindowsForm class is derived from the Custom Control class, it is identified as a custom control as well.

You can now place some restrictions as to what can be added at various locations within your template. You accomplish this by adding information to the ELEMENTSET definitions within MyPolicy.tdl.

If you want to double-check your work thus far, see Enterprise Template Walkthrough File Group 2.

Applying Policy Using ELEMENTSET Nodes

Planning becomes critical at this point to ensure you provide the development teams with a template that is optimized in the most helpful way without presenting limitations that the developers view as impediments to performing their tasks. Constructing a table similar to the following can be useful in determining what kinds of rules your policy establishes.

Policy planning table

ELEMENT Rules
etpMyTemplate Allow only the Enterprise Template projects you previously defined as children (BackendProjects, UIProjects, and UtilityProjects).
etpBackendProjects Allow the WebService project, plus C# Class Library and C# Empty Project projects. You don't want users to add the standard C# ASP.NET Web Service, since yours will eventually have more initial code.
etpUIProjects Allow the WinApp project, plus C# Windows Application and C# Empty Project projects.
etpUtilityProjects Allow the UtilityLibrary project, plus C# Class Library and Empty Project projects.
projWebService You do not want the BackendProjects WebService project to contain any Web UI items, so restrict these items from the project. Use predefined CATEGORY nodes (originally copied from DAP.tdl) to keep the TDL in MyPolicy.tdl brief and more readable.
projWinApp Allow Windows UI controls, common items, Windows UI code items, and Toolbox components. Again, use the predefined CATEGORY nodes from the original DAP.tdl to keep the TDL in MyPolicy.tdl brief and more readable.
projUtilityLibrary Allow the same items that can be used in the WebService project, as well as Toolbox data items.

The Template Description Language uses ELEMENTSET as one of its primary mechanisms to allow projects and project items to become available for (or restricted from) use. The architect can pick and choose to eliminate unnecessary choices. As shown in the preceding table, you now have a very clear idea of the project types to allow in the architecture of this particular template, so you can exclude all project types by default. You can then include, by name, the ones you specifically want available to users of your template. For more information about ELEMENTSET nodes, see ELEMENTSET Nodes in TDL.

Updating the ELEMENTSET Node for etpMyTemplate

To update the ELEMENTSET definition for the ELEMENT etpMyTemplate, edit the ELEMENTSET to initially exclude all project types by setting DEFAULTACTION to EXCLUDE. By setting ORDER to INCLUDEEXCLUDE, the project types enclosed in INCLUDE tags within the ELEMENTSET are evaluated and approved. Finally, to specify which projects are allowed as children, each is identified within an INCLUDE node.

To update the ELEMENTSET node for etpMyTemplate

  1. In MyPolicy.tdl, locate the ELEMENTSET node for the etpMyTemplate ELEMENT.
  2. Modify the ELEMENTSET definition to set DEFAULTACTION to EXCLUDE and to allow the three .etp projects specified in the planning table as children of etpMyTemplate. Your changes to the ELEMENTSET node should match the following.
            <ELEMENTSET>
                <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
                <ORDER>INCLUDEEXCLUDE</ORDER>
                <INCLUDE>etpBackendProjects</INCLUDE>
                <INCLUDE>etpUIProjects</INCLUDE>
                <INCLUDE>etpUtilityProjects</INCLUDE>
            </ELEMENTSET>
    

Updating the ELEMENTSET Nodes of the ELEMENT Nodes Nested Under etpMyTemplate

By editing the ELEMENTSET node belonging to etpMyTemplate, your policy file now conforms to the first line of the policy planning table shown above. You can now update the ELEMENTSET nodes of the three ELEMENT nodes you included as children of etpMyTemplate:

  • etpBackendProjects
  • etpUIProjects
  • etpUtilityProjects

Update the ELEMENTSET nodes to exclude all project types by default and to allow only the project types specified in the corresponding rows of the planning table as children of these three ELEMENT nodes. The following procedure provides lines of TDL that make these updates by setting DEFAULTACTION to EXCLUDE and adding the appropriate INCLUDE nodes.

To update the ELEMENTSET nodes of the three remaining .etp projects

  1. Replace the existing etpBackendProjects ELEMENTSET with the following:
                <ELEMENTSET>
                    <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
                    <ORDER>INCLUDEEXCLUDE</ORDER>
                    <INCLUDE>projWebService</INCLUDE>
                    <INCLUDE>projCSharpProject</INCLUDE>
                    <INCLUDE>projCSharpEmptyProject</INCLUDE>
                </ELEMENTSET>
    

    The rationale for this ELEMENTSET is precisely the same as in the one belonging to the top-level node (etpMyTemplate). Using EXCLUDE as the default greatly simplifies the restrictions you want to impose.

  2. Replace the existing etpUIProjects ELEMENTSET with the following:
                <ELEMENTSET>
                    <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
                    <ORDER>INCLUDEEXCLUDE</ORDER>
                    <INCLUDE>projWinApp</INCLUDE>
                    <INCLUDE>projCSharpWinApp</INCLUDE>
                    <INCLUDE>projCSharpProject</INCLUDE>
                    <INCLUDE>projCSharpEmptyProject</INCLUDE>
                </ELEMENTSET>
    
  3. Replace the existing etpUtilityProjects ELEMENTSET with the following:
                <ELEMENTSET>
                    <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
                    <ORDER>INCLUDEEXCLUDE</ORDER>
                    <INCLUDE>projUtilityLibrary</INCLUDE>
                    <INCLUDE>projCSharpClassLibrary</INCLUDE>
                    <INCLUDE>projCSharpProject</INCLUDE>
                    <INCLUDE>projCSharpEmptyProject</INCLUDE>
                </ELEMENTSET>
    

Updating the Remaining ELEMENTSET nodes

The remaining ELEMENT nodes are all language projects. Whereas the structure of the template is provided by the Enterprise Template projects (.etp files), the real work is done in the language projects. The ELEMENTSET definitions for these projects look quite different. A variety of controls, tools, and so on must be available to development team members as they create applications from the template.

You could list every single item you want available to the development team by placing the correct name of each inside INCLUDE tags in the ELEMENTSET but that would be extremely time consuming because so many project items exist. Instead, use a feature of the DAP.tdl file which you copied when creating MyPolicy.tdl. MyPolicy.tdl already contains a variety of CATEGORY nodes composed of logical groupings you can refer to for almost all the functionality needed. You can find the CATEGORY definitions by searching the file for the category names shown in the INCLUDE nodes in the procedure below.

Update the ELEMENTSET nodes to exclude all project items by default and to include the desired categories. The following procedure provide lines of TDL that make these updates by setting DEFAULTACTION to EXCLUDE and adding the appropriate INCLUDE nodes.

To update the ELEMENTSET Nodes of the Language Projects

  1. Replace the projWebService ELEMENTSET with the following:
                <ELEMENTSET>
                    <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
                    <ORDER>INCLUDEEXCLUDE</ORDER>
                    <INCLUDE>catVBCommonProjectItems</INCLUDE>
                    <INCLUDE>catCommonProjectItems</INCLUDE>
                    <INCLUDE>catCSCommonProjectItems</INCLUDE>
                    <INCLUDE>catComponentCodeItems</INCLUDE>
                    <INCLUDE>catWebConfigurationProjectItems</INCLUDE>
                    <INCLUDE>projItemWebService</INCLUDE>
                    <INCLUDE>projItemGlobalApplicationClass</INCLUDE>
                    <INCLUDE>codeWebService</INCLUDE>
                    <INCLUDE>refSystem.Web</INCLUDE>
                    <INCLUDE>refSystem.Web.Services</INCLUDE>
                </ELEMENTSET>
    
    Note   To avoid policy reminders in the Visual Studio Task List, the INCLUDE nodes specify the standard parts of the ASP.NET Web Service project (Web.config and Global Application class items).
  2. Replace the projWinApp ELEMENTSET with the following:
                <ELEMENTSET>
                    <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
                    <ORDER>INCLUDEEXCLUDE</ORDER>
                    <INCLUDE>catVBCommonProjectItems</INCLUDE>
                    <INCLUDE>catWinUIProjectItems</INCLUDE>
                    <INCLUDE>catCommonProjectItems</INCLUDE>
                    <INCLUDE>catCSCommonProjectItems</INCLUDE>
                    <INCLUDE>catWinCodeItems</INCLUDE>
                    <INCLUDE>catDataCodeItems</INCLUDE>
                    <INCLUDE>catComponentCodeItems</INCLUDE>
                    <INCLUDE>refSystem.Windows.Forms</INCLUDE>
                </ELEMENTSET>
    
  3. Replace the projUtilityLibrary ELEMENTSET with the following:
                <ELEMENTSET>
                    <DEFAULTACTION>EXCLUDE</DEFAULTACTION>
                    <ORDER>INCLUDEEXCLUDE</ORDER>
                    <INCLUDE>catVBCommonProjectItems</INCLUDE>
                    <INCLUDE>catCommonProjectItems</INCLUDE>
                    <INCLUDE>catCSCommonProjectItems</INCLUDE>
                    <INCLUDE>catComponentCodeItems</INCLUDE>
                    <INCLUDE>catWebConfigurationProjectItems</INCLUDE>
                    <INCLUDE>projItemWebService</INCLUDE>
                    <INCLUDE>projItemGlobalApplicationClass</INCLUDE>
                    <INCLUDE>codeWebService</INCLUDE>
                </ELEMENTSET>
    

Save these changes to MyPolicy.tdl, then close the current project and reopen the MyTemplate project. This allows you to easily check for any typing errors that might have occurred. Check the Task List for errors and make any corrections necessary.

If you encounter errors or simply want to double-check your work, see Enterprise Template Walkthrough File Group 3.

Checking the Effects of the Policy

You can see how the policy you just applied to the new template affects the Add New Project dialog box. Compare the contents of this dialog box for a node that does not have policy applied with a node that does have policy applied.

To view the effects of the policy

  1. In Solution Explorer, right-click the Solution node, point to Add, and click New Project. You can see the full set of projects available in the Add New Project dialog box. Click cancel to close the dialog box.
  2. Repeat the process, selecting each of the project nodes in Solution Explorer and examining the available projects in the Add New Project dialog box. Notice that the set of projects is now restricted. Later, when you define a building block for the WebService, you will see the WebService project available.

Even though you stated, through policy, that you allow the new template and language projects to be part of any application developers write when using MyTemplate, the Visual Studio IDE remains unaware that those items exist. Although you can see the graphic representation of them in Solution Explorer, for these building blocks to be added to an existing application, you need to make some changes and additions to your .vsdir files.

See Also

Walkthrough: Creating a Template Using Subproject Wizards | Walkthrough: Adding Building Blocks to the Template | Custom Template Walkthroughs | Policy Walkthroughs with TDL Files

Show:
© 2015 Microsoft