Group Policy ADMX Syntax Reference
Guide
Microsoft Corporation
Published: May 2007
Author: Judith Herman
Editor: Craig Liebendorfer
Abstract
This reference document describes the new Group Policy ADMX format. The intent of
this document is to teach you how to create .admx and .adml files for custom Group
Policy administrative template settings.
This document supports a preliminary release of a software product that may be changed
substantially prior to final commercial release. This document is provided for
informational purposes only and Microsoft makes no warranties, either express or
implied, in this document. Information in this document, including URL and other Internet
Web site references, is subject to change without notice. The entire risk of the use or the
results from the use of this document remains with the user. Unless otherwise noted, the
example companies, organizations, products, domain names, e-mail addresses, logos,
people, places, and events depicted herein are fictitious, and no association with any real
company, organization, product, domain name, e-mail address, logo, person, place, or
event is intended or should be inferred. Complying with all applicable copyright laws is
the responsibility of the user. Without limiting the rights under copyright, no part of this
document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying,
recording, or otherwise), or for any purpose, without the express written permission of
Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other
intellectual property rights covering subject matter in this document. Except as expressly
provided in any written license agreement from Microsoft, the furnishing of this document
does not give you any license to these patents, trademarks, copyrights, or other
intellectual property.
© 2007 Microsoft Corporation. All rights reserved.
Microsoft, SQL Server, Windows Vista, Windows, and Windows Server are either
registered trademarks or trademarks of Microsoft Corporation in the United States and/or
other countries.
The names of actual companies and products mentioned herein may be the trademarks
of their respective owners.
Contents
Group Policy ADMX Syntax Reference Guide .................................................................. 21
How to read this document ............................................................................................ 21
ADMX Prerequisites .......................................................................................................... 22
ADMX Schema.................................................................................................................. 22
.admx and .adml File Structure ......................................................................................... 22
Language-neutral file (.admx) structure......................................................................... 23
Language resource file (.adml) structure ....................................................................... 24
Best Practices for Authoring ADMX Files ......................................................................... 25
Referencing the Windows Base ADMX File...................................................................... 26
Referring to the Windows base file ................................................................................ 26
Referencing Windows category elements ..................................................................... 27
Referencing Windows supportedOn elements .............................................................. 28
Creating a Custom Base ADMX File ................................................................................. 28
Creating the custom base file ........................................................................................ 29
Referring to the custom base file ................................................................................... 30
Referencing custom category elements ........................................................................ 30
Associating .admx and .adml Parameter Information ....................................................... 31
Referencing the presentation element........................................................................... 33
Referencing the parameter definition ............................................................................ 33
Comparing ADM and ADMX Syntax ................................................................................. 34
Sample Files ..................................................................................................................... 40
To add the ADM sample files to the Group Policy Object Editor on a Windows Vista
Machine ...................................................................................................................... 40
To add the ADMX sample files to the Group Policy Object Editor on a Windows Vista
Machine ...................................................................................................................... 41
Additional references ..................................................................................................... 41
ADMX syntax .................................................................................................................... 41
additive Attribute ............................................................................................................... 42
Syntax ............................................................................................................................ 42
Examples ....................................................................................................................... 42
Additional references ..................................................................................................... 42
annotation Element ........................................................................................................... 42
Syntax ............................................................................................................................ 43
Attributes ........................................................................................................................ 43
Child elements ............................................................................................................... 43
Remarks......................................................................................................................... 43
Examples ....................................................................................................................... 43
Additional references ..................................................................................................... 43
boolean Element ............................................................................................................... 44
Syntax ............................................................................................................................ 44
Attributes ........................................................................................................................ 44
Child elements ............................................................................................................... 45
Remarks......................................................................................................................... 45
Examples ....................................................................................................................... 45
Additional references ..................................................................................................... 45
category Element .............................................................................................................. 46
Syntax ............................................................................................................................ 46
Attributes ........................................................................................................................ 46
Child elements ............................................................................................................... 47
Remarks......................................................................................................................... 47
Examples ....................................................................................................................... 48
Additional references ..................................................................................................... 48
categories Element ........................................................................................................... 48
Syntax ............................................................................................................................ 48
Attributes ........................................................................................................................ 48
Child elements ............................................................................................................... 49
Remarks......................................................................................................................... 49
Examples ....................................................................................................................... 49
Additional references ..................................................................................................... 49
checkBox Element ............................................................................................................ 50
Syntax ............................................................................................................................ 50
Attributes ........................................................................................................................ 50
Child elements ............................................................................................................... 50
Remarks......................................................................................................................... 50
Examples ....................................................................................................................... 51
Additional references ..................................................................................................... 51
class Attribute .................................................................................................................... 51
Syntax ............................................................................................................................ 51
Examples ....................................................................................................................... 51
Additional references ..................................................................................................... 52
clientExtension Attribute.................................................................................................... 52
Syntax ............................................................................................................................ 52
Examples ....................................................................................................................... 52
Additional references ..................................................................................................... 52
comboBox Element ........................................................................................................... 53
Syntax ............................................................................................................................ 53
Attributes ........................................................................................................................ 53
Child elements ............................................................................................................... 53
Remarks......................................................................................................................... 54
Examples ....................................................................................................................... 54
Additional references ..................................................................................................... 54
decimal Element (elements) ............................................................................................. 55
Syntax ............................................................................................................................ 55
Attributes ........................................................................................................................ 55
Child elements ............................................................................................................... 56
Remarks......................................................................................................................... 56
Examples ....................................................................................................................... 56
Additional references ..................................................................................................... 57
decimal Element (value).................................................................................................... 57
Syntax ............................................................................................................................ 57
Attributes ........................................................................................................................ 57
Child elements ............................................................................................................... 57
Examples ....................................................................................................................... 57
Additional references ..................................................................................................... 58
decimalTextBox Element .................................................................................................. 58
Syntax ............................................................................................................................ 58
Attributes ........................................................................................................................ 58
Child elements ............................................................................................................... 59
Remarks......................................................................................................................... 59
Examples ....................................................................................................................... 59
Additional references ..................................................................................................... 59
default Element ................................................................................................................. 60
Syntax ............................................................................................................................ 60
Attributes ........................................................................................................................ 60
Child elements ............................................................................................................... 60
Remarks......................................................................................................................... 60
Examples ....................................................................................................................... 60
Additional references ..................................................................................................... 60
defaultChecked Attribute ................................................................................................... 61
Syntax ............................................................................................................................ 61
Remarks......................................................................................................................... 61
Examples ....................................................................................................................... 61
Additional references ..................................................................................................... 61
defaultItem Attribute .......................................................................................................... 62
Syntax ............................................................................................................................ 62
Remarks......................................................................................................................... 62
Examples ....................................................................................................................... 62
Additional references ..................................................................................................... 62
defaultKey Attribute ........................................................................................................... 62
Syntax ............................................................................................................................ 62
Remarks......................................................................................................................... 63
Examples ....................................................................................................................... 63
Additional references ..................................................................................................... 63
defaultValue Attribute ........................................................................................................ 64
Syntax ............................................................................................................................ 64
Examples ....................................................................................................................... 64
Additional references ..................................................................................................... 64
defaultValue Element ........................................................................................................ 64
Syntax ............................................................................................................................ 64
Attributes ........................................................................................................................ 64
Child elements ............................................................................................................... 65
Remarks......................................................................................................................... 65
Examples ....................................................................................................................... 65
Additional references ..................................................................................................... 65
definition Element.............................................................................................................. 65
Syntax ............................................................................................................................ 65
Attributes ........................................................................................................................ 65
Child elements ............................................................................................................... 66
Remarks......................................................................................................................... 66
Examples ....................................................................................................................... 66
Additional references ..................................................................................................... 67
definitions Element ............................................................................................................ 67
Syntax ............................................................................................................................ 67
Attributes ........................................................................................................................ 67
Child elements ............................................................................................................... 67
Remarks......................................................................................................................... 68
Examples ....................................................................................................................... 68
Additional references ..................................................................................................... 68
delete Element .................................................................................................................. 68
Syntax ............................................................................................................................ 69
Attributes ........................................................................................................................ 69
Child elements ............................................................................................................... 69
Examples ....................................................................................................................... 69
Additional references ..................................................................................................... 69
description Element........................................................................................................... 69
Syntax ............................................................................................................................ 70
Attributes ........................................................................................................................ 70
Child elements ............................................................................................................... 70
Remarks......................................................................................................................... 70
Examples ....................................................................................................................... 70
Additional references ..................................................................................................... 70
disabledList Element ......................................................................................................... 70
Syntax ............................................................................................................................ 70
Attributes ........................................................................................................................ 71
Child elements ............................................................................................................... 71
Remarks......................................................................................................................... 71
Examples ....................................................................................................................... 71
Additional references ..................................................................................................... 72
disabledValue Element ..................................................................................................... 72
Syntax ............................................................................................................................ 72
Attributes ........................................................................................................................ 73
Child elements ............................................................................................................... 73
Remarks......................................................................................................................... 73
Examples ....................................................................................................................... 73
Additional references ..................................................................................................... 74
displayName Attribute ....................................................................................................... 74
Syntax ............................................................................................................................ 74
Remarks......................................................................................................................... 74
Examples ....................................................................................................................... 74
Additional references ..................................................................................................... 74
displayName Element ....................................................................................................... 75
Syntax ............................................................................................................................ 75
Attributes ........................................................................................................................ 75
Child elements ............................................................................................................... 75
Remarks......................................................................................................................... 75
Examples ....................................................................................................................... 75
Additional references ..................................................................................................... 75
dropdownList Element....................................................................................................... 76
Syntax ............................................................................................................................ 76
Attributes ........................................................................................................................ 76
Child elements ............................................................................................................... 76
Remarks......................................................................................................................... 77
Examples ....................................................................................................................... 77
Additional references ..................................................................................................... 77
elements Element ............................................................................................................. 77
Syntax ............................................................................................................................ 77
Attributes ........................................................................................................................ 78
Child elements ............................................................................................................... 78
Remarks......................................................................................................................... 78
Examples ....................................................................................................................... 79
Additional references ..................................................................................................... 79
enabledList Element.......................................................................................................... 79
Syntax ............................................................................................................................ 79
Attributes ........................................................................................................................ 79
Child elements ............................................................................................................... 80
Remarks......................................................................................................................... 80
Examples ....................................................................................................................... 80
Additional references ..................................................................................................... 81
enabledValue Element ...................................................................................................... 81
Syntax ............................................................................................................................ 81
Attributes ........................................................................................................................ 81
Child elements ............................................................................................................... 81
Remarks......................................................................................................................... 82
Examples ....................................................................................................................... 82
Additional references ..................................................................................................... 82
enum Element ................................................................................................................... 82
Syntax ............................................................................................................................ 83
Attributes ........................................................................................................................ 83
Child elements ............................................................................................................... 83
Remarks......................................................................................................................... 84
Examples ....................................................................................................................... 84
Additional references ..................................................................................................... 85
expandable Attribute ......................................................................................................... 86
Syntax ............................................................................................................................ 86
Remarks......................................................................................................................... 86
Examples ....................................................................................................................... 86
Additional references ..................................................................................................... 86
explainText Attribute ......................................................................................................... 87
Syntax ............................................................................................................................ 87
Remarks......................................................................................................................... 87
Examples ....................................................................................................................... 87
Additional references ..................................................................................................... 87
explicitValue Attribute ........................................................................................................ 88
Syntax ............................................................................................................................ 88
Remarks......................................................................................................................... 88
Examples ....................................................................................................................... 88
Additional references ..................................................................................................... 88
fallbackCulture Attribute .................................................................................................... 89
Syntax ............................................................................................................................ 89
Remarks......................................................................................................................... 89
Examples ....................................................................................................................... 89
Additional references ..................................................................................................... 89
falseList Element ............................................................................................................... 89
Syntax ............................................................................................................................ 89
Attributes ........................................................................................................................ 90
Child elements ............................................................................................................... 90
Remarks......................................................................................................................... 90
Examples ....................................................................................................................... 90
Additional references ..................................................................................................... 91
falseValue Element ........................................................................................................... 91
Syntax ............................................................................................................................ 91
Attributes ........................................................................................................................ 91
Child elements ............................................................................................................... 92
Remarks......................................................................................................................... 92
Examples ....................................................................................................................... 92
Additional references ..................................................................................................... 92
fileName Attribute .............................................................................................................. 93
Syntax ............................................................................................................................ 93
Remarks......................................................................................................................... 93
Examples ....................................................................................................................... 93
Additional references ..................................................................................................... 93
id Attribute ......................................................................................................................... 93
Syntax ............................................................................................................................ 93
Examples ....................................................................................................................... 93
Additional references ..................................................................................................... 94
item Element ..................................................................................................................... 94
Syntax ............................................................................................................................ 94
Attributes ........................................................................................................................ 94
Child elements ............................................................................................................... 95
Remarks......................................................................................................................... 95
Examples ....................................................................................................................... 95
Additional references ..................................................................................................... 95
item Element (enum) ......................................................................................................... 96
Syntax ............................................................................................................................ 96
Attributes ........................................................................................................................ 96
Child elements ............................................................................................................... 96
Remarks......................................................................................................................... 97
Examples ....................................................................................................................... 97
Additional references ..................................................................................................... 97
key Attribute ...................................................................................................................... 97
Syntax ............................................................................................................................ 98
Remarks......................................................................................................................... 98
Examples ....................................................................................................................... 98
Additional references ..................................................................................................... 98
keywords Element ............................................................................................................. 98
Syntax ............................................................................................................................ 98
Attributes ........................................................................................................................ 99
Child elements ............................................................................................................... 99
Remarks......................................................................................................................... 99
Examples ....................................................................................................................... 99
Additional references ..................................................................................................... 99
label Element .................................................................................................................... 99
Syntax ............................................................................................................................ 99
Attributes ...................................................................................................................... 100
Child elements ............................................................................................................. 100
Remarks....................................................................................................................... 100
Examples ..................................................................................................................... 100
Additional references ................................................................................................... 100
list Element ...................................................................................................................... 100
Syntax .......................................................................................................................... 100
Attributes ...................................................................................................................... 101
Child elements ............................................................................................................. 102
Remarks....................................................................................................................... 102
Examples ..................................................................................................................... 102
Additional references ................................................................................................... 103
listBox Element ............................................................................................................... 103
Syntax .......................................................................................................................... 103
Attributes ...................................................................................................................... 103
Child elements ............................................................................................................. 103
Remarks....................................................................................................................... 103
Examples ..................................................................................................................... 104
Additional references ................................................................................................... 104
maxLength Attribute ........................................................................................................ 104
Syntax .......................................................................................................................... 104
Examples ..................................................................................................................... 104
Additional references ................................................................................................... 104
maxValue Attribute .......................................................................................................... 105
Syntax .......................................................................................................................... 105
Remarks....................................................................................................................... 105
Examples ..................................................................................................................... 105
Additional references ................................................................................................... 105
minRequiredRevision Attribute ....................................................................................... 106
Syntax .......................................................................................................................... 106
Remarks....................................................................................................................... 106
Examples ..................................................................................................................... 106
Additional references ................................................................................................... 107
minValue Attribute ........................................................................................................... 107
Syntax .......................................................................................................................... 107
Remarks....................................................................................................................... 107
Examples ..................................................................................................................... 107
Additional references ................................................................................................... 108
name Attribute ................................................................................................................. 108
Syntax .......................................................................................................................... 108
Remarks....................................................................................................................... 108
Examples ..................................................................................................................... 108
Additional references ................................................................................................... 108
namespace Attribute ....................................................................................................... 109
Syntax .......................................................................................................................... 109
Remarks....................................................................................................................... 109
Examples ..................................................................................................................... 109
Additional references ................................................................................................... 109
noSort Attribute ............................................................................................................... 110
Syntax .......................................................................................................................... 110
Remarks....................................................................................................................... 110
Examples ..................................................................................................................... 110
Additional references ................................................................................................... 110
parentCategory Element ................................................................................................. 111
Syntax .......................................................................................................................... 111
Attributes ...................................................................................................................... 111
Child elements ............................................................................................................. 111
Remarks....................................................................................................................... 111
Examples ..................................................................................................................... 111
Additional references ................................................................................................... 112
policy Element ................................................................................................................. 112
Syntax .......................................................................................................................... 112
Attributes ...................................................................................................................... 112
Child elements ............................................................................................................. 113
Remarks....................................................................................................................... 115
Examples ..................................................................................................................... 115
Additional references ................................................................................................... 116
policyDefinitionResources Element ................................................................................ 116
Syntax .......................................................................................................................... 116
Attributes ...................................................................................................................... 116
Child elements ............................................................................................................. 117
Remarks....................................................................................................................... 118
Examples ..................................................................................................................... 118
Additional references ................................................................................................... 119
policyDefinitions Element ................................................................................................ 119
Syntax .......................................................................................................................... 119
Attributes ...................................................................................................................... 120
Child elements ............................................................................................................. 120
Remarks....................................................................................................................... 121
Examples ..................................................................................................................... 122
Additional references ................................................................................................... 122
policyNamespaces Element ............................................................................................ 123
Syntax .......................................................................................................................... 123
Attributes ...................................................................................................................... 123
Child elements ............................................................................................................. 123
Remarks....................................................................................................................... 123
Examples ..................................................................................................................... 124
Additional references ................................................................................................... 124
policies Element .............................................................................................................. 124
Syntax .......................................................................................................................... 124
Attributes ...................................................................................................................... 124
Child elements ............................................................................................................. 124
Remarks....................................................................................................................... 125
Examples ..................................................................................................................... 125
Additional references ................................................................................................... 125
prefix Attribute ................................................................................................................. 126
Syntax .......................................................................................................................... 126
Remarks....................................................................................................................... 126
Examples ..................................................................................................................... 126
Additional references ................................................................................................... 126
presentation Attribute ...................................................................................................... 126
Syntax .......................................................................................................................... 126
Remarks....................................................................................................................... 127
Examples ..................................................................................................................... 127
Additional references ................................................................................................... 127
presentation Element ...................................................................................................... 127
Syntax .......................................................................................................................... 127
Attributes ...................................................................................................................... 128
Child elements ............................................................................................................. 128
Remarks....................................................................................................................... 129
Examples ..................................................................................................................... 130
Additional references ................................................................................................... 130
presentationTable Element ............................................................................................. 130
Syntax .......................................................................................................................... 130
Attributes ...................................................................................................................... 130
Child elements ............................................................................................................. 131
Remarks....................................................................................................................... 131
Examples ..................................................................................................................... 131
Additional references ................................................................................................... 132
ref Attribute ...................................................................................................................... 133
Syntax .......................................................................................................................... 133
Remarks....................................................................................................................... 133
Examples ..................................................................................................................... 133
Additional references ................................................................................................... 133
refId Attribute ................................................................................................................... 134
Syntax .......................................................................................................................... 134
Examples ..................................................................................................................... 134
Additional references ................................................................................................... 134
required Attribute ............................................................................................................. 135
Syntax .......................................................................................................................... 135
Examples ..................................................................................................................... 135
Additional references ................................................................................................... 135
resources Element (.adml) .............................................................................................. 135
Syntax .......................................................................................................................... 135
Attributes ...................................................................................................................... 136
Child elements ............................................................................................................. 136
Remarks....................................................................................................................... 136
Examples ..................................................................................................................... 136
Additional references ................................................................................................... 137
resources Element (.admx) ............................................................................................. 137
Syntax .......................................................................................................................... 137
Attributes ...................................................................................................................... 137
Child elements ............................................................................................................. 138
Remarks....................................................................................................................... 138
Examples ..................................................................................................................... 138
Additional references ................................................................................................... 138
revision Attribute ............................................................................................................. 139
Syntax .......................................................................................................................... 139
Remarks....................................................................................................................... 139
Examples ..................................................................................................................... 139
Additional references ................................................................................................... 140
schemaVersion Attribute ................................................................................................. 140
Syntax .......................................................................................................................... 140
Remarks....................................................................................................................... 140
Examples ..................................................................................................................... 141
Additional references ................................................................................................... 141
seeAlso Element ............................................................................................................. 141
Syntax .......................................................................................................................... 141
Attributes ...................................................................................................................... 141
Child elements ............................................................................................................. 141
Remarks....................................................................................................................... 141
Examples ..................................................................................................................... 142
Additional references ................................................................................................... 142
soft Attribute .................................................................................................................... 142
Syntax .......................................................................................................................... 142
Remarks....................................................................................................................... 142
Examples ..................................................................................................................... 142
Additional references ................................................................................................... 143
spin Attribute ................................................................................................................... 143
Syntax .......................................................................................................................... 143
Remarks....................................................................................................................... 143
Examples ..................................................................................................................... 143
Additional references ................................................................................................... 144
spinStep Attribute ............................................................................................................ 144
Syntax .......................................................................................................................... 144
Examples ..................................................................................................................... 144
Additional references ................................................................................................... 144
storeAsText Attribute....................................................................................................... 144
Syntax .......................................................................................................................... 145
Remarks....................................................................................................................... 145
Examples ..................................................................................................................... 145
Additional references ................................................................................................... 145
string Element (.adml) ..................................................................................................... 145
Syntax .......................................................................................................................... 145
Attributes ...................................................................................................................... 146
Child elements ............................................................................................................. 146
Remarks....................................................................................................................... 146
Examples ..................................................................................................................... 146
Additional references ................................................................................................... 147
string Element (.admx) .................................................................................................... 147
Syntax .......................................................................................................................... 147
Attributes ...................................................................................................................... 147
Child elements ............................................................................................................. 147
Examples ..................................................................................................................... 147
Additional references ................................................................................................... 147
stringTable Element ........................................................................................................ 148
Syntax .......................................................................................................................... 148
Attributes ...................................................................................................................... 148
Child elements ............................................................................................................. 148
Remarks....................................................................................................................... 148
Examples ..................................................................................................................... 149
Additional references ................................................................................................... 149
suggestion Element......................................................................................................... 149
Syntax .......................................................................................................................... 149
Attributes ...................................................................................................................... 150
Child elements ............................................................................................................. 150
Remarks....................................................................................................................... 150
Examples ..................................................................................................................... 150
Additional references ................................................................................................... 150
supersededAdm Element ................................................................................................ 150
Syntax .......................................................................................................................... 150
Attributes ...................................................................................................................... 151
Child elements ............................................................................................................. 151
Examples ..................................................................................................................... 151
Additional references ................................................................................................... 151
supportedOn Element ..................................................................................................... 151
Syntax .......................................................................................................................... 151
Attributes ...................................................................................................................... 152
Child elements ............................................................................................................. 152
Remarks....................................................................................................................... 152
Examples ..................................................................................................................... 153
Additional references ................................................................................................... 153
supportedOn Element (policy) ........................................................................................ 153
Syntax .......................................................................................................................... 153
Attributes ...................................................................................................................... 153
Child elements ............................................................................................................. 154
Remarks....................................................................................................................... 154
Examples ..................................................................................................................... 154
Additional references ................................................................................................... 154
target Element ................................................................................................................. 155
Syntax .......................................................................................................................... 155
Attributes ...................................................................................................................... 155
Child elements ............................................................................................................. 155
Remarks....................................................................................................................... 156
Examples ..................................................................................................................... 156
Additional references ................................................................................................... 156
text Element .................................................................................................................... 156
Syntax .......................................................................................................................... 156
Attributes ...................................................................................................................... 156
Child elements ............................................................................................................. 157
Remarks....................................................................................................................... 157
Examples ..................................................................................................................... 158
Additional references ................................................................................................... 158
text Element (presentation) ............................................................................................. 158
Syntax .......................................................................................................................... 158
Attributes ...................................................................................................................... 159
Child elements ............................................................................................................. 159
Examples ..................................................................................................................... 159
Additional references ................................................................................................... 159
textBox Element .............................................................................................................. 159
Syntax .......................................................................................................................... 159
Attributes ...................................................................................................................... 160
Child elements ............................................................................................................. 160
Remarks....................................................................................................................... 160
Examples ..................................................................................................................... 160
Additional references ................................................................................................... 161
trueList Element .............................................................................................................. 161
Syntax .......................................................................................................................... 161
Attributes ...................................................................................................................... 161
Child elements ............................................................................................................. 161
Remarks....................................................................................................................... 162
Examples ..................................................................................................................... 162
Additional references ................................................................................................... 162
trueValue Element........................................................................................................... 163
Syntax .......................................................................................................................... 163
Attributes ...................................................................................................................... 163
Child elements ............................................................................................................. 163
Remarks....................................................................................................................... 164
Examples ..................................................................................................................... 164
Additional references ................................................................................................... 164
using Element ................................................................................................................. 164
Syntax .......................................................................................................................... 164
Attributes ...................................................................................................................... 164
Child elements ............................................................................................................. 165
Remarks....................................................................................................................... 165
Examples ..................................................................................................................... 165
Additional references ................................................................................................... 166
value Attribute ................................................................................................................. 166
Syntax .......................................................................................................................... 166
Examples ..................................................................................................................... 166
Additional references ................................................................................................... 166
value Element ................................................................................................................. 166
Syntax .......................................................................................................................... 166
Attributes ...................................................................................................................... 167
Child elements ............................................................................................................. 167
Remarks....................................................................................................................... 167
Examples ..................................................................................................................... 167
Additional references ................................................................................................... 168
valueList Element ............................................................................................................ 168
Syntax .......................................................................................................................... 168
Attributes ...................................................................................................................... 168
Child elements ............................................................................................................. 168
Remarks....................................................................................................................... 169
Examples ..................................................................................................................... 169
Additional references ................................................................................................... 170
valueName Attribute........................................................................................................ 170
Syntax .......................................................................................................................... 170
Examples ..................................................................................................................... 170
Additional references ................................................................................................... 170
valuePrefix Attribute ........................................................................................................ 171
Syntax .......................................................................................................................... 171
Remarks....................................................................................................................... 171
Examples ..................................................................................................................... 171
Additional references ................................................................................................... 172
XML declaration .............................................................................................................. 172
Syntax .......................................................................................................................... 172
Attributes ...................................................................................................................... 172
Child elements ............................................................................................................. 173
Remarks....................................................................................................................... 173
Examples ..................................................................................................................... 173
Additional references ................................................................................................... 173
xmlns Attribute ................................................................................................................ 173
Syntax .......................................................................................................................... 173
Remarks....................................................................................................................... 174
Examples ..................................................................................................................... 174
Additional references ................................................................................................... 174
21
Group Policy ADMX Syntax Reference
Guide
This reference guide provides information for creating and editing custom ADMX files.
These XML-based files allow the administrator to create a user interface in the Group
Policy Object Editor and Group Policy Management Console to display Group Policy
settings.
How to read this document
For those wishing to get an introduction to the ADMX format, the conceptual topics in this
reference guide provide a starting point. It is recommended you read the following topics:

ADMX Prerequisites

ADMX Schema

.admx and .adml File Structure

Best Practices for Authoring ADMX Files

Referencing the Windows Base ADMX File

Creating a Custom Base ADMX File

Associating .admx and .adml Parameter Information

Comparing ADM and ADMX Syntax

Sample Files
After you have become familiar with ADMX files and the ADMX format, you can then use
the ADMX syntax section as technical reference. This section provides an alphabetical
reference that lists all ADMX elements and attributes used when creating an .admx file
and an .adml file.
Note
This document will use the following rules when referring to the different
components of ADMX files. When referring to the general set of administrative
template files for Windows Vista registry settings, we will refer to "ADMX files."
This document will refer to ".admx files" when referring to the language-neutral
administrative template files and ".adml files" when referring to the languagedependent administrative template files.
22
ADMX Prerequisites
ADMX files are XML based. You should have some basic understanding of the XML
language structure and syntax. At a minimum you should understand:

The definition of a well-formed XML document.

XML elements.

XML attributes.

XML namespaces.

XML is case sensitive. You must enter all elements and attributes in the same case
as presented in this reference.
You can create and edit ADMX files using any XML-compatible editor, which can be as
basic as Notepad.
ADMX Schema
In Windows Vista, the Group Policy Object Editor and Group Policy Management
Console display registry-based policy settings using ADMX files. An ADMX file is an
XML-based file, defined as a set of one language neutral file (.admx) and associated
ADMX language-dependent files (.adml).
The ADMX schema defines the syntax for the ADMX files. The ADMX schema can be
downloaded from the Microsoft Download Center
(http://go.microsoft.com/fwlink/?LinkId=86094).
.admx and .adml File Structure
In order to support the multilingual display of policy settings, the ADMX file structure must
be broken into two types of files:

A language-neutral file, .admx, describing the structure of the categories and
Administrative template policy settings displayed in the Group Policy Object Editor.

A set of language-dependent files, .adml, providing the localized portions displayed in
the Group Policy Object Editor. Each .adml file represents a single language you
wish to support.
23
Language-neutral file (.admx) structure
The language-neutral file, .admx, determines the number and type of policy settings and
their location by category in the Group Policy Object Editor display.
Top level view of the .admx file structure
The .admx file is divided into seven main sections:

The XML declaration that is required in order to validate as an XML-based file.

The policyDefinitions Element, which contains all other elements for an .admx file.

The policyNamespaces Element, which defines the unique namespace for this .admx
file. The policyNamespaces element also provides a mapping to external file
namespaces if this .admx file will reference category elements defined in a different
24
.admx file. For more information about mapping to external file namespaces, see
Referencing the Windows Base ADMX File or Creating a Custom Base ADMX File.

The resources Element (.admx), which specifies the requirements for the languagespecific resources; the minimum required version of the associated .adml file.

The supportedOn Element, which specifies references to localized text strings
defining the operating systems or applications affected by a specific policy setting.
For more information about mapping to supportedOn text for Windows, see
Referencing the Windows Base ADMX File.

The categories Element, which specifies categories under which the policy setting in
this .admx file will be displayed in the Group Policy Object Editor. If you specify a
category name that already exists in a different .admx file, you will create a duplicate
node. For more information about referencing previously defined category names in
order to avoid duplicate nodes, see Referencing the Windows Base ADMX File or
Creating a Custom Base ADMX File.

The policies Element, which contains the individual policy setting definitions.
Language resource file (.adml) structure
The language resource files, .adml, provide the language specific information needed by
the language neutral file. The language neutral file will then reference specific sections of
the language resource file in order for the Group Policy Object Editor to display a policy
setting in the correct language.
25
Top level view of the .adml file structure
The .adml file contains the following main sections:

The XML declaration, required to validate as an XML-based file.

The policyDefinitionResources Element, which contains all other elements for an
.adml file.

The resources Element (.adml), which contains a stringTable Element and a
presentationTable Element for a specified language. These two elements must be
defined in the .adml file in the specific order of stringTable element followed by
presentationTable element, as required by the ADMX schema. The parser for the
Group Policy tools will give an error if the order of these two elements is reversed.
Best Practices for Authoring ADMX Files
Here are some best practices to use when authoring an ADMX file.
1. All ADMX files are authored as one language neutral file (.admx) and a set of
language-dependent files that will be localized for all supported languages (.adml).
26
2. To avoid duplicate nodes being displayed in the Group Policy Object Editor, do not
use the same category name that has been previously defined under a parent
category. For example, if your company created an .admx file with a category based
on the company name, then creating a second .admx file with that company name
category will result in the Group Policy Object Editor creating two nodes with the
same name. Instead create a custom base file that all your company .admx files will
reference. For more information see Creating a Custom Base ADMX File.
3. To avoid circular referencing, one .admx file should not reference another .admx file's
category elements. Instead, a component base category should be placed in a
separate base file built for referencing from multiple .admx files. For more information
see Creating a Custom Base ADMX File.
4. Each policy namespace for an .admx file must be unique. The policy namespace is
defined in the target Element of the .admx file.
5. XML is case sensitive. You must enter all elements and attributes in the same case
as presented in this reference.
Referencing the Windows Base ADMX
File
The Windows base file, windows.admx, provides predefined categories and supported
on text for Windows products. This section provides information about referencing the
definitions from the windows.admx file for use in your .admx file
Referring to the Windows base file
The Windows base file is referred to using the unique namespace,
Microsoft.Policies.Windows. The namespace string is case sensitive.
To refer to the Windows base file, include the using element in your policyNamespaces
element. The namespace attribute must match the defined namespace from the
Windows base file. Even though 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
Windows base file to avoid confusion.
For example, this XML fragment from the example2.admx file both defines its
namespace and refers to the Windows Base file within the policyNamespaces element.
<policyNamespaces>
27
<target prefix="example2" namespace="Microsoft.Policies.Example2" />
<using prefix="windows" namespace="Microsoft.Policies.Windows" />
</policyNamespaces>
Referencing Windows category elements
You can display your category node or a policy setting under an existing Windows
component node of the Group Policy Object Editor or the Group Policy Management
Console. To accomplish this, you must reference the category elements in the Windows
base file. Windows base file category elements can be used as the parentCategory
element for any category element or policy element within your .admx file. If you define
the category element name within your own .admx file instead of referencing the
Windows base file, the Group Policy Object Editor or Group Policy Management Console
will display a duplicate node. This happens because a category element defined in a
different namespace is evaluated as a unique element by the Group Policy Object Editor.
Because each .admx file is created in a unique namespace, this will result in duplicate
nodes.
To place your category node under an existing node from the Windows base file, add the
"windows:" prefix to the ref attribute of the parentCategory element.
This XML fragment demonstrates placing your sample category under the
parentCategory based on the Windows base file category element. In the Group Policy
Object Editor, this is equivalent to displaying your sample category node under an
existing Windows component node.
<category name="SAMPLE" displayName="$(string.SAMPLE)"
explainText="$(string.SAMPLEHELP)">
<parentCategory ref="windows:WindowsComponents" />
</category>
This XML fragment demonstrates placing your sample policy setting under the
parentCategory based on the Windows base file category element. In the Group Policy
Object Editor, this is equivalent to displaying your sample policy setting under an existing
Windows component node.
<policy name="Sample_NoParamPolicy" class="Both"
displayName="$(string.Sample_NoParamPolicy)"
explainText="$(string.Sample_NoParamPolicy_Help)" key="Software\Policies\Examples"
valueName="Example1NoParam">
<parentCategory ref="windows:WindowsComponents" />
<supportedOn ref="SUPPORTED_ProductOnly" />
28
<enabledValue>
<decimal value="1" />
</enabledValue>
<disabledValue>
<decimal value="0" />
</disabledValue>
</policy>
Referencing Windows supportedOn elements
Windows product names support information is provided in the Windows base file. You
can reference these product names for your .admx file. In order to use the supported on
information in the Windows base file, you must do the following:

Within your supportedOn element, add the "windows:" prefix to the ref attribute to
reference the Windows base file.

Reference a defined supportedOn element from the Windows base file. If you use
an invalid element name, the Group Policy Object Editor will not display any
supported on information and will not display an error message.
This XML fragment demonstrates referencing supported on text for your policy setting,
using existing Windows product information.
<policy name="Sample_NoParamPolicy" class="Both"
displayName="$(string.Sample_NoParamPolicy)"
explainText="$(string.Sample_NoParamPolicy_Help)" key="Software\Policies\Examples"
valueName="Example1NoParam">
<parentCategory ref="SAMPLE" />
<supportedOn ref="windows:SUPPORTED_WindowsXP" />
<enabledValue>
<decimal value="1" />
</enabledValue>
<disabledValue>
<decimal value="0" />
</disabledValue>
</policy>
Creating a Custom Base ADMX File
If your organization plans on creating a number of .admx files to display under a single
category node in the Group Policy Object Editor, you will need to build a custom base file.
A single custom base file with predefined categories and supported on text can be
29
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 Group Policy Object Editor 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="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
revision="1.0" schemaVersion="1.0"
xmlns=
"http://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="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns=
"http://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>
30
<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>
Caution
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 Group Policy Object Editor or the Group Policy Management Console. To accomplish
this, you must 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 Group Policy Object
Editor or Group Policy Management Console will display a duplicate node. This happens
because a category element defined in a different namespace is evaluated as a unique
31
element by the Group Policy Object Editor. 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 Group Policy Object
Editor.
<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 Group Policy Object Editor.
<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>
Associating .admx and .adml Parameter
Information
ADM files use the PART statement to define a single parameter for a policy setting. In the
ADMX syntax, the elements controlling the presentation or localized display of a
parameter, are defined in the .adml file. The information defining the datatype and value
of a parameter are defined in the .admx file. This section will describe how the different
32
elements from the two files, .admx and .adml, are used to create parameter definitions
for policy settings.
We will use an example of creating two check box parameters for a single policy setting
to illustrate how the .admx and .adml files work together to define parameters. This
example is a fragment taken from the example2.admx and example2.adml sample files.
For more information about downloading and importing the sample files into the Group
Policy Object Editor, see Sample Files.
This XML fragment shows the policy setting from the .admx file that includes two check
box parameters.
<policy name="Sample_Checkbox" class="Machine"
displayName="$(string.Sample_Checkbox)"
explainText="$(string.Sample_Checkbox_Help)"
presentation="$(presentation.Sample_Checkbox)"
key="Software\Policies\Examples">
<parentCategory ref="CHECKBOXTWOTYPES_CATEGORY" />
<supportedOn ref="windows:SUPPORTED_ProductOnly" />
<elements>
<boolean id="Checkbox_1" valueName="Example2Checkbox1">
<trueValue>
<decimal value="1" />
</trueValue>
<falseValue>
<decimal value="0" />
</falseValue>
</boolean>
<boolean id="Checkbox_2" valueName="Example2Checkbox2">
<trueValue>
<decimal value="0" />
</trueValue>
<falseValue>
<decimal value="1" />
</falseValue>
</boolean>
</elements>
</policy>
This XML fragment shows the corresponding presentation information from the .adml file.
<presentation id="Sample_Checkbox">
<checkBox refId="Checkbox_1">First check box parameter</checkBox>
<checkBox refId="Checkbox_2" defaultChecked="true">Second check box
parameter - checked by default</checkBox>
</presentation>
These two XML fragments provide a starting point for looking at the coordination between
parameter definitions in .admx and .adml files. We will look at two areas of coordination
33
between the .admx and .adml files. The first is the top level referencing between the
policy setting and its parameter display. The second is the referencing between datatype
representation in the elements element and the parameter definition in the presentation
element.
Referencing the presentation element
A policy setting defined through the policy element in an .admx file references a specific
presentation element in the .adml file through the presentation attribute of the policy
element. Using the example for the two check boxes, you can see the presentation
attribute is defined as presentation="$(presentation.Sample_Checkbox)". The
presentation.Sample_Checkbox text tells the Group Policy Object Editor to reference the
.adml file presentationTable element using the id attribute set to Sample_Checkbox. The
presentation element with this id attribute was provided above and is repeated here with
this XML fragment.
<presentation id="Sample_Checkbox">
<checkBox refId="Checkbox_1">First check box parameter</checkBox>
<checkBox refId="Checkbox_2" defaultChecked="true">Second check box
parameter - checked by default</checkBox>
</presentation>
You may wonder how the Group Policy Object Editor finds the correct .adml file to look
up the presentation element. The answer is simple. The Group Policy Object Editor will
search the .adml file with the same filename as the .admx file. The Group Policy Object
Editor will display an error message if it cannot find a corresponding .adml file for each
.admx file it reads.
The number of datatypes as well as the type of datatype (boolean, decimal, text, enum,
item, and list) defined in the .admx elements element must match the number and type
of the parameters defined in the .adml presentation element (checkBox, textBox,
decimalTextBox, comboBox, dropdownList, and listBox). We will cover how to match
the datatypes to the parameter definitions in the next section.
Referencing the parameter definition
You can match the number of datatypes defined in an elements element to the number
of parameters identified in the presentation element, if you collapse the elements. In our
example, the elements element contains two boolean elements:
<elements>
<boolean id="Checkbox_1" valueName="Example2Checkbox1">
…
34
</boolean>
<boolean id="Checkbox_2" valueName="Example2Checkbox2">
…
</boolean>
</elements>
The presentation element contains two checkBox elements:
<presentation id="Sample_Checkbox">
<checkBox refId="Checkbox_1">…</checkBox>
<checkBox refId="Checkbox_2" defaultChecked="true">…</checkBox>
</presentation>
The number of boolean elements (2) matches the number of checkBox elements (2).
You use the id attribute of the boolean element to match the associated checkBox
element referred to using the refId attribute.
The below table shows how to match the datatype in the .admx file, which is the boolean
element in our example, with the parameter definition in the .adml file, which is the
checkBox element in our example.
Datatype in the .admx file
Parameter definition in the .adml file
boolean Element
checkBox Element
text Element
textBox Element
decimal Element (elements)
decimalTextBox Element
text Element
comboBox Element
enum Element or item Element
dropdownList Element
list Element
listBox Element
Comparing ADM and ADMX Syntax
This section provides a high-level mapping of ADM syntax to the ADMX equivalents.
("Not applicable"in the ADM-to-ADMX conversion chart implies there is no equivalent
syntax used in that file.)
35
ADM Language
.admx Equivalent
.adml Equivalent
Comments
ADM File Language resources
Versions (#If
minRequiredRevision
Version)
revision
Unlike ADM files, the
ADMX file has
versioning built in and
is not be tied to an
operating system
version.
ADM File Language resources
Versions (#If
minRequiredRevision
Version)
Not applicable
The resources
minRequiredRevision
attribute provides the
coordination between
the .admx and .adml
file versions
ADM File Language schemaVersion
Versions (#If
Version)
schemaVersion
The schemaVersion
attribute specifies the
ADMX schema
version assumed
when creating the
.admx and .adml files.
The Windows Vista
ADMX files assume a
1.0 schema version
number.
comments (;)
<!-- -->
<!-- -->
For ADM files, all text
following the ";" is
considered a
comment. For ADMX
files, the XML
comments will not be
processed by GP
tools.
Strings reference
(!!)
string
Not applicable
In ADM files, precede
text with "!!" to
reference a string.
<Strings> section of
the .adm file
Not applicable
stringTable
Reference
36
ADM Language
.admx Equivalent
.adml Equivalent
Comments
CLASS
class
Not applicable
ADMX files provide
the ability to classify
the policy definition as
being for user,
machine, or both. The
"both" classification
will allow you to create
a single policy
definition that applies
to the machine and
user registry keys.
CATEGORY

categories
Not applicable

category

parentCategory
ADM files assume
categories are nested
within the definitions.
ADMX files specify a
parentCategory
element for each
policy element defined
in the .admx file. An
individual category is
defined within the
"categories" element.
Reference
37
ADM Language
.admx Equivalent
.adml Equivalent
Comments
Duplicate Category
Sections allowed in
different ADM files.
Duplicate category
sections are not
allowed in different
ADMX files.
Not applicable
If one .adm file
includes a duplicate
"CATEGORY" entry
used in a different
existing .adm file, the
policy settings will be
merged when the
Group Policy Object
Editor processes the
ADM files. ADMX files
have unique
namespaces. Defining
the same "category"
element names in two
different .admx files
will cause the category
to be displayed twice.
Instead for .admx files,
you must define the
"category" element
name once and then
reference the category
element name with the
"using" element.
SUPPORTED
supportedOn
Not applicable
POLICY

policies
Not applicable

policy
Reference
In the .admx file, the
policies element
contains individual
policy elements that
correspond to a policy
setting.
38
ADM Language
.admx Equivalent
.adml Equivalent
Comments
PART
elements
presentation
In ADM files, the
PART statement
specifies various
policy setting options,
such as drop-down list
boxes, text boxes, and
text in the lower pane
of the Group Policy
snap-in. ADMX files
aggregate policy
setting options for one
policy setting into the
elements element in
the .admx file and the
presentation element
in the .adml file.
CHECKBOX
boolean
checkbox
TEXT
Not applicable
text
EDITTEXT
text
textBox
NUMERIC
decimal
decimalTextBox
COMBOBOX
text
comboBox
DROPDOWNLIST

enum

item
Reference
dropdownList
LISTBOX
list
listBox
VALUEON
enabledValue
Not applicable
VALUEOFF
disabledValue
Not applicable
ACTIONLISTON
enabledList
Not applicable
ACTIONLISTOFF
disabledList
Not applicable
The text element in
the .adml file provides
the string used as the
parameter text prompt.
39
ADM Language
.admx Equivalent
.adml Equivalent
KEYNAME
key
Not applicable
EXPLAIN
explainText
Not applicable
VALUENAME
valueName
Not applicable
CLIENTEXT
clientExtension
Not applicable
END
Not applicable
Not applicable
DEFCHECKED
Not applicable
defaultChecked
Line Breaks \n or
\n\n
Not applicable
Use line breaks
or blank lines
within the string
definitions.
Maximum string
length for EXPLAIN
text
Not applicable
Limited by
available memory
only.
Maximum string
length for
CATEGORY
EXPLAIN text
Not applicable
Limited by
available memory
only.
Maximum string
length for
EDITTEXT string
Not applicable
Maximum string
length for
EDITTEXT string
= 1023
characters.
Comments
Reference
XML syntax includes
termination of all of its
elements. There is no
need to use special
syntax to terminate an
element.
40
Sample Files
This document references two samples of ADM files,
example1_SinglePolicySetting.adm and example2.adm, with their corresponding
ADMX files. The Group Policy settings included in these files are fully functional. All of the
policy settings displayed through the use of these sample files will configure registry
settings under the registry keys, "[HKLM|HKCU]\Software\Policies\Examples". The
example files can be loaded into the Group Policy Object Editor on a Windows Vista–
based or Windows Server 2008–based computer. These files can serve as a starting
point to experiment with authoring ADMX files. You can make changes and verify the
results in the Group Policy Object Editor. As long as you do not change the registry keys,
anything you do should not affect actual Windows components or applications on your
machine. You can edit the files using an XML editor or a text editor such as Notepad.
The policy settings contained in these files will display in the Group Policy Object Editor
under the following categories:

ADM file policy settings: "[computer|user] configuration\Classic Administrative
Templates\Example 1 - Simplest single Group Policy setting" or
"[computer|user] configuration\Classic Administrative Templates\Example 2
Policy settings"

ADMX file policy settings: "[computer|user] configuration\Administrative
TemplatesExample 1 - Simplest single Group Policy setting""[computer|user]
or configuration\Administrative Templates\Example 2 Policy settings"
These sample files can be downloaded from the Microsoft Download Center
(http://go.microsoft.com/fwlink/?LinkId=86092).
To add the ADM sample files to the Group
Policy Object Editor on a Windows Vista
Machine
The ADM sample files can be tested using the Local Group Policy Object Editor.
1. Copy the example.adm file to the %windir%\inf directory.
2. To open the Group Policy Object Editor on a Windows Vista machine, click Start,
click Run, then type GPEDIT.msc.
3. Right-click either the computer or user configuration\Administrative Templates
node.
41
4. Click Add/Remove Templates.
5. The browser should open to the %windir%\inf directory. Select example.adm to add
this file to the Group Policy Object Editor.
To add the ADMX sample files to the Group
Policy Object Editor on a Windows Vista
Machine
The ADMX sample files can be tested using the Local Group Policy Object Editor. This
procedure assumes the test machine is either joined to a workgroup or a domain that
does not contain a central store.
1. Before opening the Group Policy Object Editor on a Windows Vista machine:
a. Copy the desired sample .admx file to the %windir%\PolicyDefinitions
directory.
b. Copy the corresponding sample .adml file to the
%windir%\PolicyDefinitions\en-us directory.
2. To open the local Group Policy Object Editor on a Windows Vista machine, click
Start, click Run, and then type GPEDIT.msc.
3. The Group Policy Object Editor will automatically read all ADMX files stored in the
%systemroot%\PolicyDefinitions\ directory.
Note
This procedure assumes this machine is not joined to a domain with an ADMX
central store.
Additional references

ADMX sample files (See http://go.microsoft.com/fwlink/?LinkId=86092)

Managing Group Policy ADMX Files Step-by-Step Guide (See
http://go.microsoft.com/fwlink/?LinkId=60363)
ADMX syntax
This section provides an alphabetical reference of all ADMX elements and attributes.
42
Important
XML is case sensitive. You must enter all elements and attributes in the same
case as presented in this reference.
additive Attribute
The additive attribute is 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.
Syntax
expandable="<true|false>"
where
true represents append new values in the list box to the existing subkeys, and
false represents only apply the new values from the list box.
Examples
This XML fragment example specifies a list element that appends the existing subkeys to
the ones that would be specified through the list box associated with this list element.
<list id="Sample_ListBox_SingleColumn_Param"
key="Software\Policies\Examples\listbox1"
additive="true" />
Additional references
list Element
annotation Element
The annotation element adds a localized comment at the beginning of the .adml file.
43
Syntax
<annotation>localized description text</annotation>
Attributes
There are no attributes associated with this element.
Child elements
There are no child elements associated with this element.
Remarks
This element is currently unsupported. It is recommended you use XML-based
commenting syntax for adding comments to the body of your file.
<!-- This text will be ignored when processing the files -->
Examples
This XML fragment specifies
<annotation>This file provides examples. Changing the settings should not affect
any installed applications.</annotation>
Additional references
ADMX Prerequisites
policyDefinitionResources Element
44
boolean Element
The boolean element sets a value based on the true and false cases in a policy setting.
The boolean element is generally associated with check box parameters in the Group
Policy Object Editor.
Syntax
<boolean id="<placeholderID>"
clientExtension="<placeholderGUID>"
key="<placeholderRegKey>"
valuename="<placeholderName>">
<trueValue> … </trueValue>
<falseValue> … </falseValue>
<trueList> … </trueList>
<falseList> … </falseList>
</boolean>
Attributes
Attributes
Required
Description
id Attribute
Yes
A mapping to the element.
clientExtension Attribute
No
The client-side extension
will process, on the client
computer, the particular
settings represented by the
element.
key Attribute
No
The registry key location
under which the registry
value will be created
valueName Attribute
Yes
The registry value that will
be configured for this
specific policy element.
45
Child elements
Element
Required
Description
trueValue Element
No
Sets a value based on the
true condition.
falseValue Element
No
Sets a value based on the
false condition.
trueList Element
No
Sets values based on the
true condition.
falseList Element
No
Sets values based on the
false condition.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
A boolean element in an .admx file will require a matching checkBox element with
matching id in the corresponding .adml file.
Examples
This XML fragment is an example of defining a boolean element for true and false cases.
<boolean id="Checkbox_1" valueName="Example2Checkbox1">
<trueValue>
<decimal value="1" />
</trueValue>
<falseValue>
<decimal value="0" />
</falseValue>
</boolean>
Additional references
checkBox Element
46
elements Element
category Element
The category element specifies the name of a unique category to be displayed in the
Group Policy Object Editor.
Syntax
The syntax of the category element declaration is:
<category name="<placeholder for logical or friendly name>"
displayName="$( string.<placeholder for category text>)"
explainText="$( string.<placeholder for help text>)">
<parentCategory> … </parentCategory>
<seeAlso> … </seeAlso>
<keywords> … </keywords>
</category>
Attributes
Attributes
Required
Description
name Attribute
Yes
name="<placeholder for
logical or friendly name>"
Specifies a logical name to use
for a specific supported
application and revision.
displayName Attribute
Yes
displayName="$(
string.<placeholder for
category text>)"
The reference to the category
text string located in the string
table of the .adml file.
47
Attributes
Required
Description
explainText Attribute
No
explainText="$(
string.<placeholder for help
text>)">
Explain or Help text associated
with a specific category.
Child elements
Element
Required
Description
parentCategory Element
element
Yes
Reference to parent of the
current category.
seeAlso Element element
No
Reference to another
element that may be
related. This element is not
supported and will be
ignored by current Group
Policy.
keywords Element
No
Contains index words that
could be used to search for
elements. This element is
not supported and will be
ignored by current Group
Policy tools.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
Each category element defines a text string representing the name of the category that
includes Group Policy settings declared in this .admx file, in the Group Policy Object
Editor. Duplicate category strings defined in different .admx files/policyNamespaces will
48
be treated as separate categories by the Group Policy Object Editor. This will result in
duplicate category titles in the Group Policy Object Editor display. Instead of creating a
category, you must reference the existing category to avoid creating duplicate categories.
You cannot define more than one parentCategory for a category element.
Examples
This XML fragment is an example of a single category that will be displayed under the
windows component category.
<category name="SAMPLE" displayName="$(string.SAMPLE)"
explainText="$(string.SAMPLEHELP)">
<!-- sample category -->
<parentCategory ref="windows:WindowsComponents" />
<seeAlso> policy </seeAlso>
<keywords> Contoso </keywords>
</category>
Additional references
categories Element
categories Element
The categories element is a table of category elements.
Syntax
<categories>
<category … </category>
</categories>
Attributes
There are no attributes associated with this element.
49
Child elements
Element
Required
Description
category Element
Yes
Specifies the name of a
unique category to be
displayed in the Group Policy
Object Editor.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
If there are no category elements to be specified in this .admx file, you can omit the
categories element. If you include the categories element in the .admx file, you must
define at least one category element. The categories element is defined at most once in
an .admx file.
Examples
This XML fragment is an example of a single unique category referencing a string in the
.adml file.
<categories>
<category name="SAMPLE" displayName="$(string.SAMPLE)"
explainText="$(string.SAMPLEHELP)">
<!-- sample category -->
<parentCategory ref="windows:WindowsComponents" />
<seeAlso> policy </seeAlso>
<keywords> custom </keywords>
</category>
</categories>
Additional references
policyDefinitions Element
50
checkBox Element
The checkBox element represents a check box parameter. The checkBox element
must be associated with a boolean element defined in the elements element.
Syntax
<checkBox refId="<placeholderID>"
defaultChecked="true|false"
Placeholder label:</ checkBox >
where Placeholder label is label text for the parameter.
Attributes
Attributes
Required
Description
refId Attribute
Yes
A mapping to the element.
defaultChecked Attribute
No
A default value. If not
specified, the
defaultChecked attribute will
be set to false.
Child elements
There are no child elements associated with this element.
Remarks
The checkBox element is associated with a check box parameter in the Group Policy
Object Editor. The checkBox element will require a matching boolean element in the
corresponding .admx file with matching id attribute as declared in the presentation
element containing the checkBox element.
51
Examples
This XML fragment is an example of two checkBox elements that are associated with
two check box parameters, the second checked by default.
<checkBox refId="Checkbox_1">First check box parameter</checkBox>
<checkBox refId="Checkbox_2" defaultChecked="true">Second check box
parameter - checked by default</checkBox>
Additional references
boolean Element
presentation Element
class Attribute
The class attribute, defined in the .admx file, identifies whether the policy setting will be
located under a single node of the Group Policy Object Editor (computer or user) or both
nodes.
Syntax
class="Machine|User|Both"
where
Machine identifies placement of the policy setting under the computer configuration
node.
User identifies placement of the policy setting under the user configuration node.
Both identifies placement of the policy setting under both the computer and user
configuration nodes.
Examples
This XML fragment identifies a policy setting to be displayed under the computer
configuration node.
class="Machine"
52
Additional references
policy Element
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.
Syntax
clientExtension="<placeholderGUID>"
where the placeholderGUID is a GUID representing a specific client-side extension.
Examples
This XML fragment is used in a boolean, decimal, text, enum, or list element to direct
the disk quota client-side extension to process specified settings.
clientExtension="{3610eda5-77ef-11d2-8dc5-00c04fa31a66}"
Additional references
boolean Element
decimal Element (elements)
text Element
enum Element
list Element
53
comboBox Element
The comboBox element represents a combo box parameter. The comboBox element
must be associated with a text element defined in the elements element.
Syntax
<comboBox refId="<placeholderID>" noSort ="true|false" >
<label> … </label>
<default> … </default>
<suggestion> … </suggestion>
</comboBox>
Attributes
Attributes
Required
Description
refId Attribute
Yes
A mapping to the element.
noSort Attribute
No
If true, display the suggested
values in the defined order of
the suggestion elements;
otherwise, sort the
suggested values in
alphabetical order. If not
specified, the noSort
attribute will be set to false.
Element
Required
Description
label Element
Yes
String label for the
parameter.
default Element
No
A default string displayed in
the combo box parameter.
Child elements
54
Element
Required
Description
suggestion Element
No
A string listed in the dropdown list of the combo box
parameter.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The comboBox element is associated with a combo box parameter in the Group Policy
Object Editor. The comboBox element will require a matching text element in the
corresponding .admx file with matching id attribute as declared in the presentation
element containing the comboBox element.
The label element, default element, and suggestion element must be defined in the
order shown in the syntax section. If the order of the child elements of the comboBox
element is not correctly specified, the Group Policy Object Editor will display an error
message.
Examples
This XML fragment is an example of a comboBox element with default text displayed in
the text box parameter when the policy setting is enabled. The noSort attribute is set to
true which will cause the suggestion elements to be displayed in the same order as
listed in the comboBox element.
<comboBox refId="Sample_ComboBox_Filename" noSort="true" >
<label>Sample Executable File Name</label>
<default>None</default>
<suggestion>Filename A</suggestion>
<suggestion>Filename B</suggestion>
<suggestion>EXECUTABLE.EXE</suggestion>
</comboBox>
Additional references
presentation Element
55
text Element
decimal Element (elements)
The decimal element sets the registry value to the specified numeric value when a policy
setting is enabled through the Group Policy Object Editor. The decimal element
determines whether the registry key will be created as a REG_DWORD or REG_SZ
when storing the numeric value.
Syntax
<decimal id="<placeholderID>"
clientExtension="<placeholderGUID>"
key="<placeholderRegKey>"
valuename="<placeholderName>"
required="true|false"
minValue="<placeholderMinValue>"
maxValue="<placeholderMaxValue>"
storeAsText="true|false"
soft="true|false" />
Attributes
Attributes
Required
Description
id Attribute
Yes
A mapping to the decimal
element.
clientExtension Attribute
No
The client-side extension will
process, on the client
computer, the particular
settings represented by the
decimal element.
key Attribute
No
The registry key location
under which the registry
value will be created.
56
Attributes
Required
Description
valueName Attribute
Yes
The registry value that will
be configured for this
specific policy element.
required Attribute
No
Requirement to enter a
value in the parameter box.
minValue Attribute
No
The minimum allowed value.
maxValue Attribute
No
The maximum allowed
value.
storeAsText Attribute
No
If true, store the decimal
value as a REG_SZ registry
value.
soft Attribute
No
This attribute flags whether
to overwrite an existing
subkey.
Child elements
There are no child elements associated with this element.
Remarks
The decimal element is associated with either a spin box or numeric text entry box
parameter in the Group Policy Object Editor. The decimal element will require a
matching decimalTextBox element in the corresponding .adml file with matching id
attribute as declared in the decimal element.
Examples
This XML fragment is an example of a decimal element thatis associated with a spin
box that uses the default zero minimum value and a maximum value of 599940. The
value will be stored as a text string, REG_SZ.
<decimal id="Sample_NumericTextLabel"
valueName="Example2NumericSpin"
maxValue="599940" storeAsText="true" />
57
Additional references
elements Element
decimalTextBox Element
decimal Element (value)
The decimal element sets a value to an unsigned integer decimal value.
Syntax
<decimal value="X"/>
where value represents an unsigned integer decimal value.
Attributes
Attributes
Required
Description
value Attribute
Yes
Represents a deleted value,
decimal, or string.
Child elements
There are no child elements associated with this element.
Examples
This XML fragment is an example of using the decimal element to set a value to 100.
<decimal value="100"/>
58
Additional references
enabledValue Element
disabledValue Element
value Element
decimalTextBox Element
The decimalTextBox element represents a text box with or without a spin control for
entering decimal numbers as a policy setting parameter. The decimalTextBox element
must be associated with a decimal element defined in the elements element.
Syntax
<decimalTextBox refId="<placeholderID>"
defaultValue="<placeholderNumericValue>"
spin="true|false"
spinStep="<placeholderNumericValue>">
Placeholder label:</decimalTextBox>
where Placeholder label is label text for the parameter.
Attributes
Attributes
Required
Description
refId Attribute
Yes
A mapping to the element.
defaultValue Attribute
No
A default value. If not
specified, the defaultValue
attribute will be set to 1.
spin Attribute
No
If true, create a spin control;
otherwise, create a text box
for numeric entry. This
attribute is true, by default.
59
Attributes
Required
Description
spinStep Attribute
No
The increment of change for
the spin control. If not
specified, the spinStep
attribute will be set to 1.
Child elements
There are no child elements associated with this element.
Remarks
The decimalTextBox element is associated with either a spin box or numeric text box
parameter in the Group Policy Object Editor. The decimalTextBox element will require a
matching decimal element in the corresponding .admx file with matching id attribute as
declared in the presentation element containing the decimalTextBox element.
Examples
This XML fragment is an example of a decimalTextBox element that is associated with a
spin control that displays a default value of 900 and increments or decrements by steps
of 60.
<decimalTextBox refId="Sample_NumericTextLabel"
defaultValue="900"
spinStep="60">Spin box label:</decimalTextBox>
Additional references
decimal Element (elements)
presentation Element
60
default Element
The default element is a localized default displayed when the combo box parameter is
active.
Syntax
<default>Placeholder localized text</default>
Attributes
There are no attributes associated with this element.
Child elements
There are no child elements associated with this element.
Remarks
The default element is optional. You cannot create more than one default element.
Examples
This XML fragment specifies a combo box parameter with a default value, "None".
<comboBox refId="Sample_ComboBox_Filename" noSort="true" >
<label>Sample Executable File Name</label>
<default>None</default>
<suggestion>Filename A</suggestion>
<suggestion>Filename B</suggestion>
<suggestion>EXECUTABLE.EXE</suggestion>
</comboBox>
Additional references
comboBox Element
61
defaultChecked Attribute
The defaultChecked attribute is a Boolean value. If true, the check box parameter is
displayed checked; otherwise, the check box parameter is displayed unchecked.
Syntax
defaultChecked="<true|false>"
where
true represents checked state.
false represents unchecked state.
Remarks
The defaultChecked attribute is an optional attribute and is false by default.
The current behavior of Windows Vista does not match the specified operation of the
defaultChecked attribute. In Windows Vista, all check box parameters are checked, by
default.
Examples
This XML fragment specifies two check box parameters. When the policy setting is
enabled, the first check box is displayed unchecked and the second check box is
displayed checked.
<checkBox refId="Checkbox_1">First check box parameter</checkBox>
<checkBox refId="Checkbox_2" defaultChecked="true">Second check box
parameter - checked by default</checkBox>
Additional references
decimal Element (elements)
text Element
62
defaultItem Attribute
The defaultItem attribute is the numerical value identifying the default choice from the
items in the drop-down list. The item list is numbered starting from 0.
Syntax
defaultItem="<placeholder for unsigned decimal integer number>"
Remarks
The defaultItem attribute is an optional attribute. If the defaultItem attribute is not
specified or is set to a nonexistent item, the drop-down list box will be blank.
Examples
This XML fragment specifies the first item in the drop-down list will be displayed by
default.
defaultItem="0"
Additional references
dropdownList Element
defaultKey Attribute
The defaultKey attribute specifies a default registry subkey for all items in the
enabledList element, disabledList element, or valueList element
Syntax
defaultKey="<placeholder for registry subkey>"
where
63
<placeholder for registry subkey> represents the registry location under which will be
placed the registry entry specified in the item element.
Remarks
If a key attribute is not defined for an item element, the default registry key, defaultKey
attribute, defined for the enabledList element or disabledList element will be used. The
Group Policy Object Editor will display an error if both the defaultKey attribute and the
key attribute for an item element do not exist.
Examples
This XML fragment creates an enabledList element with the item elements relying on
the defaultKey for the registry subkey specification.
<enabledList defaultKey="Software\Policies\Examples">
<item valueName="Example2ActionList1">
<value>
<string>1</string>
</value>
</item>
<item valueName="Example2ActionList2">
<value>
<decimal value="11" />
</value>
</item>
<item valueName="Example2ActionList3">
<value>
<string>String3</string>
</value>
</item>
</enabledList>
Additional references
enabledList Element
disabledList Element
valueList Element
64
defaultValue Attribute
The defaultValue attribute specifies the default numerical value of the parameter. If not
specified, the defaultValue attribute will be set to 1.
Syntax
defaultValue="<placeholder for unsigned decimal integer number>"
Examples
This XML fragment specifies a default spin control parameter or numeric text box
parameter value of 900.
defaultValue="900"
Additional references
decimalTextBox Element
defaultValue Element
The defaultValue element is a localized string initially displayed in the text box
parameter when the policy setting is enabled.
Syntax
<defaultValue>Placeholder localized text</defaultValue>
Attributes
There are no attributes associated with this element.
65
Child elements
There are no child elements associated with this element.
Remarks
The defaultValue element is optional. If specified, the defaultValue element must be
defined after the label element.
Examples
This XML fragment specifies a text box parameter displaying a default string,
"%SYSTEMROOT%\Example".
<textBox refId="Sample_textboxExpandszPrompt">
<label>This text box allows input of environment variables:</label>
<defaultValue>%SYSTEMROOT%\Example</defaultValue>
</textBox>
Additional references
textBox Element
definition Element
The definition element creates the mapping between the logical name to an existing
reference supported on string text in the .adml file.
Syntax
<definition name="<placeholder for logical or friendly name>"
displayName="$(string.<placeholder for supportedOn text>)"/>
Attributes
66
Attributes
Required
Description
name Attribute
Yes
name="<placeholder for logical or
friendly name>"
Specifies a logical name to use for a
specific supported application and
revision.
displayName Attribute
Yes
displayName="$(string.<placeholder
for supportedOn text>)"
The reference to the supported
information string located in the string
table of the .adml file.
Child elements
There are no child elements associated with this element.
Remarks
Group Policy provides a enterprise management of Windows Server 2008,
Windows Vista, Microsoft Windows Server 2003, and Microsoft Windows XP as well as
applications that run on the Windows platform. The enterprise will typically include
multiple versions of operating systems and other applications. In order to administrate for
these different versions, the Group Policy settings cannot be deprecated when a policy
setting no longer applies to the current version operating system or application. Instead of
removing Group Policy settings that apply only to earlier operating systems or
applications, the Group Policy setting remains in the ADMX files and the supportedOn
element is used to specify what operating system or application version is affected by an
individual Group Policy setting.
The definition element can be omitted if the ADMX file only requires Windows operating
system versions or strings from a custom base file for supportedOn text.
Examples
This XML fragment is an example of a single definition of supportedOn text for a specific
product version.
67
<definition name="SUPPORTED_ProductOnly"
displayName="$(string.SUPPORTED_ProductOnly)"/>
Additional references
definitions Element
Referencing the Windows Base ADMX File
Creating a Custom Base ADMX File
definitions Element
The definitions element is a table of definition elements for the supportedOn text.
Syntax
<definitions>
<definition> … </definition>
</definitions>
Attributes
There are no attributes associated with this element.
Child elements
Element
Required
Description
definition Element
No
The definition of the
supported product
information.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
68
Remarks
Group Policy provides enterprise management of Windows Server 2008, Windows Vista,
Microsoft Windows Server 2003, and Microsoft Windows XP as well as applications that
run on the Windows platform. The enterprise will typically include multiple versions of
operating systems and other applications. In order to administrate for these different
versions, the Group Policy settings cannot be deprecated when a policy setting no longer
applies to the current version operating system or application. Instead of removing Group
Policy settings that apply only to earlier operating systems or applications, the Group
Policy setting remains in the ADMX files and the supportedOn element is used to
specify what operating system or application version is affected by an individual Group
Policy setting.
The supportedOn element is an optional element that can be removed if all the
individual Group Policy settings reference the supportedOn elements defined in a
different .admx file. One example of a file containing different supportedOn elements is
the Windows base file, windows.admx.
Examples
This XML fragment is an example of a definitions table containing one supportedOn
element for a specific product version.
<definitions>
<definition name="SUPPORTED_ProductOnly"
displayName="$(string.SUPPORTED_ProductOnly)"/>
</definitions>
Additional references
supportedOn Element
Referencing the Windows Base ADMX File
Creating a Custom Base ADMX File
delete Element
The delete element represents a deleted registry value or key.
69
Syntax
<delete />
Attributes
There are no attributes associated with this element.
Child elements
There are no child elements associated with this element.
Examples
This XML fragment is an example of using the delete element in a list to direct deleting
the registry subkey, Software\Policies\Examples\Example2ActionList3.
</item>
<item key="Software\Policies\Examples"
valueName="Example2ActionList3">
<value>
<delete />
</value>
</item>
Additional references
enabledValue Element
disabledValue Element
value Element
description Element
The description element is the localized description of policy settings contained in the
.adml file.
70
Syntax
<description>localized description text</description>
Attributes
There are no attributes associated with this element.
Child elements
There are no child elements associated with this element.
Remarks
This is an optional element unsupported by Group Policy Object Editor and Group Policy
Management Console.
Examples
This XML fragment is an example of a description element.
<description>This file contains application custom policy
settings.</description>
Additional references
policyDefinitionResources Element.
disabledList Element
The disabledList element is used to set the multiple registry values when a policy setting
is disabled through the Group Policy Object Editor.
Syntax
<disabledList defaultKey="<placeholder for registry subkey>">
71
<item> … </item>
</disabledList>
Attributes
Attributes
Required
Description
defaultKey Attribute
No
Represents a default registry
subkey for all items.
Child elements
Element
Required
Description
item Element
Yes
Represents a registry subkey
with an associated value.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The disabledList element is an optional element. If you use the disabledList element
when defining a policy element, you must define at least one item element. If not, the
Group Policy Object Editor will display an error.
There is no limit to the number of items that can be defined for a single disabledList
element.
Examples
This XML fragment demonstrates the use of the disabledList. The first two registry
subkeys are set to a string value and a decimal value, respectively, when the policy
setting is configured to the disabled state. The third subkey is deleted when the same
policy setting is configured to the disabled state.
72
<disabledList>
<item key="Software\Policies\Examples"
valueName="Example2ActionList1">
<value>
<string>0</string>
</value>
</item>
<item key="Software\Policies\Examples"
valueName="Example2ActionList2">
<value>
<decimal value="10" />
</value>
</item>
<item key="Software\Policies\Examples"
valueName="Example2ActionList3">
<value>
<delete />
</value>
</item>
</disabledList>
Additional references
policy Element
disabledValue Element
The disabledValue element sets the registry value when a policy setting is disabled
through the Group Policy Object Editor.
Syntax
< disabledValue >
<delete /> | <decimal> … </decimal> | <string> … </string>
</ disabledValue >
You must include a choice of either the delete element, decimal element, or string
element.
73
Attributes
There are no attributes associated with this element.
Child elements
Element
Required
Description
delete Element
One of three must be used in
the enabledValue element.
Represents a deleted
registry value or key.
decimal Element
(elements)
One of three must be used in
the enabledValue element.
Represents an unsigned
decimal number.
string Element (.admx)
One of three must be used in
the enabledValue element.
String type limited to 255
characters in length.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The disabledValue element is an optional element. If you use the disabledValue
element when defining a policy element, you must define one child element: delete
element, decimal element, or string element. If not, the Group Policy Object Editor will
display an error.
Examples
This XML fragment is an example of an disabledValue element used to configure a
registry setting value to a decimal value of 0.
<disabledValue>
<decimal value="0" />
</disabledValue>
74
Additional references
policy Element
displayName Attribute
The displayName attribute, defined in the .admx file, is a string value referenced in the
.adml file. This attribute can be used in the category, definition, enum, or policy
element.
Syntax
displayName="$(string.<placeholderTextID>)"
where
placeholderTextID is the unique name for a string text defined in the .adml stringTable
element.
Remarks
The XML notation $(string.<placeholderTextID>) indicates an external reference to the
related .adml file with reference to the string elements for the placeholderTextID.
Examples
This XML fragment displays an example of the displayName attribute referencing a
string for supported text with an ID of SUPPORTED_ProductOnly.
displayName="$(string.SUPPORTED_ProductOnly)"
Additional references
category Element
definition Element
enum Element
75
policy Element
stringTable Element
displayName Element
The displayName element is the localized friendly name of the .adml file.
Syntax
<displayName>localized display name text</displayName>
Attributes
There are no attributes associated with this element.
Child elements
There are no child elements associated with this element.
Remarks
This is an optional element unsupported by Group Policy Object Editor and Group Policy
Management Console.
Examples
This XML fragment is an example of a displayName element.
<displayName> Custom Policy Settings </displayName>
Additional references
policyDefinitionResources Element
76
dropdownList Element
The dropdownList element represents a drop-down listparameter. The dropdownList
element must be associated with an enum element defined in the elements element.
Syntax
<dropdownList refId="<placeholderID>"
noSort="true|false"
defaultItem ="<placeholderNumericValue>">
Placeholder label:</dropdownList>
where Placeholder label is label text for the parameter.
Attributes
Attributes
Required
Description
refId Attribute
Yes
A mapping to the element.
noSort Attribute
No
If true, create a spin
control; otherwise, create a
text box for numeric entry.
This attribute is true, by
default.
defaultItem Attribute
No
The numerical value
identifying the default choice
of the list of items. The item
list is numbered starting
from 0.
Child elements
There are no child elements associated with this element.
77
Remarks
The dropdownList element is associated with a drop-down list parameter in the Group
Policy Object Editor. The dropdownList element will require a matching enum element
in the corresponding .admx file with matching id attribute as declared in the presentation
element containing the dropdownList element.
Examples
This XML fragment is an example of a dropdownList element with the first item in the list
displayed as the default choice.
<dropdownList refId="Sample_Dropdownlist_Box" defaultItem="0">Drop-down
list box choices:</dropdownList>
Additional references
dropdownList Element
presentation Element
elements Element
The 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.
Syntax
<elements>
<boolean> … </boolean>
<decimal> … </decimal>
<text> … </text>
<enum> … </enum>
<list> … </list>
</elements>
78
Attributes
There are no attributes associated with this element.
Child elements
Element
Required
Description
boolean Element
No. At least one element
must be defined.
Represents a choice element
in a policy with associated
values for the true and false
cases.
decimal Element
(elements)
No. At least one element
must be defined.
Represents a
number/decimal element in a
policy. The number can be
defined to be stored as either a
numeric or string
representative value.
text Element
No. At least one element
must be defined.
Represents a text element in a
policy.
enum Element
No. At least one element
must be defined.
Represents an enumeration
element.
list Element
No. At least one element
must be defined.
Represents a list element in a
policy.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
If the elements element is defined, it must contain at least one child element. The
number and type of elements defined in the .admx file must match the presentation
elements defined in the corresponding .adml file.
79
Examples
This XML fragment is an example of the elements specifying two check box parameters.
<elements>
<boolean id="Checkbox_1" valueName="Example2Checkbox1">
<trueValue>
<decimal value="1" />
</trueValue>
<falseValue>
<decimal value="0" />
</falseValue>
</boolean>
<boolean id="Checkbox_2" valueName="Example2Checkbox2">
<trueValue>
<decimal value="0" />
</trueValue>
<falseValue>
<decimal value="1" />
</falseValue>
</boolean>
</elements>
Additional references
policy Element
enabledList Element
The enabledList element is used to set the multiple registry values when a policy setting
is enabled through the Group Policy Object Editor.
Syntax
<enabledList defaultKey="<placeholder for registry subkey>">
<item> … </item>
</enabledList>
Attributes
80
Attributes
Required
Description
defaultKey Attribute
No
Represents a default registry
subkey for all items.
Child elements
Element
Required
Description
item Element
Yes
Represents a registry subkey
with an associated value.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The enabledList element is an optional element. If you use the enabledList element
when defining a policy element, you must define at least one item element. If not, the
Group Policy Object Editor will display an error.
There is no limit to the number of items that can be defined for a single enabledList
element.
Examples
This XML fragment is an example of three registry values set to either a string or decimal
value when a policy setting is configured to the enabled state.
<enabledList>
<item key="Software\Policies\Examples" valueName="Example2ActionList1">
<value>
<string>1</string>
</value>
</item>
<item key="Software\Policies\Examples" valueName="Example2ActionList2">
<value>
<decimal value="11" />
</value>
81
</item>
<item key="Software\Policies\Examples" valueName="Example2ActionList3">
<value>
<string>String3</string>
</value>
</item>
</enabledList>
Additional references
policy Element
enabledValue Element
The enabledValue element sets the registry value when a policy setting is enabled
through the Group Policy Object Editor.
Syntax
<enabledValue>
<delete /> | <decimal> … </decimal> | <string> … </string>
</enabledValue>
You must include a choice of either the delete element, decimal element, or string
element.
Attributes
There are no attributes associated with this element.
Child elements
Element
Required
Description
delete Element
One of three must be used in
the enabledValue element.
Represents a deleted
registry value or key.
82
Element
Required
Description
decimal Element
(elements)
One of three must be used in
the enabledValue element.
Represents an unsigned
decimal number.
string Element (.admx)
One of three must be used in
the enabledValue element.
String type limited to 255
characters in length.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The enabledValue element is an optional element. If you use the enabledValue element
when defining a policy element, you must define one child element: delete, decimal, or
string element. If not, the Group Policy Object Editor will display an error.
Examples
This XML fragment is an example of an enabledValue element used to configure a
registry setting value to a decimal value of 1.
<enabledValue>
<decimal value="1" />
</enabledValue>
Additional references
policy Element
enum Element
The 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 Group Policy Object Editor.
83
Syntax
<enum
id="<placeholderID>"
clientExtension="<placeholderGUID>"
key="<placeholderRegKey>"
valuename="<placeholderName>"
required="true|false" >
<item> … </item>
</enum >
Attributes
Attributes
Required
Description
id Attribute
Yes
A mapping to the enum
element.
clientExtension Attribute
No
The client-side extension will
process, on the client
computer, the particular
settings represented by the
enum element.
key Attribute
No
The registry key location
under which the registry
value will be created.
valueName Attribute
Yes
The registry value that will
be configured for this
specific policy element.
required Attribute
No
Requirement to enter a
value in the parameter box.
Child elements
84
Element
Required
Description
item Element (enum)
No
Represents a set of display
names with one value or a
set of registry subkey values.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The enum element is generally associated with a drop-down list parameter in the Group
Policy Object Editor.
The enum element will require a matching dropdownList element in the corresponding
.adml file with id that matches as declared in the enum element.
Examples
This XML fragment is an example of an enum element thatis associated with a choice of
three values with different display names in a drop-down list.
<enum id="Sample_Dropdownlist_Box"
valueName="Example2DropDownList" required="true">
<item displayName="$(string.Sample_DropDownList_First)">
<value>
<decimal value="1" />
</value>
</item>
<item displayName="$(string.Sample_DropDownList_Second)">
<value>
<decimal value="2" />
</value>
</item>
<item displayName="$(string.Sample_DropDownList_Third)">
<value>
<decimal value="3" />
</value>
</item>
</enum>
85
This XML fragment is an example of an enum element that is associated with a choice
of two sets of values (defined in ADM files as an ACTIONLIST) with different display
names in a drop-down list.
<elements>
<enum id="enum_example" valueName="exampleValueName" required="true">
<item displayName="$(string.displayChoice1)">
<value>
<decimal value="1" />
</value>
<valueList>
<item key="Software\Policies\Examples\1" valueName="1">
<value>
<decimal value="3" />
</value>
</item>
<item key="Software\Policies\Examples\2" valueName="2">
<value>
<decimal value="3" />
</value>
</item>
</valueList>
</item>
<item displayName="$(string.displayChoice2)">
<value>
<decimal value="2" />
</value>
<valueList>
<item key="Software\Policies\Examples\1" valueName="1">
<value>
<decimal value="1" />
</value>
</item>
<item key="Software\Policies\Examples\2" valueName="2">
<value>
<decimal value="3" />
</value>
</item>
</valueList>
</item>
</enum>
</elements>
Additional references
elements Element
dropdownList Element
86
expandable Attribute
The expandable attribute is 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).
Syntax
expandable="<true|false>"
where
true represents expandable string type (REG_EXPAND_SZ) and
false represents string type (REG_SZ)
Remarks
The expandable attribute is an optional attribute, false by default.
Examples
This XML fragment is an example that specifies a text element that will store its value in
a REG_EXPAND_SZ registry subkey.
<text id="Sample_textboxExpandszPrompt"
valueName="Example2TextboxExpandsz"
required="true"
expandable="true" />
Additional references
list Element
text Element
87
explainText Attribute
The explainText attribute, defined in the .admx file, is a string value referenced in the
.adml file representing Help or Explain text for either a category or policy setting.
Syntax
explainText="$(string.<placeholderTextID>)"
where
placeholderTextID is the unique name for a string text defined in the .adml stringTable
element.
Remarks
The XML notation $(string.<placeholderTextID>) indicates an external reference to the
related .adml file with reference to the string elements for the placeholderTextID.
Examples
This XML fragment displays an example of the explainText attribute referencing a string
for supported text with an ID of SAMPLEHELP.
explainText="$(string.SAMPLEHELP)"
Additional references
category Element
policy Element
stringTable Element
88
explicitValue Attribute
The explicitValue attribute is 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.
Syntax
expandable="<true|false>"
where
true represents create a two-column list showing registry subkey name and registry
subkey value and
false represents only apply the new values from the list box.
Remarks
The explicitValue attribute is an optional attribute. The explicitValue attribute will be set
to false, by default. This option cannot be used with the valuePrefix attribute.
Examples
This XML fragment example specifies a list element that appends the existing subkeys to
the ones that would be specified through the list box associated with this list element.
<list id="Sample_ListBox_SingleColumn_Param"
key="Software\Policies\Examples\listbox1"
additive="true" />
Additional references
list Element
valuePrefix Attribute
89
fallbackCulture Attribute
The 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.
Syntax
fallbackCulture="<placeholder for culture/language name>"
Remarks
US English, en-us, is the default fallbackCulture when the fallbackCulture attribute is
not declared in the resources element. For a list of ISO-style language/culture names,
see Locale Identifiers.
Examples
This XML fragment displays an example of a fallbackCulture of US English.
fallbackCulture="en-us"
Additional references
resources Element (.admx)
falseList Element
The falseList element is used to set the multiple registry values when a boolean
element is set to the false state.
Syntax
<falseList defaultKey="<placeholder for registry subkey>">
<item> … </item>
</falseList>
90
Attributes
Attributes
Required
Description
defaultKey Attribute
No
Represents a default registry
subkey for all items.
Child elements
Element
Required
Description
item Element
Yes
Represents a registry subkey
with an associated value.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The falseList element is an optional element. If you use the falseList element when
defining a boolean element, you must define at least one item element. If not, the Group
Policy Object Editor will display an error.
You can define a maximum of one falseList element for a boolean element.
There is no limit to the number of items that can be defined for a single falseList
element.
Examples
This XML fragment demonstrates the use of the falseList. The first two registry subkeys
are set to a string value and a decimal value, respectively, for the boolean element false
state. The third registry subkey is deleted for the boolean element false state.
<falseList>
<item key="Software\Policies\Examples"
valueName="ExamplefalseList1">
<value>
91
<string>0</string>
</value>
</item>
<item key="Software\Policies\Examples"
valueName="ExamplefalseList2">
<value>
<decimal value="10" />
</value>
</item>
<item key="Software\Policies\Examples"
valueName="ExamplefalseList3">
<value>
<delete />
</value>
</item>
</falseList>
Additional references
boolean Element
falseValue Element
The falseValue element sets the registry value for the false condition of a boolean
element.
Syntax
<falseValue>
<delete /> | <decimal> … </decimal> | <string> … </string>
</falseValue>
You must include a choice of either the delete element, decimal element, or string
element.
Attributes
There are no attributes associated with this element.
92
Child elements
Element
Required
Description
delete Element
One of three must be used in
the enabledValue element.
Represents a deleted
registry value or key.
decimal Element
(elements)
One of three must be used in
the enabledValue element.
Represents an unsigned
decimal number.
string Element (.admx)
One of three must be used in
the enabledValue element.
String type limited to 255
characters in length.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The falseValue element is an optional element. If you use the falseValue element when
defining a boolean element, you must define one child element: delete, decimal, or
string element. If not, the Group Policy Object Editor will display an error.
Examples
This XML fragment is an example of a falseValue element used to configure a registry
setting value to a decimal value of 0.
<falseValue>
<decimal value="0" />
</falseValue>
Additional references
boolean Element
93
fileName Attribute
The fileName attribute specifies a valid file name.
Syntax
fileName="<placeholder for file name>"
Remarks
The file name must be specified without a file path.
Examples
This XML fragment displays an example of specifying the example1.adm file.
fileName="example1.adm"
Additional references
supersededAdm Element
id Attribute
The id attribute specifies a string used as a logical name for an element.
Syntax
id="<placeholderID>"
where the placeholderID is a string value.
Examples
This XML fragment identifies a logical name, Checkbox_1, for a boolean element.
94
<boolean id="Checkbox_1" valueName="Example2Checkbox1">
Additional references
boolean Element
decimal Element (elements)
text Element
enum Element
list Element
string Element (.adml)
presentation Element
item Element
The item element represents a singe registry entry and its value.
Syntax
<disabledList>
<item> … </item>
</disabledList>
Attributes
Attributes
Required
Description
key Attribute
No
Represents a registry
subkey.
valueName Attribute
Yes
Represents a registry entry
name.
95
Child elements
Element
Required
Description
value Element
Yes
Represents a registry entry
value.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
If a key attribute is not defined for an item, the default registry key defined for the
enabledList element or disabledList element will be used. The Group Policy Object
Editor will display an error if both the defaultKey attribute and the key attribute for an
item element do not exist.
Examples
This XML fragment demonstrates the use of the item element to set the registry subkey,
Software\Policies\Examples\Example2ActionList1, to a value of 5 stored as a string.
<item key="Software\Policies\Examples"
valueName="Example2ActionList1">
<value>
<string>5</string>
</value>
</item>
Additional references
enabledList Element
disabledList Element
valueList Element
96
item Element (enum)
The item element is a child element of the enum element representing a display name
associated with one single value or a single value with a set of registry subkey values.
Syntax
<item
displayName="$(string.<placeholder for text>)">
<item> … </item>
</item>
Attributes
Attributes
Required
Description
displayName Attribute
Yes
displayName="$(
string.<placeholder for
name>)"
The reference to a display
string located in the .adml file
string table.
Child elements
Element
Required
Description
value Element
Yes
Represents a registry entry
value.
valueList Element
No
A list of items with an
associated registry key and
value.
97
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The key attribute defined in the enum element or policy element will be used to define
the default registry key location for all value elements and valueList elements.
Examples
This XML fragment demonstrates the use of the item element, child element of the enum
element, to configure a single choice for an enum. This could represent one choice from
a drop-down list in the parameter of a policy setting.
<item displayName="$(string.displayChoice1)">
<value>
<decimal value="1" />
</value>
<valueList>
<item key="Software\Policies\Examples\1" valueName="1">
<value>
<decimal value="3" />
</value>
</item>
<item key="Software\Policies\Examples\2" valueName="2">
<value>
<decimal value="3" />
</value>
</item>
</valueList>
</item>
Additional references
enum Element
key Attribute
The key attribute specifies a string that represents the name of the registry subkey
98
Syntax
key="<placeholder for registry key>"
The registry subkey will be specified from the node directly under Administrative
Templates.
Remarks
If a key attribute is not defined for an item element, the default registry key, defaultKey
attribute, defined for the enabledList element or disabledList element will be used. The
Group Policy Object Editor will display an error if both the defaultKey attribute and the
key attribute for an item element do not exist.
Examples
This XML fragment identifies the registry key under which all policy setting's values from
both sample files will be placed.
key="Software\Policies\Examples"
Additional references
policy Element
item Element
keywords Element
The keywords element is a list of searchable keywords associated with categories and
policy settings.
Syntax
<keywords> <placeholder for keywords> </keywords>
99
Attributes
There are no attributes associated with this element.
Child elements
There are no child elements associated with this element.
Remarks
This is an optional element unsupported by Local Group Policy Editor and Group Policy
Management Console.
Examples
This XML fragment is an example of a keyword for the company, Contoso. This keyword
could be used to search for all categories or policy settings specifically developed by the
Contoso company.
<keywords> Contoso </keywords>
Additional references
category Element
policy Element
label Element
The label element is a localized string label for the text box parameter.
Syntax
<label>Placeholder localized text</label>
100
Attributes
There are no attributes associated with this element.
Child elements
There are no child elements associated with this element.
Remarks
The Group Policy Object Editor will display an error if the label element is not the first
child element of the textBox element.
Examples
This XML fragment specifies a text box parameter with a label, "This text box allows
input of environment variables:"
<textBox refId="Sample_textboxExpandszPrompt">
<label>This text box allows input of environment variables:</label>
<defaultValue>%SYSTEMROOT%\Example</defaultValue>
</textBox>
Additional references
textBox Element
comboBox Element
list Element
The list element sets a list of different registry subkeys when a policy setting is enabled
through the Group Policy Object Editor. The list element is generally associated with a
show box parameter in the Group Policy Object Editor.
Syntax
<list
id="<placeholderID>"
101
clientExtension="<placeholderGUID>"
key="<placeholderRegKey>"
valuePrefix="<placeholderName>"
additive="true|false"
expandable="true|false"
explicitValue="true|false" >
</list>
Attributes
Attributes
Required
Description
id Attribute
Yes
A mapping to the list element.
clientExtension Attribute
No
The client-side extension will
process, on the client computer,
the particular settings
represented by the list element.
key Attribute
No
The registry key location under
which the registry value will be
created.
valuePrefix Attribute
Yes
The prefix prepended to an
incremented integer will create
the registry sub-key used in
setting policy values.
additive Attribute
No
If this option is specified true,
existing subkeys are not
deleted, and the values set in
the list box are appended to the
existing subkeys.
expandable Attribute
No
The registry subkey value will
be created as an expandable
string type
(REG_EXPAND_SZ) instead of
a string type (REG_SZ).
102
Attributes
Required
Description
explicitValue Attribute
No
If this option is specified true
the user must specify the
registry subkey value and the
registry subkey name. The list
box shows two columns, one
for the name and one for the
data.
Child elements
There are no child elements associated with this element.
Remarks
The list element will require a matching listBox element in the corresponding .adml file
with id that matches as declared in the list element.
Examples
This XML fragment is an example of using a list element to create a one-column list box
for parameter entry. Each registry subkey name will have "SAMPLE" prepended to its
name.
<list id="Sample_ListBox_SingleColumn_Param"
key="Software\Policies\Examples\listbox1"
valuePrefix="SAMPLE" />
Note
If the valuePrefix attribute is not specified, the registry sub-key name will match
the name of the value entered. If you want the registry sub-keys to be named
with incremental integers only, set the valuePrefix attribute to a null value,
valuePrefix="".
This XML fragment is an example of using a list element to create a two-column list box
for parameter entry.
<list id="Sample_ListBox_DoubleList"
key="Software\Policies\Examples\listbox2"
103
explicitValue="true" />
Additional references
elements Element
listBox Element
listBox Element
The listBox element represents a list parameter. The listBox element must be
associated with a list element defined in the elements element.
Syntax
<listBox refId="<placeholderID>">Placeholder label:</listBox>
where Placeholder label is label text for the parameter.
Attributes
Attributes
Required
Description
refId Attribute
Yes
A mapping to the element.
Child elements
There are no child elements associated with this element.
Remarks
The listBox element is associated with a list parameter in the Group Policy Object
Editor. To open the list, click the show button. The listBox element will require a
matching list element in the corresponding .admx file with matching id attribute as
declared in the presentation element containing the listBox element.
104
Examples
This XML fragment specifies a listBox element with label, "Single Column Title".
<listBox refId="Sample_ListBox_SingleColumn_Param">Single Column
Title</listBox>
Additional references
list Element
presentation Element
maxLength Attribute
The maxLength attribute specifies the maximum number of text characters for a text
element. The default value is 1023.
Syntax
maxLength ="<PlaceholderNumber>"
where
<PlaceholderNumber> is a placeholder for the maximum number of text characters.
Examples
This XML fragment example sets the maximum number of text characters for a text
element to 1024.
<text id="Sample_TextboxPrompt" valueName="Example2textbox"
maxLength="1024"/>
Additional references
text Element
105
maxValue Attribute
The maxValue attribute specifies the maximum value for a decimal element. The default
value is 9999.
Syntax
maxValue="<PlaceholderNumber>"
where
<PlaceholderNumber> is a placeholder for the maximum value.
Remarks
The decimal element is defined as an unsigned element. The largest value allowed for
the maxValue attribute is 9999.
Examples
This XML fragment example sets the maxValue of a decimal element to 60.
<decimal id="Sample_NumericTextLabel"
valueName="Example2NumericText"
required="true"
minValue="10"
maxValue="60" />
Additional references
decimal Element (elements)
106
minRequiredRevision Attribute
The minRequiredRevision attribute determines the minimum version of the .adml file
that will interoperate with the .admx file. The minRequiredRevision is an attribute of the
.admx resources element.
Syntax
minRequiredRevision="<MajorVersion.MinorVersion>"
where
<MajorVersion.MinorVersion> is a placeholder for the revision number.
MajorVersion has the format XXXX where X designates a single decimal digit.
MinorVersion has the format XXXXX where X designates a single decimal digit.
Remarks
The policyDefinitionResources revision attribute works in conjunction with the
minRequiredRevision attribute.
The MajorVersion value of the policyDefinitionResources revision attribute in the
.adml file must be equal to the MajorVersion value of the minRequiredRevision
attribute in the .admx file.
The MinorVersion value of the policyDefinitionResources revision attribute in the
.adml file must be greater than or equal to the MinorVersion value of the
minRequiredRevision attribute in the .admx file.
Examples
This XML fragment displays the revision attribute in the .admx file filled out to the full
number of allowed digits.
minRequiredRevision="1000.12345"
The following examples demonstrate the relationship between the
policyDefinitionResources revision attribute in the .adml file and the
minRequiredRevision attribute in the .admx file. If the minRequiredRevision attribute
in the .admx file equals 1.1 then the policyDefinitionResources revision attribute could
have any value from 1.1 up to but not including 2.0.
107
revision="1.1"
or
revision="1.1001"
to a maximum value of
revision="1.9999"
Additional references
policyDefinitions Element
revision Attribute
minValue Attribute
The minValue attribute specifies the minimum value for a decimal element. The default
value is 0.
Syntax
minValue="<PlaceholderNumber>"
where
<PlaceholderNumber> is a placeholder for the minimum value.
Remarks
The decimal element is defined as an unsigned element. The smallest allowed value for
the minValue attribute is 0.
Examples
This XML fragment example sets the minValue of a decimal element to 10.
<decimal id="Sample_NumericTextLabel"
valueName="Example2NumericText"
required="true"
108
minValue="10"
maxValue="60" />
Additional references
decimal Element (elements)
name Attribute
The name attribute is 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.
Syntax
name="<placeholder for logical or friendly name>"
Remarks
Each name attribute must be unique for a mapping to a string reference within an .admx
file. For example, if you have two policy name strings you want to reference, you cannot
use a single name="policy" to map to each string. Instead they must be unique; for
example, name="policy1" and name="policy2" to reference the policy string names.
Examples
This XML fragment displays an example of name attribute used for a supportedOn text
string logical name.
name="SUPPORTED_ProductOnly"
Additional references
category Element
definition Element
109
policy Element
namespace Attribute
The namespace attribute specifies the URI used to identify the elements within an ADMX
file.
Syntax
namespace="<placeholder for URI>"
Remarks
Each URI for an ADMX file must be unique from all other ADMX files. For example,
"Microsoft.Policies.Example1" cannot be defined as a namespace for more than one
ADMX file. However, a URI can be referred to from one ADMX file to another with the
using element. The URI follows .NET framework naming guidelines (for example, use
"InternetExplorer," but not "ie," "inet," or "internetexplorer").
Examples
This XML fragment displays an example of a namespace for the example1.admx file.
namespace="Microsoft.Policies.Example1"
Additional references
target Element
using Element
110
noSort Attribute
The noSort attribute is 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.
Syntax
noSort="<true|false>"
where
true represents display the suggested values in the defined order of the suggestion
elements.
false represents display in alphabetical or numerical order.
Remarks
The noSort attribute is an optional attribute, false by default.
Examples
This XML fragment specifies a comboBox element that will display the list of
suggestions in elemental order.
<comboBox refId="Sample_ComboBox_Filename" noSort="true" >
<label>Sample Executable File Name</label>
<default>None</default>
<suggestion>Filename A</suggestion>
<suggestion>Filename B</suggestion>
<suggestion>EXECUTABLE.EXE</suggestion>
</comboBox>
Additional references
comboBox Element
dropdownList Element
111
parentCategory Element
The parentCategory element specifies the location of the category in relationship to its
parent category in the Group Policy Object Editor tree structure.
Syntax
<parentCategory ref="<placeholderNamespace>:<placeholderLogicalName>" />
Attributes
Attributes
Required
Description
ref Attribute
Yes
ref="<placeholderNamespace>:<placeholderLogicalName>"
References a previously defined category.
Child elements
There are no child elements associated with this element.
Remarks
If the parentCategory element is omitted, the Group Policy Object Editor will display the
category element under the Administrative Templates node. You cannot define more
than one parentCategory for a category element.
Examples
This XML fragment is an example of a custom parentCategory element that is assumed
to be declared inside the same .admx file as the element being referenced.
<parentCategory ref="SAMPLE" />
This XML fragment is an example of how to define a parentCategory element
referencing the category defined in the Windows base file, Windows.admx.
112
<parentCategory ref="windows:WindowsComponents" />
Additional references
category Element
policy Element
Referencing the Windows Base ADMX File
Creating a Custom Base ADMX File
policy Element
The policy element corresponds to a single Group Policy setting displayed in the Group
Policy Object Editor. The policy element describes all of the information about the policy
setting, but includes a reference to the parameter definition.
Syntax
The syntax of the policy element declaration is:
<policy name="="<placeholder for logical or friendly name>"
class="Machine|User|Both"
displayName="$(string.<placeholder for category text>)"
explainText="$(string.<placeholder for help text>)"
presentation="$(presentation.<parameter placeholder>)"
key="<placeholder for registry key>"
valueName="<placeholder for registry valuename>">
<parentCategory> … </parentCategory>
<supportedOn> … </supportedOn>
<enabledValue> … </enabledValue>
<disabledValue> … </disabledValue>
<enabledList> … </enabledList>
<disabledList> … </disabledList>
<elements> … </elements>
</policy>
Attributes
113
Attributes
Required
Description
name Attribute
Yes
name="<placeholder for logical or
friendly name>"
Specifies a logical name to use for a
specific supported application and revision.
class Attribute
Yes
Identifies whether the policy will be located
under a single node of the Group Policy
Object Editor (computer or user) or both
nodes. The class attribute can be defined
as "User," "Machine," or "Both."
displayName Attribute
Yes
displayName="$( string.<placeholder for
category text>)"
The reference to the policy setting title text
string located in the string table of the .adml
file.
explainText Attribute
No
explainText="$( string.<placeholder for
help text>)">
Explain or Help text associated with a
specific policy setting.
presentation Attribute
No
presentation="$(presentation.<parameter
placeholder>)"
An identifier used to reference the localized
portions of the parameter definition located
in the presentation table of the .adml file.
key Attribute
Yes
The registry key location under which the
registry value will be created.
valueName Attribute
No
The registry value that will be configured for
this specific policy element.
Child elements
114
Element
Required
Description
parentCategory Element
Yes
Reference to parent of the
current category.
seeAlso Element element
No
Reference to another
element that may be related.
This element is not
supported and will be
ignored by current Group
Policy.
keywords Element
No
Contains index words that
could be used to search for
elements. This element is
not supported and will be
ignored by current Group
Policy tools.
supportedOn Element (policy) No
supportedOn logical name
as defined in the
supportedOn element for
this file.
enabledValue Element
No
A decimal or string value
representing the enabled
value of the registry
valueName element.
disabledValue Element
No
A decimal or string value
representing the disabled
value of the registry
valueName element.
enabledList Element
No
A set of decimal or string
values and registry keys
representing the enabled
state of the policy element.
disabledList Element
No
A set of decimal or string
values and registry keys
representing the disabled
state of the policy element.
115
Element
Required
Description
elements Element
No
One of five parameters types
that can be set in a policy
setting.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
One thing to keep in mind when declaring a policy element is that you have the freedom
to mix and match the elements for enabling and disabling the policy element. For
example, you can declare an enabledValue with a disabledList element. You do not
have to match the enabledValue with a disabledValue or an enabledList with a
disabledList.
You can even define a policy element with only a parameter to the policy element
through the presentation attribute. This will have the net effect of only setting a registry
value when the policy is enabled with a set parameter. In this case, you will still need to
define a registry key as a policy attribute, even though the registry key will be
determined through the parameter definition via the referenced presentation table entry.
Examples
This XML fragment is an example of a single policy element that defines a policy setting
configured to a string value based on the enabled or disabled state.
<policy name="Sample_NoParamPolicy" class="Both"
displayName="$(string.Sample_NoParamPolicy)"
explainText="$(string.Sample_NoParamPolicy_Help)" key="Software\Policies\Examples"
valueName="Example1NoParam">
<parentCategory ref="SAMPLE" />
<supportedOn ref="SUPPORTED_ProductOnly" />
<enabledValue>
<decimal value="1" />
</enabledValue>
<disabledValue>
<decimal value="0" />
</disabledValue>
</policy>
116
This XML fragment is an example of a policy element that contains only a text input
box parameter definition declared through the elements element.
<policy name="Sample_Textbox" class="User"
displayName="$(string.Sample_Textbox)"
explainText="$(string.Sample_Textbox_Help)"
presentation="$(presentation.Sample_Textbox)"
key="Software\Policies\Examples">
<parentCategory ref="TEXTBOX_CATEGORY" />
<supportedOn ref="SUPPORTED_ProductOnly" />
<elements>
<text id="Sample_TextboxPrompt" valueName="Example2textbox" />
</elements>
</policy>
Additional references
policies Element
policyDefinitionResources Element
The policyDefinitionResources element is the document element for an .adml file that
defines all the localized resource information with a single language/culture per file for
each supported language/culture setting. The policyDefinitionResources element also
declares a default namespace for all of the elements in the .adml file.
Syntax
<policyDefinitionResources xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
revision="<MajorVerison.MinorVersion>" schemaVersion="<MajorVerison.MinorVersion>"
xmlns= "http://schemas.microsoft.com/GroupPolicy/2006/07/PolicyDefinitions" >
<displayName> … </displayName>
<description> … </description>
<annotation> … </annotation>
<resources> … </resources>
</policyDefinitionResources>
Attributes
117
Attributes
Required
Description
xmlns Attribute
No
xmlns:xsd
="http://www.w3.org/2001/XMLSchema"
Designation for elements and data types used
in the schema that comes from the
"http://www.w3.org/2001/XMLSchema"
namespace. This attribute is typed as shown.
xmlns Attribute
No
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
Designation for the "XML Schema Instance"
namespace available is from the
"http://www.w3.org/2001/XMLSchemainstance" namespace. This attribute is typed as
shown.
revision Attribute
Yes
revision="<MajorVerison.MinorVersion>"
Version of the .admx file for tracking purposes.
schemaVersion
Attribute
Yes
xmlns Attribute
No
schemaVersion="<MajorVerison.MinorVersion>"
Schema version used by the Group Policy
tools. For Windows Vista and Windows
Server 2008 schemaVersion must be set as
follows; schemaVersion="1.0"
The Group Policy schema namespace.
Note
The Group Policy tools will successfully consume the .adml file that does not
include the xmlns:xsd, xmlns:xsi, and xmlns attributes. The .adml file may not
validate as a fully-formed XML file if the xmlns:xsd, xmlns:xsi, and xmlns
attributes are not included in the .adml file.
Child elements
118
Element
Required
Description
displayName Element
Yes
The localized friendly name of
the .adml file.
description Element
No
The localized description of
policy settings contained in the
.adml file.
annotation Element
Yes
A localized comment at the
beginning of the .adml file.
resources Element (.adml)
No
Contains the stringTable and
presentationTable elements
for specific MUI languages.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
Because the policyDefinitionResources element is the document element, it contains
all the other elements in the document representing the .adml file. The XML declaration is
not part of the document element.
Examples
This XML fragment is the corresponding localized resources for the single policy setting
example in the policyDefinitions element.
<?xml version="1.0" encoding="utf-8"?>
<policyDefinitionResources xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" revision="1.0"
schemaVersion="1.0" xmlns="
http://schemas.microsoft.com/GroupPolicy/2006/07/PolicyDefinitions ">
<displayName>enter display name here</displayName>
<description>enter description here</description>
<resources>
<stringTable>
<string id="SAMPLE">Example 1 - Simplest single Group Policy
setting</string>
<string id="Sample_NoParamPolicy">Set state only</string>
<string id="Sample_NoParamPolicy_Help">This is an example of a Group Policy
119
setting that only sets a value for the enabled, disabled states.
If you enable this setting, the Example1NoParam value will be set to 1.
If you disable this setting, the Example1NoParam will be set to 0.
If you do not configure this setting, the value will be deleted, if currently set
to a value.</string>
<string id="SAMPLEHELP">Example 1
Contains an example of the simplest policy setting that can be created.
This will be displayed as both a machine and user policy setting.</string>
<string id="SUPPORTED_ProductOnly">Only works on placeholder
product</string>
</stringTable>
</resources>
</policyDefinitionResources>
Additional references
XML declaration
policyDefinitions Element
The policyDefinitions element is the document element for an .admx file that defines a
set of registry-policy settings. The policyDefinitions element also declares a default
namespace for all of the elements in the .admx file.
Syntax
<policyDefinitions xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
revision="<MajorVerison.MinorVersion>" schemaVersion="<MajorVerison.MinorVersion>"
xmlns=" http://schemas.microsoft.com/GroupPolicy/2006/07/PolicyDefinitions" >
<policyNamespaces> … </policyNamespaces>
<supersededAdm> … </supersededAdm>
<resources> … </resources>
<supportedOn> … </supportedOn>
<categories> … </categories>
<policies> … </policies>
</policyDefinitions>
120
Attributes
Attributes
Required
Description
xmlns Attribute
No
xmlns:xsd
="http://www.w3.org/2001/XMLSchema"
Designation for elements and data types used
in the schema that comes from the
"http://www.w3.org/2001/XMLSchema"
namespace. This attribute is typed as shown.
xmlns Attribute
No
xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"
Designation for the XML Schema Instance
namespace available is from the
"http://www.w3.org/2001/XMLSchemainstance" namespace. This attribute is typed as
shown.
revision Attribute
Yes
revision="<MajorVerison.MinorVersion>"
Version of the .admx file for tracking purposes.
schemaVersion
Attribute
Yes
xmlns Attribute
No
schemaVersion="<MajorVerison.MinorVersion>"
Schema version used by the Group Policy
tools. For Windows Vista and Windows
Server 2008 schemaVersion must be set as
follows; schemaVersion="1.0"
The Group Policy schema namespace.
Note
The Group Policy tools will successfully consume the .admx file that does not
include the xmlns:xsd, xmlns:xsi, and xmlns attributes. The .admx file may not
validate as a fully-formed XML file if the xmlns:xsd, xmlns:xsi, and xmlns
attributes are not included in the .admx file.
Child elements
121
Element
Required
Description
policyNamespaces Element
Yes
Contains mappings of
.admx files to unique
namespaces.
supersededAdm Element
No
Reference to the file name
for an .adm file. Group
Policy Object Editor will not
read any .adm file
designated as superseded.
resources Element (.admx)
Yes
Contains the required
minimum revision of the
.adml file.
supportedOn Element
No
Mapping of products and
definitions.
categories Element
No
Contains a list of categories
under which Group Policy
settings will be displayed in
the Group Policy Object
Editor and the Group Policy
Management Console.
policies Element
No
Contains a list of policy
setting definitions.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
Because the policyDefinitions element is the document element, it contains all the
other elements in the document representing the .admx file. The XML declaration is not
part of the document element.
122
Examples
This XML fragment is an example of a single policy setting to configure a registry-based
value with numeric values for the enabled and disabled policy states. If the policy setting
state is changed from a defined state to the not configured policy state, the existing
registry value will be deleted when Group Policy is processed.
<policyDefinitions xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" revision="0.9"
schemaVersion="1.0"
xmlns="http://www.microsoft.com/GroupPolicy/PolicyDefinitions">
<policyNamespaces>
<target prefix="example1_singlepolicysetting"
namespace="Microsoft.Policies.Example1_singlepolicysetting" />
</policyNamespaces>
<supersededAdm fileName="example1_singlepolicysetting.adm" />
<resources minRequiredRevision="0.9" />
<supportedOn>
<definitions>
<definition name="SUPPORTED_ProductOnly"
displayName="$(string.SUPPORTED_ProductOnly)"/>
</definitions>
</supportedOn>
<categories>
<category name="SAMPLE" displayName="$(string.SAMPLE)"
explainText="$(string.SAMPLEHELP)" />
</categories>
<policies>
<policy name="Sample_NoParamPolicy" class="Both"
displayName="$(string.Sample_NoParamPolicy)"
explainText="$(string.Sample_NoParamPolicy_Help)" key="Software\Policies\Examples"
valueName="Example1NoParam">
<parentCategory ref="SAMPLE" />
<supportedOn ref="SUPPORTED_ProductOnly" />
<enabledValue>
<decimal value="1" />
</enabledValue>
<disabledValue>
<decimal value="0" />
</disabledValue>
</policy>
</policies>
</policyDefinitions>
Additional references
XML declaration
123
policyNamespaces Element
The 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.
Syntax
<policyNamespaces>
<target> … </target>
<using> … </using>
</policyNamespaces>
Attributes
There are no attributes associated with this element.
Child elements
Element
Required
Description
target Element
Yes
Defines the unique name for the
policy namespace in an .admx
file.
using Element
No
References an existing category
or supportedOn name from a
different policyNamespace.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
ADMX files treat all elements defined within a specific policyNamespace as a unique
name. Using a category element name in multiple ADMX files will cause duplicate
category nodes to be displayed in the Group Policy Object Editor. See the using Element
124
section for more information about avoiding duplicate nodes within the Group Policy
Object Editor.
Examples
This XML fragment is an example of the "policy" namespace definition and one reference
to the windows.admx base file in order to use existing category and supportedOn text
definitions.
<policyNamespaces>
<target prefix="example" namespace="Microsoft.Policies.Example" />
<using prefix="windows" namespace="Microsoft.Policies.Windows" />
</policyNamespaces>
Additional references
policyDefinitions Element
policies Element
The policies element is a table of policy elements.
Syntax
<policies>
<policy> … </policy>
</policies>
Attributes
There are no attributes associated with this element.
Child elements
125
Element
Required
Description
policy Element
Yes
Represents a single policy
setting.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
If there are no policy elements to be specified in this .admx file, you can omit the policies
element. If you include the policies element in the .admx file, you must define at least
one policy element. The policies element is defined at most once in an .admx file.
Examples
This XML fragment is an example of a single unique policy setting that sets a registry
value to a decimal number, based on the policy setting enabled, disabled, or not
configured state.
<policies>
<policy name="<placeholder for logical or friendly name>"
displayName="$( string.<placeholder for policy text>)"
explainText="$( string.<placeholder for help text>)"
key="<placeholder for registry key>"
valueName="Example1NoParam">
<parentCategory ref="SAMPLE" />
<supportedOn ref="SUPPORTED_ProductOnly" />
<enabledValue>
<decimal value="1" />
</enabledValue>
<disabledValue>
<decimal value="0" />
</disabledValue>
</policy>
</policies>
Additional references
policyDefinitions Element
126
prefix Attribute
The prefix attribute specifies the logical name that refers to the namespace within the
current or referenced ADMX file.
Syntax
prefix="<placeholder for logical or friendly name>"
Remarks
The prefix attribute must be unique within this ADMX file. It is a good idea to keep this
name unique to all ADMX files to avoid confusion. One method for naming the logical
name is to use the ADMX file name as the logical name; for example, use example1 as
the prefix in the example1.ADMX file.
Examples
This XML fragment displays an example of a prefix attribute.
prefix="example1"
Additional references
target Element
using Element
presentation Attribute
The presentation attribute, defined in the .admx file, is a presentation value referenced
in the .adml file representing the localized portions of a policy setting parameter.
Syntax
presentation="$(presentation.<placeholderTextID>)"
127
where
placeholderTextID is the unique name for the localized portions of a policy setting
parameter as defined in the .adml presentationTable element.
Remarks
For example, a check box parameter will need a localized label for the check box in the
policy setting display. The presentation attribute will provide a reference to the correct
localized text for the check box label.
The XML notation $(presentation.<placeholderTextID>) indicates an external reference
to the related .adml file with reference to the presentation elements for the
placeholderTextID.
Examples
This XML fragment displays an example of the presentation attribute referencing a
presentation element for the localized portions of a check box parameter.
presentation="$(presentation.Sample_Checkbox)"
Additional references
policy Element
presentation Element
The presentation element corresponds to the parameters for a single Group Policy
setting displayed in the Group Policy Object Editor.
Syntax
The syntax of the presentation element declaration is:
<presentation id="<placeholder for logical or friendly name>">
<text> … </text>
<decimalTextBox> … </decimalTextBox>
<textBox> … </textBox>
128
<checkBox> … </checkBox>
<comboBox> … </comboBox>
<dropdownList> … </dropdownList>
<listBox> … </listBox>
</presentation>
Attributes
Attributes
Required
Description
id Attribute
Yes
Specifies a logical name
when referencing the
presentation information for a
specific policy setting.
Child elements
Element
Required
Description
text Element (presentation)
Yes
A localized string. Used for
defining text located above
and below the parameter
input.
decimalTextBox Element
No
Represents a text box with
or without a spin control
for entering decimal
numbers as a policy setting
parameter. Must be
associated with a decimal
element defined in the
elements element.
textBox Element
No
Represents a text box
parameter. Must be
associated with a text
element defined in the
elements element.
129
Element
Required
Description
checkBox Element
No
Represents a check box
parameter. Must be
associated with a boolean
element defined in the
elements element.
comboBox Element
No
Represents a combo box
parameter with default or
suggested entries. Must be
associated with a text
element as defined in the
elements element.
dropdownList Element
No
Represents a drop-down
list parameter with which a
user can pick one of the
displayed entries. Must be
associated with an enum
element defined in the
elements element.
listBox Element
No
Represents a list box
parameter with Add and
Remove buttons. This is
the only parameter that can
be used to manage multiple
values under one key. Must
be associated with a list
element defined in the
elements element.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The child elements specified in the presentation element must correspond to those
defined in the elements element of the .admx file. The Group Policy Object Editor will
130
display an error if there is not a matching presentation child element for an existing
elements child element.
Examples
This XML fragment is an example of a presentation element that contains the
corresponding elements for a text box parameter declared through the elements
element.
<presentation id="Sample_Textbox">
<textBox refId="Sample_TextboxPrompt">
<label>Prompt label for textbox</label>
</textBox>
</presentation>
Additional references
presentationTable Element
elements Element
presentationTable Element
A table of presentation elements representing the layout of parameter controls for
individual Group Policy settings. The layout of parameter controls include: type of
parameter entry mechanism (edit box, spin control, drop-down box, 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.
Syntax
<presentationTable>
<presentation> … </presentation>
</presentationTable>
Attributes
There are no attributes associated with this element.
131
Child elements
Element
Required
Description
presentation Element
Yes
Represents the display
information of the
parameters for a policy
setting.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
If there are no presentation elements to be specified in the .adml file, you can omit the
presentationTable element. If you include the presentationTable element in the .adml
file, you must define at least one presentation element. The presentationTable element
is defined at most once in an .adml file.
Examples
The XML fragment is an example a set of parameters for multiple policy settings.
<presentationTable>
<presentation id="Sample_Checkbox">
<checkBox refId="Checkbox_1">First check box</checkBox>
<checkBox refId="Checkbox_2"
defaultChecked="true">2nd check box</checkBox>
</presentation>
<presentation id="Sample_ComboBox">
<comboBox refId="Sample_ComboBox_Filename">
<label>Sample Executable File Name</label>
<suggestion>Filename A</suggestion>
<suggestion>Filename B</suggestion>
<suggestion>EXECUTABLE.EXE</suggestion>
</comboBox>
</presentation>
<presentation id="Sample_DropDownList">
<dropdownList refId="Sample_Dropdownlist_Box"
defaultItem="0">Drop-down list box choices:</dropdownList>
</presentation>
<presentation id="Sample_ListBox_DoubleColumn">
132
<text>Prompt text can be added above the listbox.</text>
<text>Enter an item name paired with a value.</text>
<text> </text>
<listBox refId="Sample_ListBox_DoubleList">name pair:</listBox>
<text> </text>
<text>Possible values:</text>
<text>value1 stored as a string representing action 1</text>
<text>value2 stored as a string representing action 2</text>
</presentation>
<presentation id="Sample_ListBox_SingleColumn">
<listBox refId="Sample_ListBox_SingleColumn_Param">Single Column
Title</listBox>
</presentation>
<presentation id="Sample_NumericSpin">
<text>These are optional lines of text that provide</text>
<text>additional help text within the parameter display.</text>
<text> </text>
<decimalTextBox refId="Sample_NumericTextLabel"
defaultValue="900"
spinStep="60">Spin box label:</decimalTextBox>
</presentation>
<presentation id="Sample_NumericText">
<text>These are optional lines of text that provide</text>
<text>additional help text within the parameter display.</text>
<text> </text>
<decimalTextBox refId="Sample_NumericTextLabel">Spin box
label:</decimalTextBox>
</presentation>
<presentation id="Sample_Textbox">
<textBox refId="Sample_TextboxPrompt">
<label>Prompt label for textbox</label>
</textBox>
</presentation>
<presentation id="Sample_textboxExpandsz">
<textBox refId="Sample_textboxExpandszPrompt">
<label>This text box allows input of environment variables:</label>
<defaultValue>%SYSTEMROOT%\Example</defaultValue>
</textBox>
</presentation>
</presentationTable>
Additional references
resources Element (.adml)
133
ref Attribute
The ref attribute references a logical name for the parent category.
Syntax
ref="<placeholderNamespace>:<placeholderLogicalName>"
where
placeholderNamespace is the unique name for a namespace where the LogicalName
is defined, if not in the current namespace. This is an optional definition of the ref
attribute
placeholderLogicalName is the logical name of the parent category or supportedOn
text to be referenced in the .adml file stringTable element.
Remarks
The LogicalName will be assumed to be part of the current .admx file namespace unless
specified in the ref statement.
Examples
This XML fragment is an example of a reference to a logical category name defined
within the same .admx file.
<parentCategory ref="SAMPLE" />
This XML fragment is an example of a reference to a logical category name defined in a
different .admx file; for example, the Windows base file, Windows.admx. The Windows
base file uses a unique namespace, referred to using the prefix "windows".
<parentCategory ref="windows:WindowsComponents" />
Additional references
parentCategory Element
policy Element
134
stringTable Element
supportedOn Element (policy)
refId Attribute
The 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.
Syntax
refId="<placeholderID>"
where placeholderID is a string value.
Examples
This XML fragment identifies a logical name, Sample_ListBox_SingleColumn_Param,
for a listBox element.
<listBox refId="Sample_ListBox_SingleColumn_Param">Single Column
Title</listBox>
Additional references
decimalTextBox Element
textBox Element
checkBox Element
comboBox Element
dropdownList Element
listBox Element
135
required Attribute
The required attribute specifies a Boolean value that represents whether a value must
be specified for the parameter.
Syntax
required="true|false"
where the required attribute is specified as true or false. This is an optional attribute. The
required attribute default value is false.
Examples
This XML fragment identifies an enum element representing a drop-down list where a
value must be selected when the policy setting is enabled.
<enum id="Sample_Dropdownlist_Box" valueName="Example2DropDownList"
required="true">
Additional references
decimal Element (elements)
text Element
enum Element
resources Element (.adml)
The resources element in the .adml file contains the stringTable and
presentationTable elements for specific MUI languages.
Syntax
<resources>
<stringTable>…</stringTable>
<presentationTable>…</presentationTable>
136
</resources>
Attributes
There are no attributes associated with this element.
Child elements
Element
Required
Description
presentationTable Element
No
A table of presentation
elements representing
parameter controls in a
single Group Policy setting.
stringTable Element
No
A table of referenced
localized strings.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The .adml file resources element contains all of the language strings and parameter
presentation information needed by the .admx file. There is only one resources element
for each .adml file.
Examples
This XML fragment provides an example of a resource element containing the text and
presentation information for a single policy setting containing check boxes.
<resources>
<stringTable>
<string id="CHECKBOXTWOTYPES_CATEGORY">Checkbox example</string>
<string id="SAMPLE">Example 2 Policy settings</string>
<string id="Sample_Checkbox">Sets policy setting parameter via a check
box</string>
137
<string id="Sample_Checkbox_Help">This is an example of a Group Policy
setting that configures a parameter using a check box.
If you enable this policy setting, check box1 and check box2 will be active.
Note: Check box2 will be checked by default.
If you disable this policy setting, no check box will be active.
If you do not configure this policy setting, the value will be deleted, if
currently set to a value.
Note: This policy setting changes the Example2Checkbox1 and Example2Checkbox2
registry values.</string>
</stringTable>
<presentationTable>
<presentation id="Sample_Checkbox">
<checkBox refId="Checkbox_1">First check box parameter</checkBox>
<checkBox refId="Checkbox_2" defaultChecked="true">Second check box
parameter - checked by default</checkBox>
</presentation>
</presentationTable>
</resources>
Additional references
policyDefinitionResources Element
resources Element (.admx)
The resourceselement, in the .admx file, specifies the minimum revision level of the
matching .adml file and optionally the fallback language to use.
Syntax
<resources minRequiredRevision="<MajorVersion.MinorVersion>"
fallbackCulture="<placeholder for culture/language name>"/>
Attributes
138
Attributes
Required
Description
minRequiredRevision
Attribute
Yes
minRequiredRevision="<MajorVersion.MinorVersion>"
fallbackCulture
Attribute
No
A minimum revision level of the matching .adml file.
fallbackCulture="<placeholder for
culture/language name>"
Default language to use when the .adml file does not
exist on the machine or ADMX central store for the
required language.
Child elements
There are no child elements associated with this element.
Remarks
The .admx file specifies all the language independent declarations for the ADMX files.
The .admx file references language resources, such as UI display strings, from the .adml
file. The minimum revision value guarantees the .admx file will not be referencing
information that does not exist in the .adml file.
US English, en-us, is the default fallbackCulture when the fallbackCulture attribute is
not declared in the resources element.
Examples
This XML fragment is an example of specifying a minimum required version of .9 for the
.adml file with the default fallbackCulture, en-us.
<resources minRequiredRevision="0.9" />
Additional references
policyDefinitions Element
139
revision Attribute
The revision attribute provides a method of tracking changes made to the .admx or
.adml file.
Syntax
revision="<MajorVersion.MinorVersion>"
where
<MajorVersion.MinorVersion> is a placeholder for the revision number.
MajorVersion has the format XXXX where X designates a single decimal digit.
MinorVersion has the format XXXXX where X designates a single decimal digit.
Remarks
The revision attribute exists for both the .admx and .adml files. The revision attributes'
values can be incremented independently of each other
The policyDefinitionResources revision attribute works in conjunction with the
minRequiredRevision attribute. The MajorVersion value of the revision attribute in the
.adml file must be equal to the MajorVersion value of the minRequiredRevision
attribute in the .admx file.
The MinorVersion value of the revision attribute in the .adml file must be greater than or
equal to the MinorVersion value of the minRequiredRevision attribute in the .admx file.
Examples
This XML fragment displays the revision attribute in the .admx file filled out to the full
number of allowed digits.
revision="1000.12345"
The following examples demonstrate the relationship between the revision attribute in the
.adml file and the minRequiredRevision attribute in the .admx file. If the
minRequiredRevision attribute in the .admx file equals 1.1, then the revision attribute
could have any value from 1.1 up to but not including 2.0.
revision="1.1"
140
or
revision="1.1001"
to a maximum value of
revision="1.99999"
Additional references
minRequiredRevision Attribute
policyDefinitions Element
policyDefinitionResources Element
schemaVersion Attribute
The schemaVersion attribute specifies the ADMX schema verison that the .admx and
.adml files conform to.
Syntax
schemaVersion="<MajorVersion.MinorVersion>"
where
<MajorVersion.MinorVersion> is a placeholder for the schema version number.
MajorVersion has the format XXXX where X designates a single decimal digit.
MinorVersion has the format XXXXX where X designates a single decimal digit.
Remarks
The schemaVersion attribute is used by the Group Policy tools to determine if the ADMX
files are in a format that the Group Policy tools support. For Windows Vista and Windows
Server 2008 the schemaVersion must be set as follows; schemaVersion="1.0"
141
Examples
This XML fragment displays the schemaVersion attribute value that is used to represent
the schema supported by the Windows Vista and Windows Server 2008 Group Policy
tools.
schemaVersion="1.0"
Additional references
policyDefinitions Element
policyDefinitionResources Element
seeAlso Element
The seeAlso element is a descriptive phrase that can be used to reference related
categories or policy settings.
Syntax
<seeAlso> <placeholder for text description> </seeAlso>
Attributes
There are no attributes associated with this element.
Child elements
There are no child elements associated with this element.
Remarks
This is an optional element unsupported by the Group Policy Object Editor and the Group
Policy Management Console.
142
Examples
This XML fragment is an example of a seeAlso element containing the phrase "policy."
<seeAlso> policy </seeAlso>
Additional references
category Element
policy Element
soft Attribute
The soft attribute is a Boolean value. If true, a registry value will not overwrite a
previously set value; otherwise, registry values will always be saved.
Syntax
soft="<true|false>"
where
true represents only apply the registry value if no current value exists.
false represents always apply the registry value.
Remarks
The soft attribute is an optional attribute, false by default. This attribute can be used in
cases where you might use Group Policy to set a user configurable option for an
application. Group Policy would then predefine the option if the user had not already
configured it.
Examples
This XML fragment specifies a decimal element that will store its value in a
REG_DWORD registry value if it doesn't currently exist.
<decimal id="Sample_NumericTextLabel"
143
valueName="ExampleAppConfig"
soft="true" />
Additional references
decimal Element (elements)
text Element
spin Attribute
The spin attribute is a Boolean value. If true, a spin control is created in addition to the
numeric text box; otherwise, a numeric text box is created.
Syntax
spin="<true|false>"
where
true represents a spin control is created in addition to the numeric text box and
false represents a numeric text box is created.
Remarks
The spin attribute is an optional attribute, true by default.
Examples
This XML fragment specifies a decimalTextBox element that creates a spin control and
numeric text box. Notice the spin attribute does not need to be specified.
<decimalTextBox refId="Sample_NumericTextLabel" defaultValue="900"
spinStep="60">Spin box label:</decimalTextBox>
This XML fragment specifies the same spin control and numeric text box as in the first
example. This fragment includes the spin attribute.
144
<decimalTextBox refId="Sample_NumericTextLabel" spin="true"
defaultValue="900" spinStep="60">Spin box label:</decimalTextBox>
This XML fragment specifies a numeric text box without the spin control.
<decimalTextBox refId="Sample_NumericTextLabel" spin="false" >Spin box
label:</decimalTextBox>
Additional references
decimalTextBox Element
spinStep Attribute
The spinStep attribute specifies the increment of change for the spin control. If not
specified, the spinStep attribute will be set to 1.
Syntax
spinStep="<placeholder for unsigned decimal integer number>"
Examples
This XML fragment specifies a spin control parameter increment of 60.
spinStep="60"
Additional references
decimalTextBox Element
storeAsText Attribute
The storeAsText attribute is a Boolean value. If true, the decimal element will store the
decimal value as a REG_SZ registry value; otherwise, as a REG_DWORD.
145
Syntax
storeAsText="<true|false>"
where
true represents a REG_SZ registry value
false represents a REG_DWORD registry value
Remarks
The storeAsText attribute is an optional attribute, false by default.
Examples
This XML fragment specifies a decimal element that will store its value in a REG_SZ
registry value.
<decimal id="Sample_NumericTextLabel"
valueName="Example2NumericSpin"
maxValue="599940"
storeAsText="true" />
Additional references
decimal Element (elements)
string Element (.adml)
The string element represents a localized display string.
Syntax
<string id="<placeholderID>">Placeholder text</string>
where Placeholder text is the localized text string that will be displayed.
146
Attributes
Attributes
Required
Description
id Attribute
Yes
A mapping to the string
element.
Child elements
There are no child elements associated with this element.
Remarks
Unlike the string definitions in the ADM files, the placeholder text does not use special
formatting characters. Instead, hard carriage returns and spacing will be displayed in the
same manner they are inserted.
Examples
This XML fragment shows a string element for Explain text. The Explain text shows how
formatting is included in the string element text.
<string id="Sample_Actionlist_Help">This is an example of a Group Policy
setting that configures parameters using an action list.
If you enable this policy setting, three registry values will be set.
Note:The action list parameter does not create a unique user interface and can be
used to set as many registry values as needed.
If you disable this policy setting, the first two values will be set and one value
will be deleted.
If you do not configure this policy setting, all values will be deleted, if
currently set.
Note: This policy setting changes the Example2Actionlist1, Example2Actionlist2 and
Example2Actionlist3 registry values.</string>>
147
Additional references
stringTable Element
string Element (.admx)
The string element sets a value to string text.
Syntax
<string><placeholder for string text></string>
where placeholder for string text is the literal text.
Attributes
There are no attributes associated with this element.
Child elements
There are no child elements associated with this element.
Examples
This XML fragment is an example of the string element to a literal string, "String3".
<string>String3</string>
Additional references
enabledValue Element
disabledValue Element
value Element
148
stringTable Element
The 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.
Syntax
<stringTable>
<string> … </string>
</stringTable>
Attributes
There are no attributes associated with this element.
Child elements
Element
Required
Description
string Element (.adml)
Yes
A localized string.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
If there are no string elements to be specified in the .adml file, you can omit the
stringTable element. If you include the stringTable element in the .adml file, you must
149
define at least one string element. The stringTable element is defined at most once
in an .adml file.
Examples
The XML fragment displays a stringTable element for a single policy setting to configure
two check boxes.
<stringTable>
<string id="CHECKBOXTWOTYPES_CATEGORY">Checkbox example</string>
<string id="SAMPLE">Example 2 Policy settings</string>
<string id="Sample_Checkbox">Sets policy setting parameter via a check
box</string>
<string id="Sample_Checkbox_Help">This is an example of a Group Policy
setting that configures a parameter using a check box.
If you enable this policy setting, check box1 and check box2 will be active.
Note: Check box2 will be checked by default.
If you disable this policy setting, no check box will be active.
If you do not configure this policy setting, the value will be deleted, if
currently set to a value.
Note: This policy setting changes the Example2Checkbox1 and Example2Checkbox2
registry values.</string>
</stringTable>
Additional references
resources Element (.adml)
suggestion Element
The suggestion element is a localized string displayed as a drop-down choice of the
combo box parameter.
Syntax
<suggestion>Placeholder localized text</suggestion>
150
Attributes
There are no attributes associated with this element.
Child elements
There are no child elements associated with this element.
Remarks
The suggestion element is optional. There is no limit to the number of suggestion
elements allowed for a comboBox element.
Examples
This XML fragment specifies a combo box parameter with three suggested items
displayed in the combo box parameter.
<comboBox refId="Sample_ComboBox_Filename" noSort="true" >
<label>Sample Executable File Name</label>
<default>None</default>
<suggestion>Filename A</suggestion>
<suggestion>Filename B</suggestion>
<suggestion>EXECUTABLE.EXE</suggestion>
</comboBox>
Additional references
comboBox Element
supersededAdm Element
The supersededAdm element references an ADM file name to be replaced by an ADMX
file. Group Policy Object Editor will not read any ADM file designated as superseded.
Syntax
<supersededAdm fileName="<placeholder for ADM file name>" />
151
Attributes
Attributes
Required
Description
fileName Attribute
Yes
fileName="<placeholder for ADM
file name>"
ADM file name to be superseded
by the ADMX file.
Child elements
There are no child elements associated with this element.
Examples
This XML fragment is an example using the supersededAdm element to direct the
Group Policy Object Editor to ignore the example1.adm file when processing the .admx
file containing this element.
<supersededAdm fileName="example1.adm" />
Additional references
policyDefinitions Element
supportedOn Element
The supportedOn element provides a mapping of products to definitions.
Syntax
<supportedOn>
<definitions> … </definitions>
</supportedOn>
152
Attributes
There are no attributes associated with this element.
Child elements
Element
Required
Description
definitions Element
No
Contains the definitions of
the supported product
information.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
Group Policy provides a enterprise management of the Windows Server 2008,
Windows Vista, Microsoft Windows Server 2003, and Microsoft Windows XP as well as
applications that run on the Windows platform. The enterprise will typically include
multiple versions of operating systems and other applications. In order to administrate for
these different versions, the Group Policy settings cannot be deprecated when a policy
setting no longer applies to the current version of an operating system or application.
Instead of removing Group Policy settings that apply only to earlier operating systems or
applications, the Group Policy setting remains in the ADMX files, and the supportedOn
element is used to specify what operating system or application version is affected by an
individual Group Policy setting.
The supportedOn element is an optional element. The supportedOn element can be
removed if all individual Group Policy settings reference supportedOn elements defined
in a different .admx file; for example, the Windows base file, windows.admx.
153
Examples
This XML fragment is an example of a custom supportedOn element for a specific
product version.
<supportedOn>
<definitions>
<definition name="SUPPORTED_ProductOnly"
displayName="$(string.SUPPORTED_ProductOnly)"/>
</definitions>
</supportedOn>
Additional references
policyDefinitions Element
Referencing the Windows Base ADMX File
Creating a Custom Base ADMX File
supportedOn Element (policy)
The supportedOn element provides a mapping of products to policy setting definitions.
Syntax
<supportedOn ref="<placeholderNamespace>:<placeholderLogicalName>" />
Attributes
Attributes
Required
Description
ref Attribute
Yes
ref="<placeholderNamespace>:<placeholderLogicalName>"
References a previously defined category.
154
Child elements
There are no child elements associated with this element.
Remarks
Group Policy provides a enterprise management of Microsoft Windows Server 2008,
Windows Vista, Windows Server 2003, and Windows XP as well as applications that run
on the Windows platform. The enterprise will typically include multiple versions of
operating systems and other applications. In order to administrate for these different
versions, the Group Policy settings cannot be deprecated when a policy setting no longer
applies to the current version of an operating system or application. Instead of removing
Group Policy settings that apply only to earlier operating systems or applications, the
Group Policy setting remains in the ADMX files, and the supportedOn element is used to
specify what operating system or application version is affected by an individual Group
Policy setting.
The supportedOn element is an optional element. There can be a maximum of one
supportedOn element defined for a single Group Policy setting.
Examples
This XML fragment is an example of a supportedOn element referencing a product
defined in the same .admx file.
<supportedOn ref="SUPPORTED_ProductOnly" />
This XML fragment is an example of a supportedOn element referencing a product
defined in the Windows base file, windows.admx.
<supportedOn ref="windows:SUPPORTED_WindowsVista" />
Additional references
policyDefinitions Element
Referencing the Windows Base ADMX File
Creating a Custom Base ADMX File
155
target Element
The target element provides the mapping of a logical or friendly name to an unique URI
name representing a policy namespace.
Syntax
<target prefix="<placeholder for logical or friendly name>"
namespace="<placeholder for URI>" />
Attributes
Attributes
Required
Description
prefix Attribute
Yes
prefix="<placeholder for logical
or friendly name>"
A logical name to use for referring to
the namespace within the current
ADMX file.
namespace Attribute
Yes
namespace="<placeholder for URI>"
The URI follows .NET framework
naming guidelines; for example,
"InternetExplorer," and not "ie," "inet,"
or "internetexplorer." Each URI for an
ADMX file must be unique from all
other ADMX files. For example,
"Microsoft.Policies.Example1"
cannot exist in any other ADMX file.
Child elements
There are no child elements associated with this element.
156
Remarks
The target element defines a unique name for the policy namespace in an ADMX file
with a unique URI. The dotted notation is used for the unique URI instead of the http
notation. The URI should start with the company's domain or name in order to make the
origin of the ADMX file identifiable. The friendly name used in the target element can be
reused in other files, but the target namespace must be unique for all ADMX files.
Examples
This XML fragment is an example of assigning a friendly name to the namespace,
"Microsoft.Policies.Example1."
<target prefix="example1" namespace="Microsoft.Policies.Example1" />
Additional references
policyNamespaces Element
text Element
The text element sets the specified registry value to a specified text input value when a
policy setting is enabled through the Group Policy Object Editor.
Syntax
<text id="<placeholderID>"
clientExtension="<placeholderGUID>"
key="<placeholderRegKey>"
valuename="<placeholderName>"
required="true|false"
maxLength="<placeholderMaxLength>"
expandable="true|false"
soft="true\false" />
Attributes
157
Attributes
Required
Description
id Attribute
Yes
A mapping to the text element.
clientExtension Attribute
No
The client-side extension will
process, on the client computer,
the particular settings
represented by the text
element.
key Attribute
No
The registry key location under
which the registry value will be
created.
valueName Attribute
Yes
The registry value that will be
configured for this specific
policy element.
required Attribute
No
Requirement to enter a value in
the parameter box.
maxLength Attribute
No
The maximum number of text
characters.
expandable Attribute
No
The registry subkey value will
be created as an expandable
string type
(REG_EXPAND_SZ) instead of
a string type (REG_SZ).
soft Attribute
No
This attribute flags whether to
overwrite an existing subkey.
Child elements
There are no child elements associated with this element.
Remarks
The text element will allow for string values up to 1023 characters long. The text element
is generally associated with either a text box or a combo box parameter in the Group
Policy Object Editor.
158
The text element will require a matching text box or combo box presentation
element in the corresponding .adml file with id that matches as declared in the text
element.
Examples
This XML fragment is an example of a text element that is associated with a text box.
The value will be stored as a text string, REG_SZ.
<text id="Sample_TextboxPrompt" valueName="Example2textbox" />
This XML fragment is an example of a text element that will create a string value stored
as an expandable string (REG_EXPAND_SZ). The text box in this case will require a
value to be input before the policy setting change can be applied in the enabled state.
<text id="Sample_textboxExpandszPrompt"
valueName="Example2TextboxExpandsz"
required="true" expand="true" />
Additional references
elements Element
textBox Element
comboBox Element
text Element (presentation)
The text element, when used within the presentation element, is a localized string
displayed within the parameter box by the Group Policy Object Editor.
Syntax
<text>Placeholder string text</text>
where Placeholder string text is a character string localized for a specific language.
159
Attributes
There are no attributes associated with this element.
Child elements
There are no child elements associated with this element.
Examples
This XML fragment is an example of using the text element to provide additional help text
above the spin control parameter.
<presentation id="Sample_NumericText">
<text>These are optional lines of text that provide</text>
<text>additional help text within the parameter display.</text>
<text> </text>
<decimalTextBox refId="Sample_NumericTextLabel">Spin box
label:</decimalTextBox>
</presentation>
Additional references
presentation Element
textBox Element
The textBox element represents a text box parameter. The textBox element must be
associated with a text element defined in the elements element.
Syntax
<textBox refId="<placeholderID>">
<label> … </label>
<defaultValue> … </defaultValue>
</textBox>
160
Attributes
Attributes
Required
Description
refId Attribute
Yes
A mapping to the element.
Child elements
Element
Required
Description
label Element
Yes
String label for the text box
parameter.
defaultValue Element
No
A default string displayed in
the text box parameter.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The textBox element is associated with a text box parameter in the Group Policy Object
Editor. The textBox element will require a matching text element in the corresponding
.admx file with matching id attribute as declared in the presentation element containing
the textBox element.
If the label element is not defined as the first child element of the textBox element, the
Group Policy Object Editor will display an error message.
Examples
This XML fragment is an example of a textBox element with default text displayed in the
text box parameter when the policy setting is enabled.
<textBox refId="Sample_textboxExpandszPrompt">
<label>This text box allows input of environment variables:</label>
<defaultValue>%SYSTEMROOT%\Example</defaultValue>
</textBox>
161
Additional references
presentation Element
text Element
trueList Element
The trueList element is used to set the multiple registry values when a boolean element
is set to the true state.
Syntax
<trueList defaultKey="<placeholder for registry subkey>">
<item> … </item>
</trueList>
Attributes
Attributes
Required
Description
defaultKey Attribute
No
Represents a default registry
subkey for all items.
Child elements
Element
Required
Description
item Element
Yes
Represents a registry subkey
with an associated value.
162
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The trueList element is an optional element. If you use the trueList element when
defining a boolean element, you must define at least one item element. If not, the Group
Policy Object Editor will display an error.
You can define a maximum of one trueList element for a boolean element.
There is no limit to the number of items that can be defined for a single trueList element.
Examples
The XML fragment is an example of three registry values set to either a string or decimal
value for a boolean element true state.
<trueList>
<item key="Software\Policies\Examples" valueName="ExampletrueList1">
<value>
<string>1</string>
</value>
</item>
<item key="Software\Policies\Examples" valueName="ExampletrueList2">
<value>
<decimal value="11" />
</value>
</item>
<item key="Software\Policies\Examples" valueName="ExampletrueList3">
<value>
<string>String3</string>
</value>
</item>
</trueList>
Additional references
boolean Element
163
trueValue Element
The trueValue element sets the registry value for the true condition of a boolean
element.
Syntax
<trueValue>
<delete /> | <decimal> … </decimal> | <string> … </string>
</trueValue>
You must include a choice of either the delete element, decimal element, or string
element.
Attributes
There are no attributes associated with this element.
Child elements
Element
Required
Description
delete Element
One of three must be used in
the enabledValue element.
Represents a deleted
registry value or key.
decimal Element
(elements)
One of three must be used in
the enabledValue element.
Represents an unsigned
decimal number.
string Element (.admx)
One of three must be used in
the enabledValue element.
String type limited to 255
characters in length.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
164
Remarks
The trueValue element is an optional element. If you use the trueValue element when
defining a boolean element, you must define one child element: delete, decimal, or
string element. If not, the Group Policy Object Editor will display an error.
Examples
This XML fragment is an example of a trueValue element used to configure a registry
setting value to a decimal value of 1.
<trueValue>
<decimal value="1" />
</trueValue>
Additional references
boolean Element
using Element
The 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.
Syntax
<using prefix="<placeholder for logical or friendly name>"
namespace="<placeholder for URI>" />
Attributes
165
Attributes
Required
Description
prefix Attribute
Yes
prefix="<placeholder for logical
or friendly name>"
A logical name to use for referring to
the namespace within the current
ADMX file.
namespace Attribute
Yes
namespace="<placeholder for URI>"
A URI using dotted notation; for
example,
Microsoft.Policies.Example1.
Child elements
There are no child elements associated with this element.
Remarks
ADMX files treat all elements defined within a specific policyNamespace as a unique
name. You use the using element to reference an existing category element from a
different policyNamespace in order to avoid creating duplicate category names in the
Group Policy Object Editor. You must use the using element to reference previously
defined supportedOn text from another ADMX file or the parser will give you an error. If
you are writing a number of ADMX files that may reference another file, you should take
care to build a single file containing the category and supportedOn elements referenced
from all files, also called a base file. This will help avoid circular referencing that may
cause problems when the Group Policy Object Editor reads the ADMX files. The base file
for all Windows components is called windows.admx.
Examples
This XML fragment is an example of referencing the Windows base file, windows.admx,
via the using element.
<using prefix="windows" namespace="Microsoft.Policies.Windows" />
166
Additional references
policyNamespaces Element
value Attribute
The value attribute specifies the numerical value for the decimal element.
Syntax
value="<placeholder for unsigned decimal integer number>"
Examples
This XML fragment specifies a decimal value of 2.
<decimal value="2"/>
Additional references
decimal Element (value)
value Element
The value element represents the actions to delete a registry subkey or set the value of
the registry subkey to a decimal or string value.
Syntax
<value>
<delete /> | <decimal> … </decimal> | <string> … </string>
</value>
You must include a choice of either the delete element, decimal element, or string
element.
167
Attributes
There are no attributes associated with this element.
Child elements
Element
Required
Description
delete Element
One of three must be used
in the value element.
Represents a deleted value
of a registry subkey or the
subkey itself.
decimal Element (elements)
One of three must be used
in the value element.
Represents an unsigned
decimal number.
string Element (.admx)
One of three must be used
in the value element.
String type limited to 255
characters in length.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
Remarks
The value element is an optional element. If you use the value element when defining a
policy element, you must define one child element: delete, decimal, or string element.
If not, the Group Policy Object Editor will display an error.
Examples
This XML fragment is an example of a value element used to configure a registry setting
value to a decimal value of 10.
<value>
<decimal value="10" />
</value>
168
Additional references
item Element
valueList Element
The valueList element is used to set the multiple registry values within the item element
when defined as a child of the enum element.
Syntax
<valueList defaultKey="<placeholder for registry subkey>">
<item> … </item>
</valueList>
Attributes
Attributes
Required
Description
defaultKey Attribute
No
Represents a default registry
subkey for all items.
Child elements
Element
Required
Description
item Element
Yes
Represents a registry subkey
with an associated value.
Note
For simplicity of documentation, nested elements located one level down, known
as child elements, will only be described for a given element.
169
Remarks
The valueList element is an optional element. If you use the valueList element nested
within an enum element, you must define at least one item element. If not, the Group
Policy Object Editor will display an error.
There is no limit to the number of items that can be defined for a single valueList
element.
The valueList element is most commonly used to set multiple registry key values for a
drop-down list choice of a policy setting parameter.
Note
This topic refers to two separate item elements, each defined differently. They
are distinguished from each other based on the relative level within the enum
element definition.
One item element is the parent to the valueList element. This item element
represents the display and registry keys and values that will be configured for a
single choice (for example, in a drop-down list).
The second item element is the child element of the valueList element. This
item element represents a single registry subkey with its associated value.
Examples
This XML fragment is an example of three registry values set to either a string or decimal
value when a policy setting is configured to the enabled state.
<enabledList>
<item key="Software\Policies\Examples"
valueName="Example2ActionList1">
<value>
<string>1</string>
</value>
</item>
<item key="Software\Policies\Examples"
valueName="Example2ActionList2">
<value>
<decimal value="11" />
</value>
</item>
<item key="Software\Policies\Examples"
valueName="Example2ActionList3">
<value>
170
<string>String3</string>
</value>
</item>
</enabledList>
Additional references
item Element (enum)
valueName Attribute
The valueName attribute specifies a string that contains the name for a registry entry.
Syntax
valueName="<placeholder for registry valuename>"
where the registry value name is a string value representing the name of the registry
entry.
Examples
This XML fragment identifies the valueName for the policy setting from Example 1.
valueName="Example1NoParam"
Additional references
boolean Element
decimal Element (elements)
enum Element
item Element
list Element
policy Element
171
text Element
valuePrefix Attribute
The 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.
Syntax
valuePrefix="<placeholderTextString>"
where
placeholderTextString represents the text string to be prepended to the incremented
integer for registry subkey creation.
Remarks
The valuePrefix attribute is an optional attribute. If this attribute is not specified, the
registry subkey name will match the name of the value entered. If you want the registry
subkeys to be named with incremental integers only, set the valuePrefix attribute to a
null value, valuePrefix="".
Examples
This XML fragment is an example of a list element that will prepend the text string
"SAMPLE" to an incremented integer for generating the subkey name. In this case, the
first subkey created will have the name,
HKLM|HKCU\Software\Policies\Examples\listbox1\SAMPLE1.
<list id="Sample_ListBox_SingleColumn_Param"
key="Software\Policies\Examples\listbox1"
valuePrefix="SAMPLE" />
172
Additional references
list Element
XML declaration
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.
Syntax
<?xml version="<placeholder for version number>" encoding="<placeholder for
character encoding"?>
Where:
Attributes
Attributes
Required
Description
version
Yes
version="<placeholder for
version number>"
The version of XML used in the
document. Currently, the only
version of XML available is 1.0.
encoding
No
encoding="<placeholder for
character encoding"
Character encoding information
used by XML parsers. ADMX files
are always UTF-8 encoded.
173
Note
The Group Policy tools will successfully consume the ADMX file that does not
include the XML declaration. The ADMX file may not validate as a fully-formed
XML file if the XML declaration is not included in the .admx file.
Child elements
There are no child elements associated with this element.
Remarks
At a minimum, the XML declaration must specify the XML version attribute. The XML
declaration may also contain the document encoding attribute. Both attributes are set at
the start of each file through one declaration. The declaration begins with the notation,
'<?', and ends with the notation, '>?'. The declaration must not be preceded by
comments, white space or other XML processing instructions.
Examples
The XML fragment is an example of an XML declaration that includes the version and
character encoding attributes.
<?xml version="1.0" encoding="utf-8"?>
Additional references
ADMX syntax
xmlns Attribute
The xmlns attribute specifies the default namespace for all elements in either the .admx
or .adml file.
Syntax
xmlns= "http://schemas.microsoft.com/GroupPolicy/2006/07/PolicyDefinitions" >
174
Remarks
The purpose of the URI is to identify the standard schema used to describe the ADMX
format. Even though the namespace name begins with "http:", it has nothing to do with
the HTTP protocol, a specific web site or any network-accessible resource.
Examples
This XML fragment displays the header for the .adml file containing the URI all Microsoft
Group Policy .admx and .adml files must use.
<policyDefinitionResources xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" revision="1.0"
schemaVersion="1.0"
xmlns="http://schemas.microsoft.com/GroupPolicy/2006/07/PolicyDefinitions">
Additional references
policyDefinitions Element
policyDefinitionResources Element