Windows Server 2008 and Windows Vista : Creating Custom ADMX and ADML Files (part 4) - Using ADMX File Language

7. Using ADMX File Language

The ADMX file language is similar to that of the .adm template, with just a few oddities.

Table 5. ADMX and ADML File Element Syntax

ADMX File Data Type	ADML File Parameter Definition
additive Attribute	A Boolean value. If true, the existing subkeys are not deleted, and the values set in the list box are appended to the existing subkeys. If false, the existing subkeys are deleted and the values in the list box replace the existing subkeys.
annotation Element	Adds a localized comment at the beginning of the .adml file.
boolean Element	Sets a value based on the true and false cases in a policy setting. It is generally associated with checkBox parameters in the GPME.
category Element	Specifies the name of a unique category to be displayed in the GPME.
categories Element	A table of category elements.
checkBox Element	Represents a check box parameter. It must be associated with a boolean element defined in the elements element.
class Attribute	Identifies whether the policy setting will be located under a single node of the GPME (computer or user) or both nodes. This is defined in the .admx file.
clientExtension Attribute	Defines the client-side extension that will process, on the client computer, the particular settings represented by the boolean, decimal, text, enum, or list element.
comboBox Element	Represents a combo box parameter. It must be associated with a text element defined in the elements element.
decimal Element (elements)	Sets the registry value to the specified numeric value when a policy setting is enabled through the GPME. It determines whether the registry key will be created as a REG_DWORD or REG_SZ when storing the numeric value.
decimal Element (value)	Sets a value to an unsigned integer decimal value.
decimal TextBox Element	Represents a text box with or without a spin box control for entering decimal numbers as a policy setting parameter. It must be associated with a decimal element defined in the elements element.
default Element	A localized default displayed when the combo box parameter is active.
defaultChecked Element	A Boolean value. If true, the check box parameter is displayed as selected; otherwise, the check box parameter is displayed as cleared.
defaultItem Element	The numerical value that identifies the default choice from the items in the drop-down list. The item list is numbered starting from 0.
defaultKey Attribute	Specifies a default registry subkey for all items in the enabledList element, disabledList element, or valueList element.
defaultValue Attribute	Specifies the default numerical value of the parameter. If not specified, the defaultValue attribute is set to 1.
defaultValue Element	A localized string that is initially displayed in the text box parameter when the policy setting is enabled.
definition Element	Creates the mapping between the logical name to an existing reference supported on string text in the .adml file.
definitions Element	A table of definition elements for the supportedOn text.
delete Element	Represents a deleted registry value or key.
description Element	The localized description of policy settings contained in the .adml file.
disabledList Element	Sets the multiple registry values when a policy setting is disabled through the GPME.
disabledValue Element	Sets the registry value when a policy setting is disabled through the GPME.
displayName Attribute	A string value referenced in the .adml file. This attribute can be used in the category, definition, enum, or policy element. This is defined in the .admx file.
displayName Element	The localized friendly name of the .adml file.
dropdownList Element	Represents a drop-down list parameter. It must be associated with an enum element defined in the elements element.
elements Element	Represents the types of optional parameters defined in a policy setting. The child elements for the elements element represent these optional parameters available for a policy setting.
enabledList Element	Sets the multiple registry values when a policy setting is enabled through the GPME.
enabledValue Element	Sets the registry value when a policy setting is enabled through the GPME.
enum Element	Sets the specified registry subkey to a specified value or a list of registry subkeys to values chosen from a drop-down list when a policy setting is enabled through the GPME.
expandable Attribute	A Boolean value. If true, the registry subkey value will be created as an expandable string type (REG_EXPAND_SZ); otherwise, the registry subkey value will be created as a string type (REG_SZ).
explainText Attribute	A string value referenced in the .adml file representing Help or Explain text for either a category or policy setting. This is defined in the .admx file.
explicitValue Attribute	A Boolean value. If true, the user must specify the registry subkey name and the registry subkey value. The list box shows two columns, one for the name and one for the data. If false, the user specifies only the registry subkey value. The registry subkey name is created automatically.
fallbackCulture Attribute	Specifies the default language to use when the .adml file does not exist on the machine or ADMX central store for the required language.
falseList Element	Sets the multiple registry values when a boolean element is set to the false state.
falseValue Element	Sets the registry value for the false condition of a boolean element.
fileName Attribute	Specifies a valid file name.
id Attribute	Specifies a string used as a logical name for an element.
item Element	Represents a singe registry entry and its value.
item Element (enum)	A child element of the enum element, representing a display name associated with a single value or a single value with a set of registry subkey values.
key Attribute	Specifies a string that represents the name of the registry subkey.
keywords Element	A list of searchable keywords associated with categories and policy settings.
label Element	A localized string label for the text box parameter.
list Element	Sets a list of registry subkeys when a policy setting is enabled through the GPME. It is generally associated with a show box parameter in the GPME.
listBox Element	Represents a list parameter. It must be associated with a list element defined in the elements element.
maxLength Attribute	Specifies the maximum number of text characters for a text element. The default value is 1023.
maxValue Attribute	Specifies the maximum value for a decimal element. The default value is 9999.
minRequiredRevision Attribute	Determines the minimum version of the .adml file that will interoperate with the .admx file. It is an attribute of the .admx resources element.
minValue Attribute	Specifies the minimum value for a decimal element. The default value is 0.
name Attribute	A logical or friendly name used as a mapping to a string value referenced in the .adml file. This attribute can be used in the category, definition, or policy element.
nameSpace Attribute	Specifies the URI used to identify the elements within an ADMX file.
noSort Attribute	A Boolean value. If true, display the suggested values in the defined order of the suggestion elements; otherwise, sort the suggested values in alphabetical or numerical order.
parentCategory Element	Specifies the location of the category in relationship to its parent category in the GPME tree structure.
policy Element	Corresponds to a single Group Policy setting displayed in the GPME. It describes all of the information about the policy setting but includes a reference to the parameter definition.
policyDefinitionResources Element	The document element for an .adml file that defines all the localized resource information with a single language or culture per file for each supported language or culture setting. It also declares a default namespace for all of the elements in the .adml file.
policyDefinitions Element	The document element for an .admx file that defines a set of registry-policy settings. It also declares a default namespace for all of the elements in the .admx file.
policyNamespaces Element	Defines the unique name for the policy namespace in an ADMX file as well as any namespaces it references in other ADMX files.
policies Element	A table of policy elements.
prefix Attribute	Specifies the logical name that refers to the namespace within the current or referenced ADMX file.
presentation Attribute	A presentation value referenced in the .adml file representing the localized portions of a policy setting parameter. This is defined in the .admx file.
presentation Element	Corresponds to the parameters for a single Group Policy setting displayed in the GPME.
presentationTable Element	A table of presentation elements representing the layout of parameter controls for individual Group Policy settings. The layout of parameter controls includes: type of parameter entry mechanism (edit box, spin box, drop-down list, list box, show box, and combo box), labels and prompt text for the parameter entry, and the default and range values for each parameter entry.
ref Attribute	References a logical name for the parent category.
refId Attribute	Specifies a string used as a logical name. This attribute allows an element from the .admx file to refer to an element in the .adml file.
required Attribute	Specifies a Boolean value that represents whether a value must be specified for the parameter.
resources Element (.adml)	Contains the stringTable and presentationTable elements for specific MUI languages. This is located in the .adml file.
resources Element (.admx)	Specifies the minimum revision level of the matching .adml file and, optionally, the fallback language to use. This is located in the .admx file.
revision Attribute	Provides a method of tracking changes made to the .admx or .adml file.
schemaVersion Attribute	Specifies the ADMX schema version that the .admx and .adml files conform to.
seeAlso Element	A descriptive phrase that can be used to reference related categories or policy settings.
soft Attribute	A Boolean value. If true, a registry value will not overwrite a previously set value; otherwise, registry values will always be saved.
spin Attribute	A Boolean value. If true, a spin box control is created in addition to the numeric text box; otherwise, a numeric text box is created.
spinStep Attribute	Specifies the increment of change for the spin box control. If not specified, it is set to 1.
storeAsText Attribute	A Boolean value. If true, the decimal element will store the decimal value as a REG_SZ registry value; otherwise, as a REG_DWORD.
string Element (.adml)	Represents a localized display string.
string Element (.admx)	Sets a value to string text.
stringTable Element	Contains the display strings for the following types of information: Group Policy setting title Explain text SupportedOn text Category names and Explain text Parameter labels
suggestion Element	A localized string displayed as a drop-down choice of the combo box parameter.
supersededAdm Element	References an .adm template to be replaced by an ADMX file. GPME will not read any .adm template designated as superseded.
supportedOn Element	Provides a mapping of products to definitions.
supportedOn Element (policy)	Provides a mapping of products to policy setting definitions.
target Element	Provides the mapping of a logical or friendly name to a unique URI name representing a policy namespace.
text Element	Sets the specified registry value to a specified text input value when a policy setting is enabled through the GPME.
text Element (presentation)	A localized string displayed within the parameter box by the GPME, used within the presentation element.
textbox Element	Represents a text box parameter. It must be associated with a text element defined in the elements element.
trueList Element	Sets the multiple registry values when a boolean element is set to the true state.
trueValue Element	Sets the registry value for the true condition of a boolean element.
using Element	Provides the mapping of the logical name to a unique URI name of a previously defined policy namespace located in a different ADMX file. This is an optional element with no limit to the maximum number of using elements that can be declared in a policyNamespaces element.
value Attribute	Specifies the numerical value for the decimal element.
value Element	Represents the actions to delete a registry subkey or set the value of the registry subkey to a decimal or string value.
valueList Element	Sets the multiple registry values within the item element when defined as a child of the enum element.
valueName Attribute	Specifies a string that contains the name for a registry entry.
valuePrefix Attribute	Specifies the text string that will be prepended to an incremented integer. The combined text string and integer will create the registry subkey used in setting policy values.
XML declaration	Specify that this is an XML document. All ADMX files may start with the XML declaration. The XML declaration is not considered to be part of the ADMX document. However, it is good practice to start the ADMX file with the XML declaration to specify that this is an XML document.
xmlns Attribute	Specifies the default namespace for all elements in either the .admx or .adml file.

Table 5 provides a summary of all of the elements available for use in both the ADMX and ADML files. For a more in-depth view of the ADMX and ADML file syntax, refer to the syntax reference guide on the resource CD, which describes in detail each element that can be used in these files.

Registry-Based Policy Settings: Three Options

You have three options for creating custom registry-based entries through Group Policy. Each option has advantages, but some advantages might be more helpful than others. Of course, there are disadvantages too.

The first option is to use the legacy .adm template. The technology and syntax within the .adm template is known and familiar, and the template is easy to import. However, files can get quite large, and they are stored in the GPT of the GPO. This causes a size increase in the GPT, and therefore in the SYSVOL.

The second option is to use ADMX files. These files and their structure are not readily familiar, but because they are based on XML, that should not be an issue. Creation of ADMX files involves some extra work because there are two files: ADMX and ADML. However, this is actually a benefit, because it provides the language neutrality that the .adm templates do not possess. Because ADMX files can take advantage of the central store, there is no SYSVOL bloat, no need to manage the versioning, and no thread of using errant versions of the files.

A final option for customizing registry-based entries in a GPO is to use the Registry policy under the Preferences node. This option has a few major benefits. First, there is absolutely no scripting or coding required. Also, the registry path is easy to find and document—you simply browse for it in the interface through the GPME. Another benefit is that these settings can be flagged to behave more like a policy than a preference, with the option to remove the policy when it no longer applies. Finally, with the targeting capabilities of the preferences, the registry-based entry can be dynamic, based on any of the available criteria.