Partager via

Creating a Custom Base ADMX File

  • Article

Applies To: Windows Server 2008

If your organization plans on creating a number of .admx files to display under a single category node in the Local Group Policy Editor or Group Policy Management Console, you will need to build a custom base file. A single custom base file with predefined categories and supported on text can be referenced by multiple .admx files. This section provides information about creating and referencing the definitions in the custom base file.

Creating the custom base file

To discuss creating a custom base file, we will use the example of a company named Contoso, Ltd., that expects to create a number of different .admx files. They might want all of their policy settings from all of the files to be placed under one central category node in the Local Group Policy Editor or GPMC called "contoso." For the simplest case, the Contoso, Ltd., administrators could choose to create a custom base .admx file for defining this central category.

At its simplest, the .admx file for defining a central category called, "contoso," could look like the following.

<?xml version="1.0" encoding="utf-8"?>
<policyDefinitions xmlns:xsd="https://www.w3.org/2001/XMLSchema"
  xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
  revision="1.0" schemaVersion="1.0" 
  xmlns=
  "https://schemas.microsoft.com/GroupPolicy/2006/07/PolicyDefinitions">
  <policyNamespaces>
    <target prefix="contoso" namespace="Contoso.Policies.Contoso" />
  </policyNamespaces>
  <resources minRequiredRevision="1.0" />
  <categories>
    <category name="ContosoCompany"
              displayName="$(string.ContosoCompany)"
              explainText="$(string.ContosoCompany_Help)" />
  </categories>
</policyDefinitions>

The corresponding .adml file would provide the localized display string for the central category. This file could look like the following.

<?xml version="1.0" encoding="utf-8"?>
<policyDefinitionResources xmlns:xsd="https://www.w3.org/2001/XMLSchema"
   xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
   xmlns=
   "https://schemas.microsoft.com/GroupPolicy/2006/07/PolicyDefinitions"
   revision="1.0" schemaVersion="1.0">
  <displayName>Contoso Company base file</displayName>
  <description>This file contains the Contoso parent category.
  </description>
  <resources>
    <stringTable>
      <string id="ContosoCompany">Contoso</string>
      <string id="ContosoCompany_Help">Contains Contoso company specific configuration settings.</string>
    </stringTable>
  </resources>
</policyDefinitionResources>

Referring to the custom base file

The Contoso custom base file is referred to using the unique namespace, Contoso.Policies.Contoso. The namespace string is case sensitive.

To refer to the Contoso base file, include the using attribute in your policyNamespaces element. The namespace attribute must match the defined namespace from the custom base file. The prefix attribute can be any name that is unique within your .admx file. It is recommended you use the prefix attribute string from the custom base file when possible, in order to avoid confusion.

For example, this XML fragment from the example2.admx file both defines its namespace and refers to the Contoso Base file within the policyNamespaces element.

<policyNamespaces>
  <target prefix="example2" namespace="Microsoft.Policies.Example2" />
  <using prefix="contoso" namespace="Contoso.Policies.Contoso" />
</policyNamespaces>

Warning

When creating a custom base file, you must take care that all administrators referring to this base file will have this file on their administrative machines. Or you can use the central store to guarantee all administrators will have use of the custom base file.

Referencing custom category elements

You can display your category node or a policy setting under a single company node of the Local Group Policy Editor or the GPMC. To accomplish this, you reference the category elements in the custom base file. Custom base file category elements can be used as the parentCategory element for any category or policy element within your .admx file. If you define the category element name within your own .admx file instead of referencing the custom base file, the Local Group Policy Editor or GPMC will display a duplicate node. This happens because a category element defined in a different namespace is evaluated as a unique element by the Local Group Policy Editor or GPMC. Because each .admx file is created in a unique namespace, this will result in duplicate nodes.

To place your category node under the example Contoso node from the custom base file created in our example, add the "contoso:" prefix to the ref attribute of the parentCategory element.

This XML fragment demonstrates placing your sample category under the parentCategory, based on the Contoso component node in the Local Group Policy Editor or GPMC.

    <category name="SAMPLE" displayName="$(string.SAMPLE)"
                    explainText="$(string.SAMPLEHELP)">  
       <parentCategory ref="contoso:ContosoCompany" />
    </category>

This XML fragment demonstrates placing your sample policy setting under the parentCategory, based on the Contoso node in the Local Group Policy Editor or GPMC.

    <policy name="Sample_NoParamPolicy" class="Both"
               displayName="$(string.Sample_NoParamPolicy)"
               explainText="$(string.Sample_NoParamPolicy_Help)"
               key="Software\Policies\Examples"
               valueName="Example1NoParam">
      <parentCategory ref="contoso:ContosoCompany" />
      <supportedOn ref="SUPPORTED_ProductOnly" />
      <enabledValue>
         <decimal value="1" />
      </enabledValue>
      <disabledValue>
         <decimal value="0" />
      </disabledValue>
    </policy>