Teaching by Example

Some concepts are easy to understand simply by listening to a lecture or reading a book. Others require examples in order to fully comprehend them. Enterprise templates are a perfect example of the latter. Because much of an enterprise template is shell code, it is sometimes hard to explain. In the following sections, you will learn how to create a new enterprise template. The entire process can be broken up into several distinct parts.

Setting Up the Prerequisites

The first step in developing anything is to set up your environment. The same holds true with the development of an enterprise template. Before you start this example, make sure that you set up your system to display hidden files, folders, and file extensions in the Windows Explorer. Also, because this template will include a web service, ensure that IIS has been installed on your machine.

Laying Out the Template

The template that you will be developing is a standard n-tier application. As shown in Figure 41.1, it consists of a user interface layer (UIL), a business logic layer (BLL), and a data access layer (DAL).

Figure 41.1. The enterprise template architecture is divided into three distinct layers.

In this template, the user interface layer will be a Windows Forms application. This layer enables you to display all the necessary information to the user. In addition, it makes it possible for you to collect information from the user. The next layer is the business logic layer. This layer is a set of web services that contain the logic necessary to perform the necessary operations of the system. The final layer is the data access layer. This layer contains the functionality needed to store and retrieve the database entities used in the application. Although these layers would normally contain the functionality needed to perform the functions of the system, this is only a template and therefore contains only a thin shell of functionality.

Naming the Parts of the Template

When laying out the template, it is useful to write down the names of each section. Later in the project, it will be necessary to refer to the correct names of each part of the template. If you choose not to write down the names, you run the risk of generating errors by using inconsistent names. For the purposes of this demonstration, the name of this template will be nTierTemplate.etp. The three layers will use the name of the layer followed by .etp. For example, the data access layer will be dal.etp, the user interface layer will be uil.etp, and the business logic layer will be bll.etp.

Creating the Template Structure

The first thing to do in creating the template structure is to create the enterprise template. The following steps will create an empty enterprise template:

1.	Start Visual Studio .NET.
2.	Display the New Project dialog box by selecting File, New, Project menu item.
3.	As shown in Figure 41.2, select the Enterprise Template Project by expanding the Other Projects folder in the Project Types pane. Figure 41.2. Create a new enterprise template project from the New Project dialog. [View full size image]
4.	Type the name nTierTemplate in the Name section of the dialog.
5.	Write down the location (path) of the template because you will need this information later in the section.

With this done, you will need to create the subproject templates. To do this, follow these steps:

1.	Select the `nTierTemplate` node in the Solution Explorer.
2.	As you did earlier, invoke the New Project dialog and select the Enterprise Template Project.
3.	Change the name to DAL and create the project.
4.	Repeat steps 1 through 3 two more times, changing DAL to BLL and UIL, respectively, to create the data access layer and user interface layer subprojects.

Figure 41.3 shows the completed template structure to this point.

Figure 41.3. The empty structure of the `nTierTemplate` enterprise template.

[View full size image]

Adding the Language Projects

Up to this point, the work you have done is similar to creating four separate solutions. The only difference is that these solutions are contained within a solution and are known as an enterprise template (although similar to a solution, enterprise template projects have additional features). The next step is to actually add some substance to the template by adding what are known as language projects to the template.

The following steps will create the DAL project:

1.	Select the `DAL` node in the Solution Explorer.
2.	Invoke the New Project dialog and select the Class Library project under the Visual C# Projects folder in the Project Types pane, as shown in Figure 41.4. Figure 41.4. Create the DAL project. [View full size image]
3.	Change the name of the project to DALProject and click OK.

After you've created the DAL project, you can create the UIL project template, as shown in the following steps:

1.	Select the `UIL` node in the Solution Explorer.
2.	Invoke the New Project dialog and select the Windows Application project under the Visual C# Projects folder in the Project Types pane, as in Figure 41.5. Figure 41.5. Create the UIL project. [View full size image]
3.	Change the name of the project to UILProject and click OK.

Finally, you will want to create the BLL project. To do so, follow these steps:

1.	Select the `BLL` node in the solution explorer.
2.	Invoke the New Project dialog and select the ASP.NET Web Service project under the Visual C# Projects folder in the Project Types pane, as shown in Figure 41.6. Figure 41.6. Create the BLL project. [View full size image]
3.	Change the location of the project to http://localhost/BLLWebService and click OK.

The creation of the template structure is now complete and should resemble Figure 41.7. This structure will serve as the basis for all projects created with this template. As such, you can specify any additional settings that you want to be included with all of those projects. The settings could include compiler settings, such as warning levels, and other project defaults. You can also choose to add controls or other projects to these templates.

Figure 41.7. The completed `nTierTemplate` structure.

Assigning a Policy to the Template

Before you can use this structure as a template, you must assign a policy. Although you could create a policy from scratch, doing so is beyond the scope of this section. For the purposes of this demonstration, you will create a policy by cloning the default DAP.tdl file and modifying it as necessary.

Follow these steps to configure the policy:

1.	Copy the `DAP.tdl` file and rename the copy to `nTierTemplate.tdl`.
2.	Select the `nTierTemplate` node in the Solution Explorer.
3.	In the Properties window, enter the location and name of the policy file in the Policy File section, as shown in Figure 41.8. Figure 41.8. Assign a policy to the `nTierTemplate` enterprise template.
4.	Click Yes when prompted to reopen the project.

Making the Template

The previous sections created the basic structure from which to create the enterprise template. Unfortunately, those sections were the last of the automated processes (wizard based). This section will show you the manual steps that you must perform to finish the template and have it recognized by Visual Studio .NET.

Locate, Organize, and Clean Up

The following steps walk you through finalizing the process of creating and using an enterprise template. Before starting the following steps, save the projects, close the solution, and exit Visual Studio .NET.

1.	Locate the `EnterpriseFrameworks` directory. By default, it should be located in a subdirectory of the `Microsoft Visual Studio .NET 2003` directory.
2.	Copy the entire structure of the `nTierTemplate` project from its current location (you were instructed to write down this directory in a step earlier in this chapter) to the `EnterpriseFrameworks\Projects` directory.
3.	Copy the web `BLLWebService` project (located in the web root directory) from its current location to the `EnterpriseFrameworks\Projects\nTierTemplate\BLL` directory.

Throwing Out the Trash

Applications such as those created by Visual Studio .NET require a few ancillary files and directories such as the solution file (.sln), .suo files, .eto files, and bin and obj directories. Although they serve a purpose in a regular application, they are not needed in an enterprise template and can therefore be deleted.

Modifying the Enterprise Template Project Files

This next section will show you how to make some minor modifications to all the associated enterprise template files (.etp).

1.	Remove the Project ID.
2.	Modify the Web project to prompt for a URL.

To remove the Project ID from the Enterprise Template Files, start by deleting the line

<GUIDPROJECTID>A GUID Will Be Here</GUIDPROJECTID>

from the following files: nTierTemplate.etp, BLL\bll.etp, DAL\dal.etp, and UIL\uil.etp.

The next thing you'll do in this sample is to modify the Web Project template to prompt for a URL. Listing 41.2 shows the contents of the business logic layer enterprise template project file. In order for the web project to prompt for the URL, this file must be modified. The modified contents are shown in Listing 41.3.

Listing 41.2. The `bll.etp` File Before Modifications

<?xml version="1.0"?>
<EFPROJECT>
    <GENERAL>
        <BANNER>Microsoft Visual Studio Application Template File</BANNER>
        <VERSION>1.00</VERSION>
        <Views>
            <ProjectExplorer>
                <File>http://localhost/BLLWebService/BLLWebService.csproj</File>
            </ProjectExplorer>
        </Views>
        <References>
            <Reference>
                <FILE>http://localhost/BLLWebService/BLLWebService.csproj</FILE>
            </Reference>
        </References>
    </GENERAL>
</EFPROJECT>

Listing 41.3. The `bll.etp` File After Modifications

<EFPROJECT>
    <GENERAL>
        <BANNER>Microsoft Visual Studio Application Template File</BANNER>
        <VERSION>1.00</VERSION>
        <Views>
            <ProjectExplorer>
                <File>BLLWebService\BLLWebService.csproj</File>
            </ProjectExplorer>
        </Views>
        <References>
            <Reference>
                <FILE>BLLWebService\BLLWebService.csproj</FILE>
                <REQUIRESURL>1</REQUIRESURL>  
            </Reference>
        </References>
    </GENERAL>
</EFPROJECT>

The next step is to add global entries to the Enterprise Template Project (.etp) and user properties to the language projects (.csproj) to allow the policy file (.tdl) to identify your project files as elements.

Add the following entry to the <GLOBALS> section in all four enterprise template projects:

<GLOBALENTRY>
  <NAME>TDLELEMENTTYPE</NAME>
  <VALUE>Insert Name Here</VALUE>
</GLOBALENTRY>

Make sure to replace Insert Name Here with the name of the template project. For example, after modifying the nTierTemplate.etp file, it should look like the following:

<GLOBALENTRY>
  <NAME>TDLELEMENTTYPE</NAME>
  <VALUE>nTierTemplate</VALUE>
</GLOBALENTRY>

Add the following entry after the <Files> section in all three of the language projects:

<UserProperties
  TDLFILE = "nTierTemplate.tdl"
  TDLELEMENTTYPE = "Insert Name Here"
/>

Make sure to replace the Insert Name Here to the name of the language project. For example, after modifying the DALLibrary.csproj, it should look like the following:

<UserProperties
  TDLFILE = "nTierTemplate.tdl"
  TDLELEMENTTYPE = "DALLibrary"
/>

Making the Template Available to Users

Now that you have a completed template and are ready to use it, how do you make sure that it is easily accessible to all users of the system? After all, if you spend all the time and effort necessary to plan and create a usable enterprise template, the last thing you want to hear is that "I didn't use it because I couldn't find it."

Creating a `.vsdir` File

To identify the appropriate files to display in the Add New Project dialog, Visual Studio .NET uses a .vsdir file. In this file, each line represents a different project or template. Within each line is a set of fields delimited by pipes (|), as described in Table 41.3.

Table 41.3. .vsdir File Fields
Field Name
Purpose
RelPathName
The path relative to the location of the .vsdir file to the template file.
{clsidpackage}
Optional GUID representing a product (Visual C#, and so on) that has a DLL containing localized resources.
LocalizedName
The name of the template. This name appears in the Add Item dialog box. This field is optional and can contain either a name or resource ID.
SortPriority
An integer representing the sort order and relative priority of the template in the dialog box.
Description
A description of the template. This description appears in the Add Item dialog box when the item is selected. This field can contain either a name or resource ID.
DLLPath or {clsidPackage}
Used to load an icon for the template from a DLL or EXE file. Either specifies a full path to the DLL or EXE, or a GUID of a product that has a DLL containing localized resources.
IconResourceId
Resource ID within the specified DLL. This field is optional and determines the icon to display. If no icon is defined, the shell substitutes the default icon for a file with the same extension as the item.
Flags
A group of flags that disable or enable the Name and Location fields on the Add Item dialog box. The flags can have the following values:Space (" "): enable filename 8192: disable filename
SuggestedBaseName
The default name for the template. This name will be displayed in the Name field in the dialog box.

To correctly expose your new template to users, you will need to create a .vsdir file that contains the appropriate information for your file and store it in the EnterpriseFrameworks\ProxyProjects directory. For the purposes of this discussion, create a new text file in Notepad, and copy and paste the following line into this file (space restrictions do not allow the code to be printed on a single line, but you should paste it into Notepad as one line):

..\Projects\nTierTemplate\nTierTemplate.etp|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|
Visual C# n-Tier Project|1|This is the sample enterprise template created in chapter 41 
of the Visual C#.NET Unleashed Book.|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|
125|0|nTierProject

To complete the exposure of the template, save this file into the EnterpriseFrameworks\ProxyProjects directory.

Testing the Template

The final step in this example is to test the newly created template.

1.	Start Visual Studio .NET.
2.	Invoke the New Project dialog and select the newly created Visual C# n-Tier Project project, as shown in Figure 41.9. Figure 41.9. Select the template displayed in the New Project dialog. [View full size image]
3.	Either leave the default or change the name and click OK.
4.	Enter the path to store the Web Service BLL project, as in Figure 41.10. Figure 41.10. Enter the path to create the BLL Web Service Project.

As shown in Figure 41.11, when these steps have been completed, you should have an instance of the application that your template was designed to create.