Server Manager Extension Schema
Applies To: Windows 8
[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]
The Server Manager extension schema provides guidance about how to construct an XML file to be processed by Server Manager to customize the Server Manager Home pages.
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>
HelpLink Element
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:
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® 8 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":
The current UI culture: %WINDIR%\system32\oem\en-US\Resource.dll
The current UI neutral culture: %WINDIR%\system32\oem\en\Resource.dll
The language-neutral resources: %WINDIR%\system32\oem\Resource.dll