Enterprise Development with Visual Studio .NET, UML, and MSF

Last Updated 2/3/2009 3:43:02 PM

Abstract
In this chapter from "Enterprise Development with Visual Studio .NET, UML, and MSF," you'll learn about using policy files in conjunction with enterprise template projects to constrain and guide developers working on an enterprise solution. The chapter covers policy file concepts, provides an overview of the policy file format and schema, and explains how to create and edit policy files.

'

In this chapter, you'll be introduced to policy files. Policy files are used in conjunction with enterprise template projects, as described in Chapter 8. Enterprise template projects are application prototypes for various project types. Policy files allow you to constrain and guide the developers working on your enterprise solution. You can use policy files with both enterprise editions of VS .NET: VSED and VSEA. However, you can create and edit policy files only with VSEA. This chapter will cover a fair bit more than just the basics of using policy files. If you think the first few pages are a bit dry, please bear with us. We need to cover some basic information before we can move on to the more exciting stuff. First, we'll cover some policy file concepts, including context and scope. Then we'll provide an overview of the policy file format and schema. After we've gotten through the introductory material, we'll explain how to create and edit policy files, and you'll see how powerful they can be.

Another feature of policy files is the possibility of associating specific help topics with each of the items in an enterprise solution, making sure that the most appropriate help topics are displayed in the Dynamic Help window. This is covered in Chapter 10.

POLICY FILE CONCEPTS

Enterprise solutions usually consist of many smaller projects, so it can be difficult to control all aspects of the solution. Even if an organization has written standards for which components or project types to use, there is no guarantee that the developers will actually adhere to those standards. This is where policy files come into the picture. They can restrict and guide the developers on the individual projects in your enterprise solution, by establishing which components, project types, and solution items can and must be used.

The policy file is said to describe the structure and elements of an enterprise solution. It also governs which technologies you can use in the solution or add to the solution, in terms of solution items (such as projects) and components.

Policy files can be used not only to restrict certain solution items, but also for specifically permitting other items. This is what makes a policy file ideal for large enterprise solutions: the author of a policy file can specify in as much detail as needed what the solution can, must, or must not include.

All of the enterprise template project prototypes that come with VSEA and VSED, described in Chapter 8, use the prebuilt DAP.tdl policy file, the standard one for distributed applications. Another prebuilt policy file is named VSIDE.tdl. These files have most of the items in the VS .NET IDE defined, ready for you to copy them into your own policy files. They're usually located in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder.

TIP: The DAP.tdl and VSIDE.tdl files are prebuilt policy files you can use as a starting point for creating your own policy files. DAP.tdl contains elements that are appropriate for an enterprise solution, whereas VSIDE.tdl contains element definitions of the IDE features in VS .NET. In general, you can use a copy of the DAP.tdl as the initial policy file for your enterprise solutions, and then copy IDE element definitions, such as menu items, from the VSIDE.tdl file as needed.

Policy File Context

Policy files apply policies for the developers to a given context. As shown in Figure 9-1, this context can be any of the following three:

The entire enterprise template project (this will make up your solution)
A single enterprise template project item, such as a project
A single component, such as a Label control or a COM component When you set up your policy, you must decide which context the policy should govern.

Policy File Items

In relation to policy files, an item is anything you can apply a restriction or guideline to, such as menus, menu items, toolbox items, projects, project items, and references.

A policy file handles two different kinds of items: identified and unidentified items. Identified items are items that are explicitly part of the policy file through an ELEMENT node, which describes a single item in an enterprise template project. (The ELEMENT and other nodes in a policy file are discussed in the upcoming section on policy file format and schema.) As you can probably guess, unidentified items are those items that have not been specified as ELEMENT nodes.

But why would you need to work with unidentified items? The reason is that you won't know exactly what developers will do. For example, you don't want to explicitly create all possible project items in a project as ELEMENT nodes if you're leaving it up to the developers to decide which items to add. In fact, it would be impossible to know all possible items; literally thousands of different components can be added to a project.

Policy File Scope

The Template Description Language (TDL) language, which is used for policy files, doesn't provide full inheritance. However, when you refer to a policy file from an enterprise template project file, your subprojects and project items within the enterprise template project file automatically inherit the policy file settings from the parent project. This also means that you cannot have one policy file for a parent item, like the enterprise template project file, and another one for a subproject. For this reason, you cannot change the policy file for a child item, as illustrated in Figure 9-2.

In Figure 9-2, you can see that the Policy File property is disabled in the Properties window. If you manually changed this value to a different policy file than the one for the parent item, and tried to open the project in the VS .NET IDE, you would get an error message, and the subproject would not be opened.

POLICY FILE FORMAT AND SCHEMA

A policy file is really nothing more than an ASCII text file expressed using TDL, an implementation of XML. Listing 9-1 shows an abbreviated version of a policy file.

Listing 9-1. Policy File Structure

<?xml version="1.0" ?>
<TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">
  <DEFAULTSETTINGS></DEFAULTSETTINGS>
  <ELEMENTS>
    <ELEMENT>
      <ID></ID>
      <CONTEXT></CONTEXT>
      <IDENTIFIERS></IDENTIFIERS>
      <ELEMENTSET></ELEMENTSET>
      <CONSTRAINTS></CONSTRAINTS>
       <PROTOTYPES></PROTOTYPES>
      <FEATURELINKS></FEATURELINKS>
    </ELEMENT>
  </ELEMENTS>
  <CATEGORIES></CATEGORIES>
  <FEATURES></FEATURES>
</TDL>

Note that the policy file shown in Listing 9-1 doesn't contain any constraints; it has only the root and first-level nodes.

NOTE: The schema file used for policy files is the TDLSchema.xsd file, usually located in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Schemas folder. Although you can manually edit this file to extend the TDL schema, it is not recommended, because you risk destroying the policy file's functionality.

Because TDL is XML-based, you use nodes or elements to describe your policy. You'll find details about how the nodes and elements work in the "Creating and Editing Policy Files" section later in this chapter, and we've included a list of all the nodes in the TDL schema in the "TDL Nodes" section at the end of this chapter. A diagram that shows all the nodes in the TDL hierarchy is available as a downloadable PDF file from the Downloads section of the Apress Web site (http://www.apress.com). Here, we will take a broad look at the root and first-level nodes in a policy file, and then at the important ELEMENTS node.

Root and First-Level Nodes

As you can see in Listing 9-1, the following are the root and first-level nodes in a policy file:

<TDL>
  <DEFAULTSETTINGS></DEFAULTSETTINGS>
  <ELEMENTS></ELEMENTS>
  <CATEGORIES></CATEGORIES>
  <FEATURES></FEATURES>
</TDL>

The following sections describe these nodes, taking them in the order in which they generally appear in a policy file.

TDL Root Node
The TDL root node is the only node with an attribute, which is the xmlns attribute. This attribute specifies the namespace for the policy file. In the prebuilt DAP.tdl policy file, the attribute is set to http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema. You should use this value in all of your policy files. This way, you can use an XML editor for minimal validation, as well as tag or node completion (automatically inserting the closing tag after you've typed in the opening tag).

The TDL start tag node should generally always look like this:

<TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">

The TDL end tag should always look like this:

</TDL>

DEFAULTSETTINGS Node

The DEFAULTSETTINGS node is the only first-level node that is required. It is used for globally specifying the default behaviors of the items in the policy file. Setting the default behaviors in the DEFAULTSETTINGS node is an excellent way of avoiding repeated information in your policy file. This means that you should specify the default behavior that will fit most items in your policy file, and then override the default setting for these nodes where appropriate.

The DEFAULTSETTINGS node and its child nodes look like this:

<DEFAULTSETTINGS>
<DEFAULTACTION></DEFAULTACTION>
<ORDER></ORDER>
<POLICYMODE></POLICYMODE>
<CONSTRAINTS></CONSTRAINTS>
</DEFAULTSETTINGS>

Only the CONSTRAINTS node is optional. The child nodes work as follows:

DEFAULTACTION: This node specifies if an item is included or excluded by default.
ORDER: This node specifies in which order include and exclude actions are taken. It has meaning only if an item is specified more than once. This happens when the policies are applied in an ELEMENTSET node, and you must specify INCLUDEEXCLUDE or EXCLUDEINCLUDE as the value for this node.
POLICYMODE: This node specifies how unidentified items (items that haven't been specified with an ELEMENT node) are handled. The POLICYMODE node works in conjunction with the DEFAULTACTION node for restricting elements, and you must specify PERMISSIVE or RESTRICTIVE as the value for this node. (See Table 9-1.)
CONSTRAINTS: This node serves as a container, and it can hold context-based constraints for menus, menu items, properties, and toolbox items.

The settings in the DEFAULTSETTINGS node can be overridden in an ELEMENTSET node, which is described in the upcoming section about the ELEMENT node.

NOTE: You can create a policy file using a standard text editor or an XML editor like the one in the VS .NET IDE, and add the nodes referenced in the sections as we go along. However, the next few sections are intended as introductory material. You'll get to create a policy file in the "Creating and Editing Policy Files" section later in this chapter.

NOTE: The associated items referred to in Table 9-1 are items that are linked with a particular ELEMENT node, such as menus or menu items (MENULINK nodes).

ELEMENTS Node
The ELEMENTS node is a container in which you place all the ELEMENT nodes (discussed in the "ELEMENT Node" section) in a single policy file. If an ELEMENT node that is referenced elsewhere in the policy file hasn't been defined in the ELEMENTS node, it will be handled as an unidentified item.

CATEGORIES Node
The CATEGORIES node is a container in which you place all the CATEGORY nodes in a single policy file. The CATEGORY node is used for grouping two or more ELEMENT nodes, or even other CATEGORY nodes. Therefore, when you refer to the same group of ELEMENT nodes more than once in your policy file, consider defining a CATEGORY node in the CATEGORIES node, for easy reference elsewhere in your policy file.

FEATURES Node
The FEATURES node is a container for menu and toolbox items that you want to govern in your policy file. If you specifically want to enable or disable a menu or toolbox item, you must define it in the MENUS or TOOLBOXITEMS nodes, which are child nodes of the FEATURES node.

ELEMENT Node

The ELEMENT node isn't a first-level node in the TDL schema, but it's probably the most important one. The ELEMENT node is the fundamental building block of a policy file, because it specifies a particular enterprise template project item or element for which you define a policy.

The ELEMENT node describes a single item in an enterprise template project. If you reference an element in your policy file that hasn't been specified with an ELEMENT node, it's called an unidentified element.

The ELEMENT node and its child nodes look like this:

<ELEMENT>
  <ID></ID>
  <CONTEXT></CONTEXT>
  <IDENTIFIERS></IDENTIFIERS>
  <ELEMENTSET></ELEMENTSET>
  <CONSTRAINTS></CONSTRAINTS>
  <PROTOTYPES></PROTOTYPES>
  <FEATURELINKS></FEATURELINKS>
  </ELEMENT>

Only the ID node is required. The child nodes work as follows:

ID: This node is the unique identifier that is used to reference the node from elsewhere in the policy file.
CONTEXT: This node is used for displaying related help topics in the Dynamic Help window when the ELEMENT you're defining is selected within the VS .NET IDE. This subject is covered in detail in Chapter 10.
IDENTIFIERS: This node is a container node for zero or more IDENTIFIER nodes. This isn't the same as the ID node, which is used for referencing the ELEMENT elsewhere in the policy file. It's an identifier the VS .NET shell uses for identifying a more or less unique item, such as a project item. One of the child nodes of the IDENTIFIER node is the TYPE node, which determines the type of item, such as CODE or PROJECT .
ELEMENTSET: This node is used for referencing other ELEMENT or CATEGORY nodes that can be child items of the item being defined. The ELEMENTSET can also be used for defining constraints for the entire ELEMENT in which it is contained or a single member of the ELEMENTSET .
CONSTRAINTS: This node is used for specifying constraints for the item defined by the ELEMENT node. These constraints are specific to the element, meaning they apply when the element is selected within the VS .NET IDE. You can apply constraints to menus, menu items, properties, and toolbox items.
PROTOTYPES: This node is a container for zero or more PROTOTYPE nodes. Each PROTOTYPE node references the path and file name of an initial VS .NET project or prototype. Therefore, you use the PROTOTYPE node in cases where you have a prototype for the developers to build on.
FEATURELINKS: This node is a container for menu and toolbox item links. You add these child node links to the FEATURELINKS node in order to associate the linked items with the ELEMENT node in which FEATURELINKS is defined. This way, you enable or disable the items listed in the FEATURELINKS node, depending on whether the ELEMENT node is included or excluded. Basically, the FEATURELINKS node is there to save you the hassle of doing a lot of manual work.

In the next section, you'll see how the ELEMENT and other policy file nodes work together.

CREATING AND EDITING POLICY FILES

This section will take you through creating a policy file from scratch. In general, we recommend that you start with a copy of the DAP.tdl file and edit it to suit your needs, but creating a policy file from scratch will give you a better understanding of how the policy file works. You'll see how to create the basic policy file skeleton and specify the default behaviors. Once you know how to build a policy file, you'll be able to edit existing policy files.

If a policy file is associated with an enterprise template project that has been used to create a new enterprise solution, and this solution is currently open, the policy file is said to be in use. However, you can make changes to such a policy file, and sometimes this comes in handy, depending on what kind of changes you want to make. When a solution associated with a policy file is opened in the VS .NET IDE, VS .NET loads the entire policy file into memory, effectively caching it for as long as the solution is open. This means that if you make changes to an associated policy file when the solution is open, you must close the solution and reopen it in the IDE for the changes to be applied.

Choosing an Editor

You can create and edit your policy files in any text-based editor, such as Notepad. However, because a policy file is expressed using the XML-based TDL, working in an XML editor offers advantages. Statement completion and other "smart" features will save you a fair bit of typing and reduce the possibility of errors. VS .NET comes with a built-in XML editor (or designer, as Microsoft has chosen to call it), as shown in Figure 9-3.

Creating a Policy File Skeleton

When you're creating a policy file from scratch, you need to start by creating an empty text file with a .tdl extension (such as NewEnterprisePolicy.tdl) in the \Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder.

If you want to use the VS .NET XML Designer without adding your policy file to a project, you can begin by creating an empty text file with a .tdl extension and placing it in the mentioned Policy folder. After creating the empty policy file, you can double-click it to open it in the VS .NET XML Designer.

Your other option is to create the file in VS .NET. Open the New File dialog box (by pressing Ctrl-N or selecting File -> New -> File) and choose the XML file template, as shown in Figure 9-4.

That creates a new XML file named XMLFile1, as shown in Figure 9-5, with the standard XML header. You should now delete the XML header/declaration and save the blank XMLFile1 file with a .tdl extension in the \Program Files\ Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Policy folder. (We know it's not good practice to create XML files without an XML declaration, but you'll be adding one soon.)

The first node you need to add is the TDL node, because it is this root node that signals the type of file to VS .NET.

In Exercise 9-1, you'll start creating a policy file skeleton with the TDL node. You'll also associate the policy file with an enterprise template project, so that you will be able to check what happens in the VS .NET IDE when you use a solution based on an enterprise template project with a policy file.

NOTE: In the exercises in this chapter, you'll be using the NewTemplateProject.etp enterprise template project file created in the previous chapter. If you didn't follow the exercises in Chapter 8, you can find a copy of this file in the Chapter 08 folder of the accompanying sample code, available from the Downloads section of the Apress Web site (http://www.apress.com). You can copy the required files from the subfolders in Chapter 08\Program Files\Microsoft Visual Studio .NET 2003\EnterpriseFrameworks to the corresponding subfolders in the \Program Files\Microsoft Visual Studio .NET 2003\ EnterpriseFrameworks folder.

EXERCISE 9-1

Create an empty text file named NewEnterprisePolicy.tdl, and place it in the \Program Files\Microsoft Visual Studio .NET 2003\ EnterpriseFrameworks\Policy folder. You can use either the VS .NET XML Designer or the VS .NET New File dialog box to create this file, as described in the text preceding this exercise.

Add the TDL node to the NewEnterprisePolicy.tdl file, making it look like this:

<TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">
</TDL>

To associate the newly created policy file, NewEnterprisePolicy.tdl, with the enterprise project file from Chapter 8, NewTemplateProject.etp, open the NewTemplateProject.etp file (located in \Program Files\ Microsoft Visual Studio .NET 2003\EnterpriseFrameworks\Projects\ NewTemplateProject) in Notepad and add the following text just before the closing EFPROJECT tag:
```
<GLOBALS>
  <GLOBALENTRY>
    <NAME>TDLFILE</NAME>
    <VALUE>NewEnterprisePolicy.tdl</VALUE>
  </GLOBALENTRY>
</GLOBALS>
```
Save the enterprise template project file, and then close Notepad.

Another way to associate a policy file with an enterprise template project is to open the .etp file in the VS .NET IDE, select the enterprise project file in the Solution Explorer, and click the ellipsis button (') in the Properties window, as shown in Figure 9-6.

If you try to create a new project from the enterprise template project file with the policy file in its current state, you will get an error, like the one shown in Figure 9-7, because you're missing some of the required elements or nodes. Don't worry about it for now'we will add the necessary components in the coming sections.

Specifying Global Default Behaviors

As explained earlier in the chapter, the DEFAULTSETTINGS first-level node is used for globally specifying default behaviors for the items in an enterprise template project. Therefore, you add the first-level DEFAULTSETTINGS node as a child node to the TDL root node. After this, you need to consider how you want to handle identified items (those that have been specified as an ELEMENT node) and unidentified items, meaning including or excluding items by default, and if you want to constrain any menu items, toolbox items, or properties. You do this by using the child nodes of DEFAULTSETTINGS: DEFAULTACTION, POLICYMODE, ORDER, and CONSTRAINTS.

In Exercise 9-2, you will add the DEFAULTSETTINGS node to your policy file skeleton.

EXERCISE 9-2

Open the NewEnterprisePolicy.tdl you created in Exercise 9-1.

Add the DEFAULTSETTINGS node to the NewEnterprisePolicy.tdl file, making it look like this:

<TDL xmlns="http://www.microsoft.com/schema/EnterpriseTemplates/TDLSchema">
  <DEFAULTSETTINGS>
  </DEFAULTSETTINGS>
</TDL>

Page: 1, 2, 3, 4, 5

<< Previous Page Next Page >>

Rate this: