.NET Framework Client Profile Deployment Configuration Schema
The deployment of an application that uses the .NET Framework Client Profile includes a setup bootstrapper and a Deployment.xml file. The setup bootstrapper reads the Deployment.xml file to determine which products and packages it will install, and how to customize the user interface of the setup process. This topic describes the elements that can appear in a Deployment.xml file, and includes example Deployment.xml and Strings.xml files.
Elements
The following table shows the elements that can appear in a Deployment.xml file. All attributes that have default values are optional.
Element |
Description |
Attributes |
|---|---|---|
<Deployment> |
Required. The root node loaded by the bootstrapper. Must contain a <ProductRefs> and an <InstallUI> element. |
FallbackCulture (Required) For more information about valid culture settings, see CultureInfo. |
<ProductRefs> |
Required. Contains the products to be installed. Must contain at least one <ProductRef> element. |
|
<ProductRef> |
Required. Describes the location of the product definition file, which is named Product.xml. |
Location (Required) Relative path to the Product.xml file. |
<InstallUI> |
Required. Contains the necessary information for rendering the installation user interface (UI). Must contain a <Windows> element. Can contain an <AppToLaunch> element. |
FallbackCulture (Required) For more information about valid culture settings, see CultureInfo. |
<AppToLaunch> |
Optional. Specifies the application to launch after successful completion of the installation. |
Location (Required) Path to the application to launch. For example, %programfiles%\MyApp.exe. If the <AppToLaunch> element is present and the <PostInstallWindow> element is absent, the application launches after the deployment succeeds. If both the <AppToLaunch> and the <PostInstallWindow> elements appear, the application is launched after the deployment succeeds and the user clicks the Finish button. If the <StartAppCheckBox> element also appears, the user decides whether to launch the application after the deployment succeeds. |
<Windows> |
Required. Specifies the visual elements that define the appearance and behavior of the installation. Must contain a <Defaults> and an <InstallWindow> element, and can contain a <PreInstallWindow>, a <PostInstallWindow>, a <RollbackWindow>, an <ErrorWindow>, a <CancelledWindow>, and/or a <RebootWindow> element. |
|
<Defaults> |
Required. Contains the window defaults that persist throughout the installation process. Must contain a <ButtonGroup> element. Can also contain a <TitleCaption> and/or <CopyrightCaption> element. |
BackgroundColor (Default: Default window color) Defaults to the color of the COLOR_WINDOW constant. Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. BackgroundImage (Default: No image) JPEG, GIF, BMP, WMF, PNG, TIFF, EXIF, and EMF formats can be used. Will not be resized to fit the window. ForegroundColor (Default: Default window color) Defaults to the color of the COLOR_WINDOWTEXT constant. Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Height (Default: 300) Height of the client area of the main window, in pixels. Icon (Default: No icon) Displays in the top-left corner of the main window. Only ICO format can be used. ShowWindowFrame (Default: true) Defines whether the window will display the title bar and window borders. Title (Required) Text that appears on setup windows and message boxes. Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. TransparentColor (Optional) Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Width (Default: 500) Width of the client area of the main window, in pixels. |
<TitleCaption> |
Optional. Contains the information for rendering the sub-title text that appears in the setup window. |
Alignment (Default: Left) Can also be Center or Right. Bold (Default: false) Font (Default: System font) FontSize (Default: 20) Text font size, in pixels. ForegroundColor (Default: Inherited from <Defaults>) Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Italics (Default: false) PosX (Default: 20) The number of pixels to offset this caption from either the left or the right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this caption from the top of the window. Text (Required. Must be an identifier that is found in the <Strings> block of the localized Strings.xml file.) Underline (Default: false) |
<CopyrightCaption> |
Optional. Specifies copyright information for the author. |
Alignment (Default: Center) Can also be Left or Right. Bold (Default: false) Font (Default: System font) FontSize (Default: 10) Text font size, in pixels. ForegroundColor (Default: Inherited from <Defaults>) Italic (Default: false) PosX (Default: 20) The number of pixels to offset this caption from either the left or the right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this caption from the top of the window. Text (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. Underline (Default: false) |
<ButtonGroup> |
Required. Specifies the buttons required for moving among the different setup windows during the installation. |
PosX (Default: 20) The number of pixels to offset buttons from either the left or the right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset buttons from the top of the window. |
<PreInstallWindow> |
Optional. Defines UI behavior during the first stage of the installation. Must contain <AcceptButton> and <DeclineButton> elements. Can also contain a <EulaBox>, a <PrintButton>, a <PromptCaption>, and/or a <TitleCaption> element. |
|
<EulaBox> |
Optional. Displays the software license terms referenced by each LicenseAgreement attribute in the Product.xml file of each <ProductRef> element. |
BackgroundColor (Default: Default windows color) Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Height (Required) Height of the control, in pixels. Width (Default: Default window width minus 40) Width of the control, in pixels. PosX (Default: 20) The number of pixels to offset this control from either the left or right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this control from the top of the window. |
<AcceptButton> |
Required. Represents the Accept button for the license terms prompt. |
Text (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. |
<DeclineButton> |
Required. Represents the Decline button for the license terms prompt. |
Text (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. |
<PrintButton> |
Optional. Represents the Print button for the license terms prompt. |
Alignment (Default: Left) Can also be Center or Right. Bold (Default: false) Font (Default: System font) FontSize (Default: 12) Text font size, in pixels. ForegroundColor (Default: Inherited from <Defaults>) Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Italic (Default: false) PosX (Required) The number of pixels to offset this button from either the left or right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this button from the top of the window. Title (Required. Must be an identifier that is found in the <Strings> block of the localized Strings.xml file.) Underline (Default: false) |
<PromptCaption> |
Optional. Displays a prompt that asks the user whether he or she wants to accept the terms of the license agreements. |
Alignment (Default: Left) Can also be Center or Right. Bold (Default: false) Font (Default: System font) FontSize (Default: 12) Text font size, in pixels. ForegroundColor (Default: Inherited from <Defaults>) Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Italic (Default: false) PosX (Default: 20) The number of pixels to offset this caption from either the left or the right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this caption from the top of the window. Title (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. Underline (Default: false) |
<InstallWindow> |
Required. Defines UI behavior during the second stage of the installation process. Must contain a <CancelButton> element. Can also contain a <DownloadCaption>, a <StatusCaption>, a <ProgressBar>, a <TitleCaption>, and/or a <WebControl> element. |
The visible cancel button only appears if <RollbackWindow> is specified. |
<StatusCaption> |
Optional. Shows the status of the installation phase. |
Alignment (Default: Left) Can also be Center or Right. Bold (Default: false) Font (Default: System font) FontSize (Default: 12) Text font size, in pixels. ForegroundColor (Default: Inherited from <Defaults>) Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Italic (Default: false) PosX (Default: 20) The number of pixels to offset this caption from either the left or the right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this caption from the top of the window. Text (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. Strings.xml text can contain these tokens: %p – Percentage completion of this installation phase, excluding download activity. %g - Percentage of total installation complete, including download and installation activities. Underline (Default: false) |
<DownloadCaption> |
Optional. Shows the status of the current download. |
Alignment (Default: Left) Can also be Center or Right. Bold (Default: false) Font (Default: System font) FontSize (Default: 12) Text font size, in pixels. ForegroundColor (Default: Inherited from <Defaults>) Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Italic (Default: false) PosX (Default: 20) The number of pixels to offset this caption from either the left or the right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this caption from the top of the window. Text (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. Strings.xml text can contain these tokens: %p – Percentage of download phase completion. %c – Amount that has been currently downloaded in KB. %t – Total download size in KB. Underline (Default: false) |
<ProgressBar> |
Optional. Shows the overall status of the installation. |
Height (Required) Height of the progress bar, in pixels. PosX (Default: 20) The number of pixels to offset this progress bar from either the left or right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this progress bar from the top of the window. Width (Default: 300) Width of the progress bar, in pixels. |
<WebControl> |
Optional. Displays HTML content during the installation or post-installation phase. Must contain a <Pages> element. |
Height (Required) Height of the control, in pixels. PosX (Default: 20) The number of pixels to offset this control from either the left or right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this control from the top of the window. Width (Default: Window width minus 40) Width of the control, in pixels. |
<Pages> |
Required. Must contain one or more <Page> elements. |
Delay (Default: 5) Number of seconds a page displays. Repeat (Default: true) Whether to cycle through pages continuously. |
<Page> |
Required. Contains HTML content to display in the <WebControl> element. This content cannot include hyperlinks or active content. |
File (Required) Location of the HTML content, relative to the location of the active Strings.xml file. |
<CancelButton> |
Required. Represents the Cancel button for the installation. |
Text (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. |
<PostInstallWindow> |
Optional. Displays the Finished message or prompts to finish the installation. Must contain a <FinishButton> element. Can also contain a <FinishCaption>, a <TitleCaption>, a <WebControl> and/or a <StartAppCheckBox> element. |
|
<FinishButton> |
Required. Represents the Finish button for the installation. |
Title (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. |
<FinishCaption> |
Optional. Describes the caption to appear in the successful installation window. |
Alignment (Default: Left) Can also be Center or Right. Bold (Default: false) Font (Default: System font) FontSize (Default: 12) Text font size, in pixels. ForegroundColor (Default: Inherited from <Defaults>) Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Italic (Default: false) PosX (Default: 20) The number of pixels to offset this caption from either the left or the right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this caption from the top of the window. Text (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. Underline (Default: false) |
<StartAppCheckBox> |
Optional. Shows a check box that specifies whether to start the application specified in the <AppToLaunch> element after the installation phase. |
Alignment (Default: Left) Can also be Center or Right. Bold (Default: false) Font (Default: System font) FontSize (Default: 12) Text font size, in pixels. ForegroundColor (Default: Inherited from <Defaults>) Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Italic (Default: false) PosX (Default: 20) The number of pixels to offset this check box from either the left or the right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this check box from the top of the window. Title (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. Underline (Default: false) Checked (Default: true) Specifies whether the check box is set by default. |
<RollbackWindow> |
Optional. Displays the installation rollback window. Can contain a <MarqueeBar>, a <TitleCaption>, a <RollbackCaption>, and/or a <WebControl> element. |
|
<RollbackCaption> |
Optional. Describes the caption to appear in the rollback window. |
Alignment (Default: Left) Can also be Center or Right. Bold (Default: false) Font (Default: System font) FontSize (Default: 12) Text font size, in pixels. ForegroundColor (Default: Inherited from <Defaults>) Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Italic (Default: false) PosX (Default: 20) The number of pixels to offset this caption from either the left or the right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this caption from the top of the window. Text (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. Underline (Default: false) |
<MarqueeBar> |
Optional. Displays a rolling animation to indicate that activity is occurring. |
Height (Required) Height of the marquee bar, in pixels. PosX (Default: 20) The number of pixels to offset this marquee bar from either the left or right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this marquee bar from the top of the window. Width (Default: 300) Width of the marquee bar, in pixels. |
<ErrorWindow> |
Optional. Displays the installation error window. Contains an <ExitButton>. Can also contain a <FailureCaption>, a <TitleCaption>, and/or a <WebControl>. |
|
<FailureCaption> |
Optional. Describes the caption to appear in the failed installation window. |
Alignment (Default: Left) Can also be Center or Right. Bold (Default: false) Font (Default: system font) FontSize (Default: 12) Text font size, in pixels. ForegroundColor (Default: Inherited from <Defaults>) Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Italic (Default: false) PosX (Default: 20) The number of pixels to offset this caption from either the left or the right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this caption from the top of the window. Text (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. Underline (Default: false) |
<CancelledWindow> |
Optional. Contains an <ExitButton> element. Can also contain <CancelledCaption>, a <TitleCaption>, and/or a <WebControl>. |
|
<CancelledCaption> |
Optional. Describes the caption to appear in the cancelled installation window. |
Alignment (Default: Left) Can also be Center or Right. Bold (Default: false) Font (Default: System font) FontSize (Default: 12) Text font size, in pixels. ForegroundColor (Default: Inherited from <Defaults>) Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Italic (Default: false) PosX (Default: 20) The number of pixels to offset this caption from either the left or the right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this caption from the top of the window. Text (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. Underline (Default: false) |
<ExitButton> |
Optional. Represents the exit button for the installation. |
Text (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. |
<RebootWindow> |
Optional. Defines a window that describes computer restart requirements and options for this installation task. Contains a <RebootNowButton> and a <RebootLaterButton> element. Can contain a <RebootPromptCaption>, a <TitleCaption>, and/or a <WebControl> element. |
If a reboot is required and <RebootWindow> is not defined, a message box containing a default message about rebooting appears. The computer reboots when the user clicks OK. |
<RebootPromptCaption> |
Optional. Describes the caption to appear in the reboot window. |
Alignment (Default: Left) Can also be Center or Right. Bold (Default: false) Font (Default: System font) FontSize (Default: 12) Text font size, in pixels. ForegroundColor (Default: Inherited from <Defaults>) Accepts a hexadecimal RGB value, such as "#FFFFFF" for white. Italic (Default: false) PosX (Default: 20) The number of pixels to offset this caption from either the left or the right edge, depending on the language orientation of the culture of this deployment. PosY (Required) The number of pixels to offset this caption from the top of the window. Text (Required) Must be an identifier that is found in the <Strings> block of the localized Strings.xml file. Underline (Default: false) |
<RebootNowButton> |
Required. Represents the button that causes an immediate reboot. |
Text (Required) Must be an identifier that is found in <Strings> block of localized Strings.xml file. |
<RebootLaterButton> |
Required. Represents the button that allows the user to reboot later. |
Text (Required) Must be an identifier that is found in <Strings> block of localized Strings.xml file. |
Example Deployment.xml
The following shows an example of a Deployment.xml file. The user interface for this example includes a pre-install window with a license terms acceptance step, an installation window with download and status captions, a progress bar, and a content portion that cycles between two HTML files every five seconds. When the installation completes, a finish.htm content page is shown.
<?xml version="1.0" encoding="utf-8" ?>
<Deployment FallbackCulture="en">
<ProductRefs>
<ProductRef Location="DotNetClientFx\Product.xml" />
</ProductRefs>
<InstallUI>
<Windows>
<Defaults Width="550" Height="350" BackgroundColor="#FFFFAA" ForegroundColor="#0000FF" Title="Client Setup">
<TitleCaption PosY="20" Text="TITLE" Font="Verdana" Bold="true" />
<CopyrightCaption PosY="320" Text="COPYRIGHT" Italic="true" />
<ButtonGroup PosY="280" />
</Defaults>
<PreInstallWindow>
<PromptCaption PosY="50" Text="PROMPT" ForegroundColor="#000000" />
<EulaBox Height="200" PosY="70" BackgroundColor="#FFFFAA" />
<AcceptButton Text="ACCEPT" />
<DeclineButton Text="DECLINE" />
</PreInstallWindow>
<InstallWindow>
<DownloadCaption PosY="240" Text="DOWNLOAD" />
<StatusCaption PosY="260" Text="STATUS" />
<WebControl PosX="20" PosY="50" Width="510" Height="180">
<Pages Repeat="true" Delay="5">
<Page File="install1.htm" />
<Page File="install2.htm" />
</Pages>
</WebControl>
<ProgressBar PosX="20" PosY="280" Width="360" />
<CancelButton Text="CANCEL" />
</InstallWindow>
<PostInstallWindow>
<WebControl PosX="20" PosY="50" Width="510" Height="180">
<Pages Repeat="false" Delay="5">
<Page File="finish.htm" />
</Pages>
</WebControl>
<FinishButton Text="EXIT" />
</PostInstallWindow>
</Windows>
</InstallUI>
</Deployment>
Example Strings.xml
The following shows an example of a Strings.xml file. This example accompanies the previous Deployment.xml example file. The Name attributes of the String elements correspond to the Text attributes in Deployment.xml.
<?xml version="1.0" encoding="utf-8" ?>
<Strings>
<String Name="TITLE">.NET Framework 3.5 Client Setup</String>
<String Name="COPYRIGHT">Copyright © 2008 Microsoft Corporation. All rights reserved.</String>
<String Name="PROMPT">Please accept the following license agreement:</String>
<String Name="DOWNLOAD">Downloading installation components - %cKB / %tKB (%g%% completed)</String>
<String Name="STATUS">Installing .NET Framework 3.5 Client (%p%% completed)</String>
<String Name="ACCEPT">&Accept</String>
<String Name="DECLINE">&Decline</String>
<String Name="CANCEL">&Cancel</String>
<String Name="EXIT">E&xit</String>
<String Name="STARTAPP">&Launch the application now</String>
</Strings>