This article will explain each grammar element comprising the Enterprise Template Definition Language (TDL). You will learn about the TDL Grammar Hierarchy and where each grammar element fits in that hierarchy. Finally, you will study each TDL Grammar Element and be shown an example of its use.
This series is designed around two central premises: first, this series teaches foundational concepts of Enterprise Templates. Second, this series demonstrates how to create Enterprise Templates using various types of available Visual Studio .NET Projects. This article series will benefit two types of audiences the best: individuals curious about Enterprise Templates (with little knowledge or experience developing Enterprise Templates), and individuals familiar with the fundamental concepts of Enterprise Templates (but seeking a more application-oriented, tools-development approach to constructing Enterprise Templates).
Many of you have written and thanked me for explaining .NET Technology in easy-to-understand terms. Many of you have also asked if there will be books or more articles in the works. The answer is "YES" to both questions. I am currently trying to drum up support for a book on "Microsoft .NET CodeDom Technology." I am presently refining the outline for this book. You can visit my Web site at http://www.brandari.net. One of the initiatives underway is a full explanation of every .NET class, property, method, event, enumeration, interface, and construct in the .NET Framework - explained in easy to understand terms. The Web site is continually being added to and refined, so feel free to stop by and check it out. Thank you for your support and all the great feedback.
The .NET Architect Enterprise Template Series will help you build the following projects:
Enterprise Template Editor Add-In
Enterprise Template Editor Web Service
Enterprise Template Editor Windows Service
Enterprise Template Editor Web Control
Enterprise Template Editor Windows Control
Enterprise Template Editor Framework
Requirements
Visual Studio.NET Enterprise Developer, or Enterprise Architect Edition
Section 1: Introduction Section 2: TDL Grammar Elements Section 3: TDL Grammar Element Explanations Summary About The Author
Section 1: Introduction
To fully master any technology, you must first recognize the need to understand its fundamental concepts, terminology, and its dependencies on other technologies. This article will explain each Template Definition Language (TDL) tag. You will learn the basic, fundamental concept behind each tag, learn when to use it, and learn how to use it through practical code examples. It is imperative that you understand the basics of Enterprise Template Technology, including the Enterprise Template Definition Language (TDL) before you attempt to create your own template projects. If you have been reading this series and felt a little bewildered, take heart. In the next few articles, you will begin to actually create your own Enterprise Templates Projects, configure your own Policy Files, and see your templates in action.
Enterprise Template TDL Grammar elements are called nodes, which are created using an XML syntax. TDL Grammar Elements are written in UPPERCASE. Nesting of TDL Elements is enforced by consulting the TDLSchema.xsd file. Only nodes contained within the TDLSchema.xsd file may be used in creating policy files. Although you can use any text editor when creating Enterprise Templates, I recommend using Microsoft Visual Studio .NET. The productivity gains and time saving features are well worth the extra price tag.
As you near the informational conclusion to this series, you will begin to apply the knowledge you have learned toward building Enterprise Template Editors using several different types of Visual Studio .NET Projects. By doing so, you will expand your programming horizons into different areas such as add-ins, Web services, and Web controls. In addition, by implementing enterprise templates using various project types you will gain valuable breadth of experience in your .NET Development knowledge.
The .NET Architect Enterprise Template Series comprises the following articles:
Article 3: Enterprise Template TDL Language <-- YOU ARE HERE
Article 4: Enterprise Template Dynamic Help
Article 5: Enterprise Template Exercise
Article 6: Enterprise Template Editor Add-In
Article 7: Enterprise Template Editor Web Service
Article 8: Enterprise Template Editor Windows Service
Article 9: Enterprise Template Editor Web Control
Article 10: Enterprise Template Editor Windows Control
Article 11: Enterprise Template Editor Framework
Article 12: Enterprise Template Developer Notes
Section 2: TDL Grammar Elements
<CATEGORIES>
Defines a container for grouping
logically similar elements defined elsewhere in the policy file
<CATEGORY>
Defines a reusable grouping of
logically similar elements
<CATEGORYMEMBER>
Defines a reference to a predefined
policy file element
<CMDID>
Defines the absolute position ID of
a menu item in a menu hierarchy
<CONSTRAINTS>
Defines a container for defining
restrictions on IDE properties, menus, and toolbox items
<CONTEXT>
Defines the content information
displayed by the Dynamic Help Window when navigating between IDE elements
<CTXTATTRIBUTE>
Defines a container for resolving
contextual switching and initialization issues related to dynamic help within
theVisual Studio .NET IDE
<DEFAULT>
Defines a default value for
automatically initializing a property
<DEFAULTACTION>
Defines the default inclusion or
exclusion setting to apply to a group of policy file elements
<DEFAULTSETTINGS>
Defines global enterprise
templatepolicy file settings for
each element
<DESCRIPTOR>
Defines a unique ID for an IDE
toolbox control
<ELEMENT>
Defines a unique enterprise template
building block
<ELEMENTS>
Defines a collection of all building
blocks available to an enterprise template
<ELEMENTSET>
Defines a container for grouping
building blocks
<ENABLED>
Defines an enabled or disabled state
for a menu item or toolbox item
<EXCLUDE>
Defines which template building
blocks are not permitted to be referenced from within the context of another
building block
<FEATURELINKS>
Defines which set of menu or toolbox
features may be associated to a specific template building block element
<FEATURES>
Defines the collection of menu and
toolbox items to be restricted via policy
<GUID>
Defines a globally unique identifier
for an IDE menu group
<ID>
Defines a mechanism for referencing
a node from other places in the policy file
<IDENTIFIER>
Defines locating, identifying and
configuration information about a specific policy file element
<IDENTIFIERDATA>
Defines a name/value pair for
processing references to elements
<IDENTIFIERS>
Defines a collection of identifying
nodes containing location, identification and configuration information for
specific elements
<INCLUDE>
Defines the ID of an element to
include in another place in the policy file
<MAXVALUE>
Defines the maximum allowable value
a property or element may contain
<MEMBERCONSTRAINT>
Defines restrictions on specific
element based upon an ID.
<MEMBERCONSTRAINTS>
Defines a collection of restraints
applying to specific menu, toolbox, or properties based upon an ID
<MENU>
Defines a menu item for later
reference in the policy file
<MENUCONSTRAINT>
Defines the enabled or disabled
restraint for a menu item
<MENUCONSTRAINTS>
Defines a collection of
context-based restricted menu items
<MENULINK>
Defines a relationship where a menu
item is disabled if the associated item is defined elsewhere in the policy
file with an exclusion setting
<MENULINKS>
Defines a collection of menu items
to be disabled when the associated item has the exclusion property set
<MENUS>
Defines a collection of menus to be
included in the policy file
<MINVALUE>
Defines a minimum allowable value
for an element
<NAME>
Defines a reference identifier for
accessing the node containing the value
<ORDER>
Defines the order in which
include/exclude settings are evaluated within a policy file element
<POLICYMODE>
Defines the mechanism for handling
undefined or unrecognized items
<PROPERTYCONSTRAINT>
Defines scope-restricted settings
for properties displayed within the IDE properties browser window
<PROPERTYCONSTRAINTS>
Defines a collection of
scope-restricted settings for properties displayed within the IDE properties
browser window
<PROTOTYPE>
Defines the location of a project,
item or enterprise template project from which a specific type of project can
be created
<PROTOTYPES>
Defines a collection of location
information for finding and creating specific types of enterprise template
projects
<READONLY>
Defines if a property is allowed to
be edited
<TDL>
Defines the root node of a policy
file, which contains all other policy file elements
<TOOLBOXCONSTRAINT>
Defines if a specific toolbox item
should be contextually enabled or disabled
<TOOLBOXCONSTRAINTS>
Defines a collection of toolbox
items that should be contextually enabled or disabled
<TOOLBOXITEM>
Defines an item to display within
the toolbox
<TOOLBOXITEMS>
Defines a collection of items to
display within the toolbox
<TOOLBOXLINK>
Defines a relationship where a
toolbox item is disabled if the associated item is defined elsewhere in the
policy file with an exclusion setting
<TOOLBOXLINKS>
Defines a collection of toolbox
items to be disabled when the associated item has the exclusion property set
<TYPE>
Defines a label identifying the type
of the logical element
<VALUE>
Defines the data portion of a name/value
pair
( figure 1.0 )
Section 3: TDL Grammar Element Explanations
<CATEGORIES> Defines a container for grouping logically similar
elements defined elsewhere in the policy file
Example:
You want to create a list of
artifacts developers are allowed to add to ASP.NET Web applications.
Explanation:
To enforce this restriction, first
define the allowable set of artifacts your developers can add to an ASP.NET
Web application.You decide
developers should add only CSS, HTML, XML and XSL items to ASP.NET Web
applications.These items are defined
elsewhere in your policy file.To
create your <CATEGORIES> node, you assigned it an identifier named
“catASPProjectItems.”You can see
this in line #4.Next, add each type
of Web item grouping to your <CATEGORIES> node by referencing its
existing unique ID value.This
process is shown in lines #5 - #8.Each web item grouping is listed inside a <CATEGORYMEMBER>
definition.
1:<TDL>
2:<CATEGORIES>
3:<CATEGORY> <!—ASP.NET Related Project
Items -->
4:<ID>catASPProjectItems</ID>
5:<CATEGORYMEMBER>projCSSItems</CATEGORYMEMBER>
6:<CATEGORYMEMBER>projHTMLItems</CATEGORYMEMBER>
7:<CATEGORYMEMBER>projXMLItems</CATEGORYMEMBER>
8:<CATEGORYMEMBER>projXSLItems</CATEGORYMEMBER>
9:</CATEGORY>
10:</CATEGORIES>
11: </TDL>
<CATEGORY>
Defines a reusable grouping of
logically similar elements
Example:
You want to group all technologies
available to your ASP.NET developers.
Explanation:
You determined your developers work
primarily with these Web technologies: ASP, HTML, CSS, XML, and XSL.The categories for these Web technologies
are defined elsewhere in the policy file.To include these groups in your own grouping, you need to reference
the existing groups by their names or IDs.Finally, to create your own category, implement line #3-9 below.These lines define a custom category of
pre-existing element groupings.Label
your new group by assigning a value to the <ID> node.This is done in line #4.
1:<TDL>
2:<CATEGORIES>
3:<CATEGORY> <!—ASP.NET Related Project
Items -->
4:<ID>catASPProjectItems</ID>
5:<CATEGORYMEMBER>projCSSItems</CATEGORYMEMBER>
6:<CATEGORYMEMBER>projHTMLItems</CATEGORYMEMBER>
7:<CATEGORYMEMBER>projXMLItems</CATEGORYMEMBER>
8:<CATEGORYMEMBER>projXSLItems</CATEGORYMEMBER>
9:</CATEGORY>
10:</CATEGORIES>
11: </TDL>
<CATEGORYMEMBER>
Defines a reference to a predefined
policy file element
Example:
You are designing template category
nodes referencing predefined policy categories.You want to create four nodes, each node referencing a unique,
preexisting category of items.
Explanation:
First, identify the preexisting
categories you want to add to your policy file.You decide to add these preexisting categories: CSS, HTML, XML,
and XSL technologies.Your new
category node is placed within its own grouping, by adding line #3
below.Your new category node should
apply to only ASP programming projects; therefore, locate the ID of the
existing group which is shown in line #4.Next, create a <CATEGORYMEMBER> node for each preexisting
category you want to reference (CSS, HTML, XML, XSL).Finally, give each grouping a unique ID
corresponding to its definition elsewhere in the policy file.This can be seen in lines #5-8 below.
1:<TDL>
2:<CATEGORIES>
3:<CATEGORY> <!—ASP.NET Related Project
Items -->
4:<ID>catASPProjectItems</ID>
5:<CATEGORYMEMBER>projCSSItems</CATEGORYMEMBER>
6:<CATEGORYMEMBER>projHTMLItems</CATEGORYMEMBER>
7:<CATEGORYMEMBER>projXMLItems</CATEGORYMEMBER>
8:<CATEGORYMEMBER>projXSLItems</CATEGORYMEMBER>
9:</CATEGORY>
10:</CATEGORIES>
11: </TDL>
<CMDID>
Defines the absolute position ID of
a menu item in a menu hierarchy
Example:
You decide to grant developers
access to the “Add Class” menu item of the “Project” menu.
Explanation:
Vside.tdl is the policy file
responsible for restricting Visual Studio .NET IDE elements.To add an enabled menu item to your own
policy file, you need three things: the menu item ID, the numeric ID Visual
Studio .NET uses to refer to the menu item, and the GUID for the menu
item.You are now ready to enable the
“Add Class” menu item of the “Project” menu.To do this, add lines #4-8 below.Notice you are adding a child <MENU> node under the
<MENUS> collection.All menu
elements declared for your template are located under the <MENUS> item
collection.
Defines a container for defining
restrictions on IDE properties, menus, and toolbox items
Example:
You want to restrict consultants
from adding new user controls to a project, from adding new database
connection controls via the toolbox, and you want to set a default value for
all database connection timeouts.
Explanation:
Your company standard mandates that
database connections must timeout between 30 and 90 seconds.Setting the database connection timeout
value is done by restricting a property.This setting is restricted by adding a child node under the
<PROPERTYCONSTRAINT> node in your policy file.Your current application contains user
controls, but a consultant you hired will be working on the project.You decide you want to restrict the
consultant from adding new user controls.Restricting users from adding new controls to existing projects is
done by adding a <MENUCONSTRAINT> node to your policy file.Last, you restrict the consultant from
adding database connection controls to the project.To restrict access to menu items, and enable or disable them,
add a new <MENUCONSTRAINT> node to your policy file.
Line #6 adds a
<PROPERTYCONSTRAINT> node to your policy file.Use this node to set the maximum and
minimum values for your database connection timeout property.Line #7 contains the name of the property
to configure – this is the database connection timeout property.Line #8 determines if the property is read
only.We want the property to be a
read/write property so we set the value to false.Line #9 sets the minimum value of the database connection
timeout property.Line #10 sets the
maximum value for the database connection timeout property.Line #11 ends the definition of your
property constraint.
Line #14 adds a
<MENUCONSTRAINT> node to your policy file.Use this node to restrict the user from adding new user
controls via the “Add User Control” menu item of the “Project” menu in the
Visual Studio .NET IDE.Line #15
contains the identifier Visual Studio .NET uses to reference an existing menu
or menu item.You want to restrict
the user from adding new user controls.The menu item identifier used by Visual Studio .NET to reference the
“Add User Control” menu item from the “Project” menu, is
“menuProject.AddUserControl”.This
identifier is placed in the <ID> node in line #15.Now that Visual Studio .NET knows to
restrict access to the menu item, you need to tell the IDE if the menu item
should be enabled or disabled.In our
case, we disable the menu item.You
can see this in line #16 below.
Line #20 adds a <TOOLBOXCONSTRAINT>
node to your policy file.Use this
node to restrict the user from adding new SQLDataConnection controls via the
toolbox.As is the case with menu
items, you must supply the identifier name Visual Studio .NET uses to
reference the toolbox item.Line #21
contains the identifier for the SQLConnection control, accessible from within
the toolbox.Now that Visual Studio
.NET is aware of a control to enable or disable, it must enable or disable
the toolbox item.In our case, we are
disabling the toolbox control.This
can be seen in line #22 below.
Defines the content information
displayed by the Dynamic Help Window when navigating between IDE elements
Example:
You have developed a library of
Visual Basic .NET controls.When navigating
between these controls you want to display immediate help for the user.You want to use the Dynamic Help Window of
the Visual Studio .NET IDE to display contextual help information.
Explanation:
Each policy file item, defined
within an <ELEMENT> tag, can have contextual, dynamic help associated
with it.To display appropriate help
information, the IDE needs to know which keywords are associated with the
item in question to display the appropriate help information.The IDE also needs to know how to
filterthe contextual search results
of a help file.Help files are often
very large and complex.It would be a
waste of time to return more information than required.For example, if you associate ADO.NET
Database Connection help, but do not further filter the result set of the
help file search, you will end up with a staggering number of help topics
EVERY TIME the user selects the element within the IDE.If there were only 50 topics, this would
certainly tax your patience and nerves.Using <CONTEXT> nodes effectively and efficiently requires solid
planning and solid design of the underlying help file as well.
You have defined the structure and
content of the help file associated with your user control.You have decided to filter the control’s
help file content by searching using the keywords identified in lines #6-8
below.These keywords identify the
help topics that may appear in the dynamic help window when the control has
the focus. Line #6 registers the WindowsForms keyword, line #7 registers the
WindowsControls keyword and line #8 registers the myLabelControl
keyword.These keywords will be
associated to your user control when it gains the focus, and will restrict
the contents of the dynamic help window.
Each keyword in a help file might
have multiple help file topics associated with it.The attributes defined in lines #9-16 below take the help
topics defined in lines #6-8 and further refine the list of displayable items
that appear in the dynamic help window.Line #9 filters the help topics by filtering the results using the
“Using” item defined in line #10.Line #11 defines the value that the item in line #10 should have.Lines #14 filters the help topics by
filtering the help file results on the “Deploying” item.Line #15 defines the value that we should
use to further filter the help results.
To recap, when the user selects your
control in a designer, the dynamic help window displays help.This help initially returns a list of help
topics, which can then be further filtered by applying the attributes in
lines #9-12 and lines #13-16 respectively.The end result is a full-filtered, custom-tailored view of the help
file, contextually relevant to the selection made in the IDE – in this case, the
selection of your user control.
1: <TDL>
2:<ELEMENTS>
3:<ELEMENT>
4:<ID>myUserControlID</ID>
5:<CONTEXT>
6:<CTXTKEYWORD>WindowsForms</CTXTKEYWORD>
7:<CTXTKEYWORD>WindowsControls</CTXTKEYWORD>
8:<CTXTKEYWORD>myLabelControl</CTXTKEYWORD>
9:<CTXTATTRIBUTE>
10:<NAME>Using</NAME>
11:<VALUE>Proper Use of</VALUE>
12:</CTXTATTRIBUTE>
13:<CTXTATTRIBUTE>
14:<NAME>Deploying</NAME>
15:<VALUE>Deploying With Your Application</VALUE>
16:</CTXTATTRIBUTE>
17:</CONTEXT>
18:</ELEMENT>
19:</ELEMENTS>
20:</TDL>
<CTXTATTRIBUTE>
Defines a container for resolving
contextual switching and initialization issues related to dynamic help within
theVisual Studio .NET IDE
Example:
You have created a custom Windows
control that allows a user to select a date by clicking on your custom user
interface.You want the dynamic help
window to initially filter on the “myCustomControl”, “myOtherTopic” and
“myFinalTopic” help topics but only want to display information relevant to
the control’s developer API.
Explanation:
You associate dynamic help with
enterprise template elements by including context keywords and content
attributes.These entries appear in
lines #6-8, line #9 and line #13 respectively.Since you know the <CTXTKEYWORD> associates to a help
file topic, you reference the help topic “myCustomControl” by adding a new
<CTXTKEYWORD> node to your policy file.This is implemented in line #6 below.The next help topic you implement is the “myOtherTopic” help
file.To reference this help topic,
add a new <CTXTKEYWORD> node to your policy file.This is implemented in line #7 below.Finally, you reference the help topic
“myFinalTopic” by adding a new <CTXTKEYWORD> node to your policy
file.This is implemented in line #8
below. Once a user navigates to your control, they will be shown a filtered
set of help topics – specifically, the “myCustomControl”, “myOtherTopic” and
“myFinalTopic” help file topics.
1:<TDL>
2:<ELEMENTS>
3:<ELEMENT>
4:<ID>myUserControlID</ID>
5:<CONTEXT>
6:<CTXTKEYWORD>myCustomControl</CTXTKEYWORD>
7:<CTXTKEYWORD>myOtherTopic</CTXTKEYWORD>
8:<CTXTKEYWORD>myFinalTopic</CTXTKEYWORD>
9:<CTXTATTRIBUTE>
10:<NAME>Using</NAME>
11:<VALUE>Proper Use of</VALUE>
12:</CTXTATTRIBUTE>
13:<CTXTATTRIBUTE>
14:<NAME>Deploying</NAME>
15:<VALUE>Deploying With Your Application</VALUE>
16:</CTXTATTRIBUTE>
17:</CONTEXT>
18:</ELEMENT>
19:</ELEMENTS>
20:</TDL>
<DEFAULT>
Defines a default value for
automatically initializing a property
Example:
You want to set the default
“FilePath” property of a new XML file to resolve to the path “C:\MyPath\”.
Explanation:
First, you need to assign an ID to
the property you are setting the default value for.This value will be used in other parts of your policy file to
reference this property and its default value.Line #4 creates a programmatic ID called “myXMLFilePath”, which
will be specific to your policy file.Line #24 defines the property for which we wish to define a default
value.In this case, we called the
property “myFilePathProperty” – obviously, this is only an example so we are
keeping things simple.Line #23 tells
us if the default value is writable – that is, if the default value may be
replaced with your own value at runtime.Line #23 indicates the property may not be replaced with our own at
runtime – it must use the default value assigned.Finally, line #24 provides the actual default value for our
property.We default the
“myFilePathProperty” to contain “C:\MyPath\”.This is shown in line #24 below.Each time we reference the ID “myXMLFilePath” defined in line
#4, its “myFilePathProperty” will default to a value of “C:\MyPath\”.
1:<TDL>
2:<ELEMENTS>
3:<ELEMENT>
4:<ID>myXMLFilePath</ID>
5:<IDENTIFIERS>
6:<IDENTIFIER>
7:<TYPE>REFERENCE</TYPE>
8:<IDENTIFIERDATA>
9:<NAME></NAME>
10:<VALUE></VALUE>
11:</IDENTIFIERDATA>
12:</IDENTIFIER>
13:</IDENTIFIERS>
14:<FEATURELINKS>
15:<TOOLBOXLINKS >
16:<TOOLBOXLINK ></TOOLBOXLINK>
17:</TOOLBOXLINKS>
18:</FEATURELINKS>
19:<CONSTRAINTS >
20:<PROPERTYCONSTRAINTS>
21:<PROPERTYCONSTRAINT >
22:<NAME >myFilePathProperty</NAME>
23:<READONLY >0</READONLY>
24:<DEFAULT >C:\MyPath\</DEFAULT>
25:</PROPERTYCONSTRAINT>
26:</PROPERTYCONSTRAINTS>
27:</CONSTRAINTS>
28:</ELEMENT>
29:</ELEMENTS>
30:</TDL>
<DEFAULTACTION>
Defines the default inclusion or
exclusion setting to apply to a group of policy file elements
Example:
When creating a new project, you
wish to include only those items belonging to specific categories.All other items are to be excluded from
the project.
Explanation:
To include only those items in
specific categories, you must decide which categories contain the items you
want to include in your project.The
categories in lines #6 - #10 contain the items you want included.Line #6 includes the common components
your project will use, line #7 includes the common controls your project will
use, line #8 includes common ASP items for your project, line #9 includes
common HTML snippets your projects uses, and line #10 includes common CSS
definitions in your project.
Now that you defined the categories
to include in your project, there remain alternatives to exclude from your
project.A mechanism is needed to
ensure only the categories listed in lines #6 - #10 are included in our new
project; all others must be excluded.Line #4 instructs the policy file to exclude all possible combinations
of items from our policy file.Essentially, line #4 says “create me an empty project containing
nothing.Include ALL possible
items.”If we excluded all possible
items that could be added to our project, the policy file we are creating
becomes useless.We need a mechanism
to include those categories that contain the items we want to add by default
to our project.Lines #6 - #10
contain these categories.Each
category you want to include must be defined using an <INCLUDE>
node.You can include as many of
these as you like since they reference IDs of existing policy file items.
1:<TDL>
2:<ELEMENTS>
3:<ELEMENTSET>
4:<DEFAULTACTION>EXCLUDE</DEFAULTACTION>
5:<ORDER>INCLUDEEXCLUDE</ORDER>
6:<INCLUDE>catCommonComponent</INCLUDE>
7:<INCLUDE>catCommonControls</INCLUDE>
8:<INCLUDE>catCommonASP</INCLUDE>
9:<INCLUDE>catCommonHTML</INCLUDE>
10:<INCLUDE>catCommonCSS</INCLUDE>
11:</ELEMENTSET>
12:</ELEMENTS>
13:</TDL>
<DESCRIPTOR>
Defines a unique
ID for an IDE toolbox control
Example:
You want to
display two controls in the IDE Toolbox: the HTML Button Control and the HTML
Reset Control.
Explanation:
You must add a
policy file entry for each IDE Toolbox control to be displayed for your
project.Controls not explicitly
tagged for display will not be visible in the IDE Toolbox.Our policy file will enable two controls
to be displayed in the IDE Toolbox: the HTML Button Control and the HTML
Reset Control.Line #12 defines a
programmatic identifier for our HTML Button Control.By assigning an ID to this control you can
refer to it from within other places in your policy file.Line #13 creates the actual descriptive
information to display for our HTML Button Control.In this case, notice the descriptor information contains a
string of HTML.You could also have
referenced the .NET Framework class that contains the code to render the
button as well.Now we need to inform
the IDE Toolbox we want to display the HTML Reset Control.Line #16 defines an identifier we can use
to refer to this control in other parts of our policy file.Line #17 contains the descriptor
information for the HTML Reset Control.Notice that it too is a string of HTML and that we could have also
referenced the .NET Framework class that contains the code to render the
control as well.If you wanted to add
to our example here, you can simply add another <TOOLBOXITEM> node with
the appropriate child nodes, using the lines below as your guide.
Defines a unique enterprise template
building block
Example:
Create the policy structure when a
new ASP.NET Web application is created.
Explanation:
We are creating an element that can
be referenced elsewhere within our policy file; thus, we provide an ID for
the new element in line #4 called “etpWebApplication”.Notice the prefix of “etp” – this
identifies the element as being an enterprise template project, which will
contain project prototypes.We will
see this in a moment.Lines #5 - #16
define the settings to display and manage context-sensitive help displayed
within the dynamic help window.Lines
#6 - #7 define the topics to initially filter by.Lines #8 - #11 further filter the help topics listed
previously.Lines #8 - #11 define a
filter for the help topics of lines #6 and #7.Lines #12 - #15 define another filter for the help topics of #
6 and #7.The end result is the help
topics are displayed and filtered whenever the user selects the element in
the IDE.In summary, you created a
new element and assigned it an ID in line #4.You identified the help topics associated with your new element
in lines #6 and #7.You filtered
these topics by defining refinements to the help topic information in lines
#8 - #15.As a result of these
actions, contextual help will be displayed in the dynamic help window
whenever the user navigates to your new element.
Of special note in this example, is
lines #26 - #29.These lines define
the location of pre-existing application code, built as “black box”, reusable
application components.Thus, when
you want to create your new application identified in line #4, you will also
automatically include the projects (or prototypes) listed in lines #27 - #28
below.You may think of enterprise
template projects as projects that have been previously created, tested,
compiled, and debugged.For example,
if you wish to create a new Web application you may have a code base of
pre-tested components you wish to reuse.Since you want these components to occur in every instance of a new
Web application, you decide to include them as “prototypes”.That way, whenever a new Web application
is created you will have a large portion of the boilerplate code already
written.
Also of note is lines #33 -
#42.These lines reference other
elements within your policy file.In
addition to your standard project boilerplate code, you may also want other types
of items included.These lines
identify the ID of those elements that have other needed functionality for
your application.For example, in
line #40 you include common CSS boilerplate code since you are developing a
Web application.This code could
contain the standard CSS definitions for your typical Web application.
Defines a collection of all building
blocks available to an enterprise template
Example:
You want to include elements in your
policy file for Web applications and Web services definitions.
Explanation:
The skeleton of a typical
<ELEMENTS> node is shown below.For the sake of brevity, we have only listed the common items of the
<ELEMENTS> container node.The
element definitions are labeled to illustrate how the number of elements
defined in your policy file greatly influences the final policy file
size.And as you may already have
inferred from the examples in this article, policy files can be QUITE LARGE
INDEED!It is not uncommon for your
policy files to average 1 MB in size! Or MORE!
1:<TDL>
2:<ELEMENTS>
3:<ELEMENT><!—Element #1-->
4:<ID>webApplications</ID>
5:<CONTEXT>
6:<CTXTKEYWORD></CTXTKEYWORD>
7:<CTXTATTRIBUTE>
8:<NAME></NAME>
9:<VALUE></VALUE>
10:</CTXTATTRIBUTE>
11:</CONTEXT>
12:<IDENTIFIERS>
13:<IDENTIFIER>
14:<TYPE></TYPE>
15:<IDENTIFIERDATA>
16:<NAME></NAME>
17:<VALUE></VALUE>
18:</IDENTIFIERDATA>
19:</IDENTIFER>
20:</IDENTIFIERS>
21:<PROTOTYPES>
22:<PROTOTYPE></PROTOTYPE>
23:</PROTOTYPES>
24:<ELEMENTSET>
25:<DEFAULTACTION></DEFAULTACTION>
26:<ORDER></ORDER>
27:<INCLUDE></INCLUDE>
28:<INCLUDE></INCLUDE>
29:</ELEMENTSET>
30:</ELEMENT>
31:<ELEMENT><!—Element #2-->
32:<ID>webServices</ID>
33:<CONTEXT>
34:<CTXTKEYWORD></CTXTKEYWORD>
35:<CTXTATTRIBUTE>
36:<NAME></NAME>
37:<VALUE></VALUE>
38:</CTXTATTRIBUTE>
39:</CONTEXT>
40:<IDENTIFIERS>
41:<IDENTIFIER>
42:<TYPE></TYPE>
43:<IDENTIFIERDATA>
44:<NAME></NAME>
45:<VALUE></VALUE>
46:</IDENTIFIERDATA>
47:</IDENTIFER>
48:</IDENTIFIERS>
49:<PROTOTYPES>
50:<PROTOTYPE></PROTOTYPE>
51:</PROTOTYPES>
52:<ELEMENTSET>
53:<DEFAULTACTION></DEFAULTACTION>
54:<ORDER></ORDER>
55:<INCLUDE></INCLUDE>
56:<INCLUDE></INCLUDE>
57:</ELEMENTSET>
58:</ELEMENT>
59:</ELEMENTS>
60:</TDL>
<ELEMENTSET>
Defines a container for grouping
building blocks
Example:
For each Web application project
created, also include its standard CSS, XSL, and XML items.
Explanation:
Line #2 creates a container holding
all referenced elements, as well as those element nodes' associated projects,
items, and settings.Line #4 assigns
an ID for referencing this element elsewhere in the policy file.We need a way to associate other items
with our project identified in line #4, thus we create an <ELEMENTSET>
node.This node will reference
projects defined in other parts of your policy file.Our goal is to merge CSS, XSL, and XML
items and settings into a new Web application, defined in line #4.Lines #8 - #10 reference the projects
defined elsewhere in our policy file, which should also be included when the
project in line #4 is referenced.When you reference the project in line #4, you will also be
referencing (or including) the items listed in lines #8 - #10 as well.
1:<TDL>
2:<ELEMENTS>
3:<ELEMENT>
4:<ID>prjStandardWebTechnologies</ID>
5:<ELEMENTSET>
6:<DEFAULTACTION>EXCLUDE</DEFAULTACTION>
7:<ORDER>INCLUDEEXCLUDE<ORDER>
8:<INCLUDE>prjCSSItems</INCLUDE>
9:<INCLUDE>prjXSLItems</INCLUDE>
10:<INCLUDE>prjXMLItems</INCLUDE>
11:</ELEMENTSET>
12:</ELEMENT>
13:</ELEMENTS>
14:</TDL>
<ENABLED>
Defines an enabled or disabled state
for a menu item or toolbox item
Example:
You want to restrict the user from
adding new classes to a project.
Explanation:
To restrict the user from
manipulating an IDE element, you apply constraints to the IDE element.In our example we are restricting access
to a specific menu item.Menu items are
restricted by adding a <MENUCONSTRAINT> node to policy files.Each menu item in the IDE is exposed to
your policy through a unique identifier for that menu item.You can find a complete listing of the
menu item identifiers in the VSIDE.TDL policy file.In our case, the “Add Class” menu item of the “Project” menu
contains the unique identifier of “menuProject.AddClass”.This is the identifier value we will use
to define which menu item to restrict.This identifier can be seen in line #7 below.This line identifies the menu item to
restrict.Line #8 informs the IDE
that we should disable this menu item when the user selects the “Project”
menu.Restricting a menu item in your
policy file is just as easy as following the template below.
1:<TDL>
2:<ELEMENTS>
3:<ELEMENT>
4:<CONSTRAINTS >
5:<MENUCONSTRAINTS>
6:<MENUCONSTRAINT>
7:<ID>menuProject.AddClass</ID>
8:<ENABLED>0</ENABLED>
9:</MENUCONSTRAINT>
10:</MENUCONSTRAINTS>
11:</CONSTRAINTS>
12:</ELEMENT>
13:</ELEMENTS>
14:</TDL>
<EXCLUDE>
Defines which template building
blocks are not permitted to be referenced from within the context of another
building block
Example:
Exclude all ASP and XML elements
from the current element set.
Explanation:
For a specific policy file element
you can include and exclude elements to create a customized list of allowable
elements.Elements are included or
excluded by supplying an <INCLUDE> or an <EXCLUDE> entry for each
type of element to include or exclude respectively.In this example, we instruct the policy file to include CSS and
XSL items.This is shown in lines #8
and #9 below.The items to exclude
are listed in lines #10 and #11. One note of importance is line #6 and line
#7.Line #6 defines the default
action to take when building your new element set.Remember, there could be hundreds of elements defined in your policy
file; however, you do not want to process them all.As a shortcut to explicitly listing ALL elements to include or
exclude in each <ELEMENT> node of an <ELEMENTSET> container, you
simply instruct the policy file to either include or exclude all elements in
the policy file.Line #6 instructs
the policy file to ignore all defined elements.Now that we have excluded all elements in the policy file that
will define our new element set, you need a way to handle any items you wish
to manipulate.Line #7 takes care of
this.This line instructs your policy
file to process the “include” elements listed in lines #8 and #9 below first,
then “exclude” the elements listed in lines #10 and #11 below.Thus, line #7 sets the order in which the
<INCLUDE> or <EXCLUDE> elements are defined.
1:<TDL>
2:<ELEMENTS>
3:<ELEMENT>
4:<ID>prjStandardWebTechnologies</ID>
5:<ELEMENTSET>
6:<DEFAULTACTION>EXCLUDE</DEFAULTACTION>
7:<ORDER>INCLUDEEXCLUDE<ORDER>
8:<INCLUDE>prjCSSItems</INCLUDE>
9:<INCLUDE>prjXSLItems</INCLUDE>
10:<EXCLUDE>prjXMLItems</EXCLUDE>
11:<EXCLUDE>prjASPItems</EXCLUDE>
12:</ELEMENTSET>
13:</ELEMENT>
14:</ELEMENTS>
15:</TDL>
<FEATURELINKS>
Defines which set of menu or toolbox
features may be associated to a specific template building block element
Example:
Associate the “Add Class” menu item
of the “Project” menu to the currently selected item.
Explanation:
You associate menu items to element
by including those menu items you want to be reference in the
<MENULINKS> section of the element.In the example below, we want to associate the “Add Class” menu item
of the “Project” menu with the element defined in line #3.To do this, we add the contents on line #6
below.The exact ID of the menu item
was derived from examining the VSIDE.tdl policy file.You can consult your online help file for
the exact location of this file on your computer if you accepted the defaults
during installing Visual Studio.
1:<TDL>
2:<ELEMENTS>
3:<ELEMENT>
4:<FEATURELINKS>
5:<MENULINKS>
6:<MENULINK>mnuProject.AddClass</MENULINK>
7:</MENULINKS>
8:</FEATURELINKS>
9:</ELEMENT>
10:</ELEMENTS>
11:</TDL>
<FEATURES>
Defines the collection of menu and
toolbox items to be restricted via policy
Example:
You want to include the “Add Class”
and “Add User Control” menu items for use in your policy file.
Explanation:
Each policy file contains certain
features common to the entire policy file.These features are contained within the top-level <FEATURES>
node of a policy file, as seen in line #2.In our case, we are defining some menu items to be features of our
policy file.These features will be
listed under the <MENUS> item in line #3 below.Line #3 acts a container for all menus we
want to define as features of our policy file.We are including two menu items in our policy file: the “Add
Class” and “Add User Control” menu items.Each of these items is defined by adding a <MENU> node under the
<MENUS> container.Thus, line
#4 begins the definition for the “Add Class” menu item, and line #9 begins
the definition for the “Add User Control” menu item.Each menu item contains a unique ID which
the Visual Studio IDE uses to refer to the menu item.Thus, line #6 defines the ID for the “Add
Class” menu item while line #11 defines the ID for the “Add User Control”
menu item.Each menu item also has a
GUID associated with it.The ID and
GUID combination values form the definition of a menu item.Line #7 contains the GUID for the “Add Class”
menu item while line #12 contains the GUID for the “Add User Control” menu
item.Any additional menu items to be
common to the entire policy file are added by creating a new <MENU>
entry and duplicating lines #4 - #8 and substituting your own values.
Defines a globally unique identifier
for an IDE menu group
Example:
You want to enable the “Cut”,
“Copy”, and “Paste” menu items from the “Edit” menu group.
Explanation:
Each menu in the Visual Studio .NET
IDE contains menu items contained within logical menu groupings.Each grouping is assigned a unique ID
referenced by the Visual Studio .NET IDE.In the example below, we defined three menu items to enable – Line #5
enables the “Cut” command of the “Edit” menu, line #10 enables the “Copy”
command of the “Edit” menu, and line #15 enables the “Paste” command of the
“Edit” menu.Notice that each menu
item contains a unique <CMDID> entry which identifies it as a unique
menu item, while each menu item contains the same <GUID> value,
identifying the menu group they menu items belong to – in our case, this is
the “Edit” menu.You can see this in
line #7, line #12, and line #17 below.
Defines a mechanism for referencing
a node from other places in the policy file
Example:
Define an entry for the “Edit” menu,
“Cut” command.
Explanation:
Defining an ID for a policy file
element is equivalent to defining a variable in your programs.An <ID> entry will enable the
element to be located and referenced elsewhere in the policy file.In the example below, you define an entry
for the “Cut” menu item in line #5.This is the ID you will use to refer to this item in other parts of your
policy file.Line #6 provides the
unique menu command ID for the item, while line #7 defines the menu group
this menu command is attached to.(Remember that menu commands belong to a menu group).
Defines locating, identifying, and
configuration information about a specific policy file element
Example:
You want to define a template for
future C# Projects.
Explanation:
Each element in your policy file
must have a unique ID associated with it.Line #4 assigns a unique ID for your C# Project Template.The <IDENTIFIER> node defined in
lines #7 - #12 provides a container for information describing your new C#
Project Template.Line #7 informs
referencing elements they are referencing a Project Item Type.Other meta-data for the Project Item Type
is defined in lines #9 - #10.Line #9
identifies the type of attribute we are setting meta-data for – in this case,
which file extension comprises a C# Project Template.Line #10 defines the file extension for a
new C# Project Template.Thus, when
the item in line #4 is referenced elsewhere in your policy file, you are
referencing a Project Item Type (C# Project) which has a .csproj file
extension.
