|
Visual
Studio Enterprise Templates
Walkthrough:
Creating a New Enterprise TemplateSee Also
Walkthrough: Creating a Template Using Subproject Wizards | Walkthrough:
Adding Building Blocks to the Template | Creating a Custom Template
Walkthroughs | Policy Walkthroughs with TDL Files
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.
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
From
Windows 2000, click Start, then click Settings, and then click Control
Panel.
In Control Panel, find the Add/Remove Programs icon and double-click
it to display the Add/Remove Programs dialog box.
On the left side of the dialog box, click Add/Remove Windows Components.
In the Add/Remove Windows Components dialog box, find Internet Information
Services. If the box is selected, IIS is already installed. If it
is not selected, select it.
Click Next to bring up the Windows Components Wizard and start the
installation process.
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
Go
to the Windows Explorer Tools menu and click Folder Options, then
click View.
Find Hidden files and folders, and select Show hidden files and
folders.
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
Launch
Visual Studio.
On the File menu, point to New, then click Project.
The New Project dialog box displays.
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.
Replace the default project name with MyTemplate.
Take note of the pathname in Location. In a later step, you will
move 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
Select
MyTemplate in Solution Explorer.
On the File menu, point to Add Project, then click New Project.
The Add New Project dialog box appears.
Select Enterprise Template Projects, and then select Enterprise
Template Project in the Templates pane.
Change the project name to BackendProjects, and then click OK.
The BackendProjects project appears in Solution Explorer.
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
In
Solution Explorer select BackendProjects.
On the File menu, point to Add Project, then click New Project.
The Add New Project dialog box appears.
Select Visual C# Projects in the Project Types pane.
In the Templates pane, select ASP.NET Web Service.
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
In
Solution Explorer select UIProjects.
On the File menu, point to Add Project, and then click New Project.
The Add New Project dialog box appears.
Select Visual C# Projects in the Project Types pane.
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
In
Solution Explorer select UtilityProjects
On the File menu, point to Add Project, and then click New Project.
The Add New Project dialog box appears.
Select Visual C# Projects in the Project Types pane.
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
If
the Properties window is not already visible, select the MyTemplate
node in Solution Explorer (not Solution 'MyTemplate'), right-click,
and select Properties.
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.
Click the ellipsis button to open the Select a TDL File dialog box.
In the dialog box, select the DAP.tdl file and press Ctrl+C to copy
it.
Press Ctrl-V to paste a copy of the file so it appears with the
other .tdl files.
Right-click on the copy you just made and rename it MyPolicy.tdl.
Select MyPolicy.tdl and click Open to associate MyPolicy.tdl with
the current application.
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 move 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\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
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
Copy the entire MyTemplate folder into the following folder:
C:\Program Files\Microsoft Visual Studio .NET\EnterpriseFrameworks\Projects
This copies all the files associated with MyTemplate except the
WebService project, which has been created in a separate location.
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
Copy the WebService folder into the BackendProjects folder at the
following location:
C:\Program Files\Microsoft Visual Studio .NET\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
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.
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
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.
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}|#5007|5|#5008|{AE77B8D0-6BDC-11d2-B354-0000F81F0C06}|125|0|Project
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 #5007
MyTemplate
SortPriority 5
0
Description #5008
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.
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
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.
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
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\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.
Near
the beginning of MyPolicy.tdl, find the <POLICYMODE> tag and
change the attribute from PERMISSIVE to RESTRICTIVE.
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
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 An identifier for this ELEMENT that can be referenced at other
points in the policy file.
TYPE Contains a unique value that can be used as a reference key
to allow the IDENTIFIER to be defined one time and then referred
to by this value from elsewhere.
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
Go
to the File menu, select New, and then click Project. The New Project
dialog box displays.
In the Project Types pane, expand Other Projects, and then click
Enterprise Template Projects.
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.
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.
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
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
WebService\WebService.vsdisco projItemDynamicDiscoFile
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
In
MyPolicy.tdl, locate the ELEMENTSET node for the etpMyTemplate ELEMENT.
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
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.
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>
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
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, .vsdisco file, and Global Application class
items).
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>
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
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.
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 | Creating a Custom Template
Walkthroughs | Policy Walkthroughs with TDL Files
--------------------------------------------------------------------------------
Send
feedback to Microsoft
©
2001 Microsoft Corporation. All rights reserved.
|
