Share via

Server Manager Extension Schema

  • Article

Applies To: Windows 7

Note

This content applies to Windows 7. For Windows 8 content, see Windows Deployment with the Windows ADK.

The Server Manager Extension Schema is a tool for OEMs to create an extensibility .xml file. For performance reasons, the .xml file will not be validated by the schema and the schema will not be used for deserialization of the .xml file at runtime by the user interface (UI). If the XML that you create does not conform to the schema, the resources will not appear in the UI and no errors will be displayed.

ServerUIExtension Element

The root element of the .xml file is the ServerUIExtension element. It contains a list of extensions that apply to the out-of-box experience, or role home pages, or both.

Child Elements

Extension

Required

One extension element is added for the out-of-box experience. You can add multiple extension elements for each of the Server Manager home pages.

Attributes

ResourceDllPath

Required

A path to the default resource DLL from which all resources will be loaded to extend the UI. The DLL must be found under %WINDIR%\System32 to prevent tampering by unauthorized users.

Environment variables will be evaluated.

Example

The following XML example shows the ServerUIExtension element schema definition.

<xs:element name="ServerUIExtension">
   <xs:complexType>
      <xs:sequence>
         <xs:element name="Extension" type="ExtensionType" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
         <xs:attribute name="ResourceDllPath" type="xs:string" use="required"/>
   </xs:complexType>
</xs:element>

Extension Element

The Extension element defines the new sections that will be added to the out-of-box experience.

Child Elements

Section

Not Required

Adds a new section to the end of the out-of-box experience or a new tile to the end-of-role home pages. Only one new tile is allowed, unless a specific role allows for multiple roles, as in the case of the File Server role.

Attributes

Name

Required

The name of the extension to indicate if the new branding and new sections apply to OOBE (“InitConfig”) or to a role home page. This must be one of these values: InitConfig, ADAM, ADFS, Application, Certificate, DHCP, Directory, Fax, File, Web, Media, NAS, Print, RMS, TS, UDDI, VirtualServer, WDS, WSS, or Windows® Server Update Services (WSUS).

ResourceDllPath

Not Required

A path to the resource DLL from which resources are loaded for this extension. If not specified, the default resource DLL that is specified in the root ServerUIExtension element will be used.

The DLL must be found in %WINDIR%\system32.

Environment variables will be evaluated.

Example

The following XML example shows the Extension element schema definition.

<xs:complexType name="ExtensionType">
   <xs:sequence>
      <xs:element name="Section" type="SectionType" minOccurs="0" maxOccurs="unbounded"/>
   </xs:sequence>
      <xs:attribute name="Name" type="ExtensionNameType" use="required"/>
      <xs:attribute name="ResourceDllPath" type="xs:string" use="optional"/>
      <xs:attribute name="HeaderTitleId" type="StringIdType" use="optional"/>
      <xs:attribute name="HeaderIconId" type="IconIdType" use="optional"/>
      <xs:attribute name="HeaderImageId" type="ImageIdType" use="optional"/>
      <xs:attribute name="HeaderDescriptionId" type="StringIdType" 
                      use="optional"/>
</xs:complexType>

Section Element

New sections can be added below existing sections in both Initial Configuration Tasks and Server Manager. In Initial Configuration Tasks, existing sections can also be modified. If an existing section is being modified, the Id attribute identifies the section to modify. If the Id attribute is not specified, a new section will be added.

Note

Status information is not displayed for the tasks in the Initial Configuration Tasks.

Child Elements

HelpLink

Not Required

Specifies information that is necessary to launch a topic.

Task

Not Required

Specifies the tasks to be launched. Status information is not displayed for the tasks in the Initial Configuration Tasks.

Attributes

TitleId

Not Required

The ID in the resource DLL from which to load the section’s title.

Id

Not Required

The identifier of an existing section in Initial Configuration Tasks that will be modified. The section names to identify the sections are: “1,” “2,” and “3.”

DescriptionId

Not Required

The ID of the description that is shown at the top of a section on a home page. This attribute will be ignored in InitConfig.

BrandingImageId

Not Required

The OEM image that is displayed in the section. The transparency color is Color.Magenta.

Example

The following XML example shows the Section element schema definition.

<xs:complexType name="SectionType">
   <xs:sequence>
      <xs:element name="HelpLink" type="HelpLinkType" minOccurs="0"/>
      <xs:element name="Task" type="TaskType" minOccurs="0" 
maxOccurs="unbounded"/>
      <xs:attribute name="BrandingImageId" type="ImageIdType" 
   </xs:sequence>
      <xs:attribute name="TitleId" type="StringIdType" use="optional"/>
      <xs:attribute name="Id" type="SectionIdType" use="optional"/>
</xs:complexType>

The HelpLink element is a launch point for the OEM to provide user assistance. There are three ways Help can be launched: a Help topic in a .chm file, a URL, or an arbitrary command that launches Help in some other form.

Note

There can be no more than one HelpLink element in a section.

Attributes

ActionLinkAttributes

No

Both Help links and tasks have basically the same functionality: to perform some action when the user clicks the link. To provide complete flexibility, both of these links will be able to launch an action in the form of:

  • A Help topic (in a .chm file)

  • A URL

  • An arbitrary command

If more than one of the Help targets is specified, a target is chosen in the order specified in the bulleted list in the preceding paragraph. For example, if both a Help topic and a URL are provided, only the Help topic is launched.

Example

The following XML example shows the HelpLink element schema definition.

<xs:complexType name="HelpLinkType">
   <xs:attributeGroup ref="ActionLinkAttributes"/>
</xs:complexType>

ActionLinkAttributes Element

Both Help links and tasks have basically the same functionality: to perform some action when the user clicks the link. To provide flexibility, both of these links launch an action in the form of a Help topic, a URL, or another command.

Attributes

LinkId

Not Required

String ID for the link to be loaded from resources.

ToolTipId

Not Required

String ID for the tooltip that is displayed for the link. If not specified and the Url or UrlId attributes are specified, the URL is displayed as the tooltip.

DescriptionId

Required except for InitConfig

String ID for the description that is displayed next to the action link on a home page. This attribute is ignored in an InitConfig extension.

HelpFile

Not Required

File name of the compiled HTML Help file (.chm). The HelpTopic attribute must also be set to the name of the topic inside the .chm file, except during the out-of-box experience.

Environment variables are evaluated. However, it is not recommended that you provide an absolute path. This way, the Help application programming interface (API) can automatically pick up the .chm file from the built-in directory and handle localization.

HelpTopic

Not Required

If the HelpFile attribute is set, the HelpTopic attribute is the name of the topic inside the .chm file.

Command

Not Required

A command that is launched when the task is clicked.

Environment variables are evaluated.

CommandArguments

Not Required

Arguments to pass to the command to be executed. Environment variables are evaluated.

Url

Not Required

A URL that is launched when the Help link is clicked. The Web site is displayed in the user’s default browser.

UrlID

Not Required

A localizable URL that is loaded from the resource DLL. The Web site is launched in the user’s default browser.

Example

The following XML example shows the ActionLinksAttributes element schema definition.

<xs:attributeGroup name="ActionLinkAttributes">
   <xs:attribute name="LinkId" type="StringIdType" use="optional"/>
   <xs:attribute name="ToolTipId" type="StringIdType" use="optional"/>
   <xs:attribute name="DescriptionId" type="StringIdType" use="optional"/>
   <xs:attribute name="HelpFile" type="xs:string" use="optional"/>
   <xs:attribute name="HelpTopic" type="xs:string" use="optional"/>
   <xs:attribute name="Command" type="xs:string" use="optional"/>
   <xs:attribute name="CommandArguments" type="xs:string" use="optional"/>
   <xs:attribute name="Url" type="xs:string" use="optional"/>
   <xs:attribute name="UrlId" type="StringIdType" use="optional"/>
</xs:attributeGroup>

Task Element

The Task element is defined by its link and is either a Help topic, a URL, or a command to run when the task is launched.

Attributes

ID

Not Required

The identifier of an existing task in Initial Configuration Tasks that will be modified.

The identifiers for the tasks are: AddRoles, AddFeatures, ComputerName, EnableUpdates, Firewall, InstallUpdates, Networking, RemoteDesktop, RestoreNetwork, and TimeZone

IconId

Not Required

The resource identifier for the icon to display for the task. The icon must be 24x24 pixels.

Hide

Not Required

Specifies whether to hide the task. By default, all tasks are shown.

TaskArguments

Not Required

Specialized parameters that are interpreted depending on the needs of each task. Currently, only the Networking task uses this argument.

Specifies the number of network adapters to display before displaying "Multiple network adapters." The default is 2. For example, TaskArguments="5" will display up to five network connections.

Example

The following XML example shows the Task element schema definition.

<xs:complexType name="TaskType">
   <xs:attributeGroup ref="ActionLinkAttributes"/>
   <xs:attribute name="Id" type="TaskIdType" use="optional"/>
   <xs:attribute name="IconId" type="IconIdType" use="optional"/>
   <xs:attribute name="Hide" type="xs:boolean" use="optional"/>
   <xs:attribute name="TaskArguments" type="xs:string" use="optional"/>
</xs:complexType>

Additional Types

The following types are provided to clarify the range of values allowed for attributes.

StringID

An identifier that corresponds to a string in the DLL resources. The ID must be a non-negative integer.

ImageType

An identifier that corresponds to an image in the DLL resources. It is a string, but it clarifies when an attribute is pointing to an image in the DLL's resources.

IconIdType

The resource identifier for a 24x24 pixel icon to display for a task.

ExtensionNameType

A name that allows the extension to be added to the out-of-box experience (called InitConfig) or one of the role home pages.

SectionIdTYpe

The identifiers for sections in Initial Configuration Tasks that can be modified.

TaskIdType

The identifiers for existing tasks in Initial Configuration Tasks that can be modified.

Example

The following XML example shows the additional types.

<xs:simpleType name="StringIdType">
   <xs:restriction base="xs:nonNegativeInteger"/>
</xs:simpleType>
<xs:simpleType name="ImageIdType">
   <xs:restriction base="xs:string"/>
</xs:simpleType>
<xs:simpleType name="IconIdType">
   <xs:restriction base="xs:integer"/>
</xs:simpleType>
<xs:simpleType name="ExtensionNameType">
   <xs:restriction base="xs:string">
      <xs:enumeration value="InitConfig"/>
      <xs:enumeration value="ServerManagerHome"/>
      <xs:enumeration value="ManageRolesHome"/>
      <xs:enumeration value="AdamRole"/>
      <xs:enumeration value="ActiveDirectoryFederationServerRole"/>
      <xs:enumeration value="ApplicationServerRole"/>
      <xs:enumeration value="CertificateServerRole"/>
      <xs:enumeration value="DhcpServerRole"/>
      <xs:enumeration value="DnsServerRole"/>
      <xs:enumeration value="DomainControllerRole"/>
      <xs:enumeration value="FaxServerRole"/>
      <xs:enumeration value="FileServerRole"/>
      <xs:enumeration value="MediaServicesRole"/>
      <xs:enumeration value="NetworkAccessServicesRole"/>
      <xs:enumeration value="PrintServerRole"/>
      <xs:enumeration value="RightsManagementServicesRole"/>

      <xs:enumeration value="TerminalServicesRole"/>
      <xs:enumeration value="WindowsDeploymentServicesRole"/>
<xs:enumeration value-"virtualizationRole?>
<xs:enumeration value="WsusRole/>
      <xs:enumeration value="WebServerRole"/>
   </xs:restriction>
</xs:simpleType>
<xs:simpleType name="SectionIdType">
   <xs:restriction base="xs:string">
      <xs:enumeration value="1"/>
      <xs:enumeration value="2"/>
      <xs:enumeration value="3"/>
   </xs:restriction>
</xs:simpleType>
<xs:simpleType name="TaskIdType">
   <xs:restriction base="xs:string">
      <xs:enumeration value="AddRoles"/>
      <xs:enumeration value="AddFeatures"/>
      <xs:enumeration value="ComputerName"/>
      <xs:enumeration value="EnableUpdates"/>
      <xs:enumeration value="Firewall"/>
      <xs:enumeration value="InstallUpdates"/>
      <xs:enumeration value="Networking"/>
      <xs:enumeration value="RemoteDesktop"/>
      <xs:enumeration value="RestoreNetwork"/>
      <xs:enumeration value="TimeZone"/>
   </xs:restriction>
</xs:simpleType>

Errors and Conditions

There are a number of errors that the UI may encounter when it initializes with the OEM's data. In all cases, the UI ignores the errors and does not display any error messages in any form.

A detailed error message is written to a log file to help OEMs diagnose issues when they create their extensions. The log file is located in the AppData special folder in the subfolder \Microsoft\Windows\ServerManager\, in ServerUIExtensionErrors.log. For example, the full path on Windows Server® 2008 might be:

C:\users\MyUserName\AppData\Roaming\Microsoft\Windows\ServerManager\ServerUIExtensionErrors.log

The customized UI is not loaded if one of the following conditions exists:

  • The registry key is not found.

  • The registry key points to a file that does not exist.

  • The .xml file cannot be parsed.

  • The XML points to an invalid resource DLL.

If none of the previous conditions are met, then the following conditional cases are exercised:

  • If a section title string resource does not load, nothing in the section is loaded.

  • If a Help string resource does not load, the Help link is not added.

  • If a Help link does not specify at least one of the optional action link attributes, the Help link is not added because there would not be a target.

  • If a task string resource does not load, the task is not added.

  • If a task does not specify at least one of the optional action link attributes, the task is not added.

  • If an optional attribute is specified and is expected to be loaded from the resources, it must be contained by the resources. If not, the Help link or task will be skipped.

  • An extension is ignored if it has the same name as another extension that has already been loaded.

  • An extension is ignored if it does not have a name from the ExtensionNameType enumeration.

Localized Content

To provide localized versions of your custom resources, specify a path to the fallback DLL in the .xml file by using the ResourceDllPath attribute.

Language-specific resources must be installed to subdirectories with the name of the culture that corresponds to the resources. The resource DLL is examined in the order specified in the numbered list below. In this example, the DLL that is specified in the XML is ResourceDllPath="%WINDIR%\system32\oem\Resource.dll":

  1. The current UI culture: %WINDIR%\system32\oem\en-US\Resource.dll

  2. The current UI neutral culture: %WINDIR%\system32\oem\en\Resource.dll

  3. The language-neutral resources: %WINDIR%\system32\oem\Resource.dll

See Also

Concepts

Server Manager Technical Reference