Platform extensibility - Part 2

Article
06/18/2009

In my previous blog post on platform extensibility, I introduced you to the data-driven nature of the property pages UI. I explained how a collection of xml files drives the UI but stopped short of describing the contents of these files. I'll continue from where I stopped in that post and describe the format of one such xml file so that you have enough information to confidently author your own. The contents of this post will also come in handy when I discuss Build Customizations in my upcoming post.

To recall, every top level node under Configuration Properties in the property pages UI (such as C/C++, Linker, etc) is called a Rule. Each Rule generally has multiple Category nodes under it and each Category node houses a bunch of properties, frequently displayed as a property grid on the right pane in the UI. Underlying every Rule, there is an xml file from which the UI sources its data and some rendering information. This xml file represents a UI-independent data model for a Rule and its properties, although as we will see a few very common UI terms do make their way into this file.

I'll use the %ProgramFiles%\MSBuild\Microsoft.Cpp\v4.0\cl.xml file to realize my goal for this post. You may want to open it in notepad or, to get the nice color formatting, in VS. The first thing to know about this xml file is that it is in the XAML format. At this stage, XAML is just a convenient xml format to express information and has no other significance. The property page UI is built using WinForms and not WPF, hence we do not utilize the XAML-driven WPF architecture although that is the direction we would like to head in the future.

If you stripped cl.xml of all data, you will end up with the following skeleton:

<?xml version="1.0" encoding="utf-8"?>

<Rule>

<Rule.DataSource />

<Rule.Categories>

...

</Rule.Categories>

...

</Rule>

In other words, a property page xml generally contains a Rule declaration which in turn includes the declarations for a bunch of categories, a data source and most importantly a collection of properties of various types. The snippet above shows the five possible types a property can have. In what follows, we will explain each of these major elements while showing some of the metadata that can be attached to them.

1. Rule: Rule is generally the lone root node in the xml file. A Rule can have many attributes defined on it. The following snippet from cl.xml shows many of them.

<Rule Name="CL" PageTemplate="tool" SwitchPrefix="/" Order="10"

xmlns="https://schemas.microsoft.com/build/2009/properties"

xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"

xmlns:sys="clr-namespace:System;assembly=mscorlib">

<Rule.DisplayName>

<sys:String>C/C++</sys:String>

</Rule.DisplayName>

I'll briefly describe the attributes you see above:

a. Name: The Name attribute is an id for the Rule. It needs to be unique among all the property page xml files for a project.

b. PageTemplate: The value of this attribute is used by the UI to choose from a collection of UI templates. The "tool" template renders the properties in a standard grid format. Other in-built values for this attribute are "debugger" and "generic". See the Debugging node and General node, respectively, to see the UI format resulting from specifying these values. The UI for "debugger" page template uses a drop-down box to switch between the properties of different debuggers whereas the "generic" template displays different property categories all in one page as opposed to having multiple category sub-nodes under the Rule node. This attribute is just a suggestion to the UI; the xml file is designed to be UI independent. So, a different UI could use this attribute for different purposes.

c. SwitchPrefix: This is the prefix used in the command line for the switches. A value of "/" would result in switches that look like /ZI, /nologo, /W3, etc.

d. Order: This is a suggestion to a prospective UI client on the relative location of this Rule compared to all other Rules in the system.

e. The namespaces: This is a standard XAML element. You can see three namespaces listed. These correspond to the namespaces for the XAML deserialization classes, XAML schema and system namespace, respectively.

f. DisplayName: This is the name that is shown on the property page UI for the Rule node. This value is localized. We created DisplayName as a child element of Rule rather than as an attribute (like Name or SwitchPrefix) because of internal localization tool requirements. From XAML's perspective, both are equivalent. So, you can just make it an attribute to reduce clutter or leave it as it is.

g. DataSource: This is a very important property that tells the project system the location from which the property value should read from and written to, and its grouping (explained below). For cl.xml, we have

Persistence="ProjectFile" tells the project system that all properties for the Rule should be written to the project file or the property sheet file (depending on which node was used to spawn the property pages). The other possible value is "UserFile" which will write the value to the .user file.

ItemType="ClCompile" says that the properties will be stored as ItemDefinition metadata or item metadata (the latter only if the property pages were spawned from a file node in solution explorer) of this item type. If this field is not set, then the property is written as a common property in a PropertyGroup.

Label="" indicates that when the properties are written as ItemDefinition metadata, the label of the parent ItemDefinitionGroup will be empty (every MSBuild element can have a Label). In VS 2010 we use labeled groups to delineate the VC++ project file. I'll go over the ordered layout design of the .vcxproj file in a later post. Getting back to the Label attribute, note that the groups housing most Rule properties do not have a label (or in other words, they have the empty string as the label).

HasConfigurationCondition="true" tells the project system to affix a configuration condition to the value so that it takes effect only for the current project configuration (the condition could be affixed to the parent group or the value itself). E.g. open the property pages off the project node and set the value of the property Treat Warnings As Error under Configuration Properties > C/C++ > General to Yes. The following value is written to the project file. Notice the configuration condition attached to the parent ItemDefinitionGroup.

</ClCompile>

</ItemDefinitionGroup>

If this value were set in the property pages spawned off a file, say stdafx.cpp, then we would have the property written under the stdafx.cpp item in the project file as shown below. Notice how the configuration condition is directly attached to the metadata itself.

</ClCompile>

</ItemGroup>

Another attribute of DataSource not listed above is PersistedName. If you wish to represent a property in the project file using a different name, this attribute will hold that different name. By default this attribute is set to the property's Name since most properties are likely to be stored as themselves in the project files.

I'll end the description of the DataSource attribute by mentioning that an individual property can override its parent Rule's DataSource to point to a different data source. In that case, the location for that particular property's value will be different from other properties in the Rule.

There are other attributes of a Rule such as Description, SupportsFileBatching, etc that are not shown here. The full set of attributes applicable to a Rule or on any other element can be obtained by browsing the msdn documentation for these types (currently, the descriptions included in these pages are sparse, but they should be accrue over time). Alternately, they can be gleaned by examining the public properties on the types in the Microsoft.Build.Framework.XamlTypes namespace living in the Microsoft.Build.Framework .dll assembly (you can use ildasm.exe for this purpose if you wish).

DisplayName, PageTemplate, Order are few UI related properties that are present in this otherwise UI-independent data model. That is fine since these are not tied to a particular UI technology. Further, these are almost certain to be used by any UI that is used to display the property pages.

DisplayName and Description are two properties that are present on almost all elements in the xml file. And these are the only two properties that are localized (localization of these strings will be explained in a later post).

2. Category: A Rule can have multiple Categories. The order in which the categories are listed in the xml file is a suggestion to the UI to display the categories in the same order. E.g. the order of the categories under the C/C++ node as seen in the UI - General, Optimization, Preprocessor, ... - is the same as that in cl.xml. A sample category looks like this:

<Category.DisplayName>

<sys:String>Optimization</sys:String>

</Category.DisplayName>

</Category>

The above snippet shows the Name and DisplayName attributes that have been described before. Once again, there are other attributes a Category can have that are not used above. You can know about them by reading the documentation or by examining the assemblies using ildasm.exe.

3. Properties: This is the meat of the xml file and contains the list of all properties in this Rule. Each property can be one of five possible types shown in the XAML skeleton above. Of course, you could have only a few of those types in your file. A property has a number of attributes that allow it to be described richly. I'll explain only the StringProperty here. The rest are very similar.

<StringProperty.DisplayName>

<sys:String>Object File Name</sys:String>

</StringProperty.DisplayName>

<StringProperty.Description>

<sys:String>Specifies a name to override the default object file name; can be file or directory name.(/Fo[name])</sys:String>

</StringProperty.Description>

</StringProperty>

Most of the attributes in the snippet have been described before. The new ones are Subtype, Category and Switch.

a. Subtype: Subtype is an attribute available only for StringProperty and StringListProperty; the rest of the attributes described below are applicable to any type of property. Subtype gives contextual information on this property. E.g. the value of "file" indicates that not only is this property a string, but it also represents a file path. Such contextual information can be and is used to enhance the editing experience by providing a windows explorer as the property's editor that allows the user to choose the file visually rather than type its path (which is still possible).

b. Category: This declares the category under which this property falls. Try to find this property under the Output Files category in the UI.

c. Switch: When a Rule represents a tool - such as the compiler tool in this case - most properties of the Rule are passed as switches to the tool executable during build time. The value of this attribute indicates the switch literal to be used. The property above specifies that its switch should be Fo. Combined with the SwitchPrefix attribute on the parent Rule, this property is passed to the executable as /Fo"Debug\" (visible in the command line for C/C++ in the property page UI).

I would like to mention a few other attributes for a property that are not illustrated here. These are:

d. Visible: If for some reason, you don't want your property to show up in the property pages (but probably still available during build time), set this attribute to false.

e. ReadOnly: If you want to provide a read-only view of this property's value in the property pages, set this attribute to true.

f. IncludeInCommandLine: Some properties may not need to be passed to a tool during build time. Setting this attribute to false will prevent it from being passed.

I hope the above description of the format of a property page XAML file has given you enough details to help you write one of your own.

Platform extensibility - Part 2

Additional resources