Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

Creating ELEMENT Identification in an Enterprise Template

Visual Studio .NET 2003

ELEMENT identification refers to applying identifying information within ELEMENT definitions to be able to associate an ELEMENT with one or more items in Solution Explorer. This topic provides several scenarios showing how to use a variety of the types of identification available to you.

Scenario 1: Identifying Custom Projects
Apply identification to a project by using a project global variable.
Scenario 2: Identifying Custom Project Items
Apply identification of a project item through the code within the project item.
Scenario 3: Identifying a User-Created Class
Apply identification to code objects.
Scenario 4: Identifying Code Variables
Apply identification to any controls that derive from a common base class.
Scenario 5: Identifying a Reference to a DLL
Apply identification to a DLL reference.
Scenario 6: Identifying an HTML Item
Apply identification to HTML Toolbox items.
Note   If a project does not compile, the identification may be incomplete or incorrect.

Scenario One: Identifying Custom Projects

You can identify projects three ways. To identify unique projects, define a project global variable in the project file and then reference the global variable from the IDENTIFIERS node in the policy file. To identify categories of projects, reference either a file extension or a property name from the IDENTIFIERS node in the policy file.

Identifying Unique Projects Using Project Global Variables

If your goal is to identify a project, either one that has a prototype that is used to create other projects or one that exists as a project within the current application, the recommended method is to identify the project through the use of a project global variable (UserProperty). A project global variable allows you to identify a project when there is not enough other information available within the project file to allow you to uniquely identify it. To use a project global variable, you must first define it in a project file and then reference it in your policy file.

The project global variable takes different formats, depending on whether you are modifying an .etp file, a .vbproj or .csproj file, or a .vcproj file. If you are modifying a template project file, add the project global variable to the appropriate project file in the \EnterpriseFrameworks\Projects folder. (If you chose the default installation location, the folder is located in C:\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Projects). If you are modifying a user project, add the project global variable to the specific project file in your My Documents\Visual Studio Projects directory. The following table shows how to add a global variable named "TDLELEMENTTYPE" with an associated value to a given project file type. You can specify something meaningful to your project in place of "identifierValue." You can also use a differently named global variable if so desired.

Project File Example Project Global Format
.etp file
<EFPROJECT>
    <! — - other stuff goes here -->
    <GLOBALS>
        <GLOBALENTRY>
             <NAME>TDLELEMENTTYPE</NAME>
              <VALUE>identifierValue</VALUE>
        </GLOBALENTRY>
    </GLOBALS>
</EFPROJECT>

.vbproj file or .csproj file
<VisualStudioProject>
        <! — - other stuff goes here -->
        <UserProperties TDLELEMENTTYPE = "identifierValue"/>
    </CSHARP>
</VisualStudioProject>

.vcproj file
<VisualStudioProject>
    <!-- other stuff goes here -->
    <GLOBALS>
        <GLOBAL
            Name="TDLELEMENTTYPE"
            Value="identifierValue"/>
    </GLOBALS>
</VisualStudioProject>

After adding the project global variable to the project file, the identification in the policy file is very simple. The following ELEMENT definition in a policy file shows identification of a project based on this method:

<ELEMENT>
    <ID>elementNameForProject</ID>
    <IDENTIFIERS>
        <IDENTIFIER>
            <TYPE>PROJECT</TYPE>
            <IDENTIFIERDATA>
                <NAME>GLOBAL:TDLELEMENTTYPE</NAME>
                <VALUE>identifierValue</VALUE>
            </IDENTIFIERDATA>
        </IDENTIFIER>
    </IDENTIFIERS>
</ELEMENT>

The lines shown above are only those required for ELEMENT identification. An actual ELEMENT node would contain additional information.

Identifying Projects Using File Extensions

For projects, you might want to provide another type of identification that is more generic. If, for example, you want to prevent any Visual C++ projects from being used within your application, you would define an ELEMENT that matches all Visual C++ projects in the following way:

<ELEMENT>
    <ID>projVisualCpp</ID>
    <IDENTIFIERS>
        <IDENTIFIER>
            <TYPE>PROJECT</TYPE>
            <IDENTIFIERDATA>
                <NAME>FileExtension</NAME>
                <VALUE>.vcproj</VALUE>
            </IDENTIFIERDATA>
        </IDENTIFIER>
    </IDENTIFIERS>
</ELEMENT>

Note that you are still dealing with a project (accordingly, you make the <TYPE>Project</TYPE> entry), but since you want to match any Visual C++ projects, you can base your identification on the file extension common to Visual C++ projects (.vcproj).

Identifying Projects Using Project Properties and Extensibility

You can also identify a project through project properties. While you can see some of these in the Property Pages (not the Properties window) or in the contents of the project file (.csproj, .vbproj, or .vcproj), the recommended method to determine the property name and value for identification is through extensibility. There are a number of cases where the display/storage value of the property does not match the necessary representation (for example, extensibility expects 0 or 1 for a Boolean property, but it is displayed and stored as True/False). For more information on extensibility, see Extending the Visual Studio Environment.

The example below shows identification of a project whose RootNamespace property has a value of UtilityLibrary.

<ELEMENT>
    <ID>projUtilityLibrary</ID>
        <IDENTIFIERS>
            <IDENTIFIER>
                <TYPE>PROJECT</TYPE>
                <IDENTIFIERDATA>
                    <NAME>Property:RootNamespace</NAME>
                    <VALUE>UtilityLibrary</VALUE>
                </IDENTIFIERDATA>
            </IDENTIFIER>
        </IDENTIFIERS>
</ELEMENT>

Scenario Two: Identifying Custom Project Items

Project items are typically identified by their file extension alone. You do not need to differentiate between a project item containing a specific class, for example the custom DataSet class, and another class file; this type of distinction is not made through project items, but rather through code items. A project item is a container. In the case of Visual C#, Visual C++, or Visual Basic files, a project item is a container for code. In the case of HTML, it is a container for HTML items. If you examine the Distributed Application Template policy file (DAP.tdl), you can see that project items are all identified by file extension.

If you find yourself identifying a new type of project item, for example an .sdl file, the ELEMENT definition is very similar to the preceding example for projects:

<ELEMENT>
    <ID>projItemSDLFile</ID>
    <IDENTIFIERS>
        <IDENTIFIER>
            <TYPE>PROJECTITEM</TYPE>
            <IDENTIFIERDATA>
                <NAME>FileExtension</NAME>
                <VALUE>.SDL</VALUE>
            </IDENTIFIERDATA>
        </IDENTIFIER>
    </IDENTIFIERS>
</ELEMENT>
Tip   Notice the use of a standard naming convention when naming ELEMENT nodes. This makes it very easy to understand ELEMENTSET definitions. For more information, see Naming Conventions in Enterprise Templates.

Scenario Three: Identifying a User-Created Class

Being able to identify code objects, such as classes, is often useful. Classes are identified either based on the classes from which they are derived or on the interfaces they implement. The following example shows how to perform the identification for a class defined as follows:

public class SerializableDataSet : DataSet, ISerializable
Note   This example is from the policy file MyTemplate.tdl. For more information on how to create the sample policy file MyTemplate.tdl, see Walkthrough: Creating a New Enterprise Template.

The corresponding ELEMENT definition for this class in the policy file is as follows:

<ELEMENT>
    <ID>codeSerializableDataSet</ID>
    <IDENTIFIERS>
        <IDENTIFIER>
            <TYPE>CODE</TYPE>
            <IDENTIFIERDATA>
                <NAME>Inherits</NAME>
                <VALUE>System.Data.DataSet</VALUE>
            </IDENTIFIERDATA>
            <IDENTIFIERDATA>
                <NAME>Implements</NAME>
                <VALUE>System.Runtime.Serialization.ISerializable</VALUE>
            </IDENTIFIERDATA>
        </IDENTIFIER>
    </IDENTIFIERS>
</ELEMENT>

Scenario Four: Identifying Code Variables

Identifying Derived Controls

You can identify any controls that derive from a common base class. For example, you can look for any controls derived from System.Windows.Forms.ListView. The important distinction between the user-created class scenario above and this scenario is that controls, when used, are code variables within a class. To identify them, use the CODEVARIABLE identification type. Since inheritance is important, use TYPEINHERITS rather than TYPENAME.

<ELEMENT>
    <ID>codeDerivedListView</ID>
    <IDENTIFIERS>
        <IDENTIFIER>
            <TYPE>CODEVARIABLE</TYPE>
            <IDENTIFIERDATA>
                <NAME>TypeInherits</NAME>
                <VALUE>System.Windows.Forms.ListView</VALUE>
            </IDENTIFIERDATA>
        </IDENTIFIER>
    </IDENTIFIERS>
</ELEMENT>

Identifying Specific Controls

You can also identify specific controls. Assume you are only concerned with ListView controls but do not care about controls derived from ListView. In this case you could use the following identification instead of the one above.

<ELEMENT>
    <ID>codeJustListView</ID>
    <IDENTIFIERS>
        <IDENTIFIER>
            <TYPE>CODEVARIABLE</TYPE>
            <IDENTIFIERDATA>
                <NAME>TypeName</NAME>
                <VALUE>System.Windows.Forms.ListView</VALUE>
            </IDENTIFIERDATA>
        </IDENTIFIER>
    </IDENTIFIERS>
</ELEMENT>

In the standard DAP.tdl and Vside.tdl files, Windows Forms and Web Forms Toolbox items are identified using TypeName.

Scenario Five: Identifying a Reference to a DLL

In addition to the types of ELEMENT nodes described above, you can also identify a reference to a particular DLL. This allows you to identify a DLL when a particular version is required. For example, the following ELEMENT definition allows only version 4.3 of a DLL named PerfUtil.dll:

<ELEMENT>
    <ID>refPerfUtil</ID>
    <IDENTIFIERS>
        <IDENTIFIER>
            <TYPE>REFERENCE</TYPE>
            <IDENTIFIERDATA>
                <NAME>FileName</NAME>
                <VALUE>PerfUtil.DLL</VALUE>
            </IDENTIFIERDATA>
            <IDENTIFIERDATA>
                <NAME>MajorVersion</NAME>
                <VALUE>4</VALUE>
            </IDENTIFIERDATA>
            <IDENTIFIERDATA>
                <NAME>MinorVersion</NAME>
                <VALUE>3</VALUE>
            </IDENTIFIERDATA>
        </IDENTIFIER>
    </IDENTIFIERS>
</ELEMENT>

If you want to specify a given version or any newer version, you can either identify all of the good versions or identify all bad versions and exclude them. The latter method is often easier as you can define ELEMENT nodes for the earlier versions of the DLL, place them in a CATEGORY node (for example, catBadVersionsOfPerfUtil), and then exclude the CATEGORY node from the ELEMENTSET of the desired projects.

Scenario Six: Identifying an HTML Item

Another type of ELEMENT identification you can use is for HTML items. This method of identification is used to recognize HTML Toolbox items. For example, the HTML looks as follows for an HTML button:

<input id=PushMeButton type=button value=Button>

To identify this button, use a combination of the tag and attribute identifiers as follows:

<ELEMENT>
    <ID>codeHTMLButton</ID>
    <IDENTIFIERS>
        <IDENTIFIER>
            <TYPE>HTMLELEMENT</TYPE>
            <IDENTIFIERDATA>
                <NAME>TAG</NAME>
                <VALUE>Input</VALUE>
            </IDENTIFIERDATA>
            <IDENTIFIERDATA>
                <NAME>Attribute:type</NAME>
                <VALUE>button</VALUE>
            </IDENTIFIERDATA>
        </IDENTIFIER>
    </IDENTIFIERS>
</ELEMENT>

Notice that the ELEMENT definition specifies that the interesting attribute is "type" with a value of "button". The HTMLElement type can be used to identify any HTML construct.

See Also

Identification in TDL | Using ELEMENTSET Nodes to Specify Constraints in Policy Files

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.