Pre-configuration of Sidebar Gadgets using unattend.xml

Article
03/08/2007

We’ve heard from several OEMs who are having trouble pre-configuring Sidebar gadgets using the Sidebar unattend settings. We will explain in more detail how these settings work.

First, the Sidebar unattend settings are overrides for the default gadget settings. To determine what the default Sidebar gadget settings are, you can examine the “%programfiles%\Windows Sidebar\settings.ini” file. The default settings.ini file that shipped with Vista contains the following information (note that this can change between versions of Windows):

[Root]
SettingsVersion=00.00.00.01
SidebarShowState=Imploded
SidebarDockedPartsOrder=0x1,0x2,0x3,
Section0=1
Section1=2
Section2=3
[Section 1]
PrivateSetting_GadgetName=%PROGRAMFILES%\windows sidebar\gadgets\Clock.gadget
PrivateSetting_Enabled=true
[Section 2]
PrivateSetting_GadgetName=%PROGRAMFILES%\windows sidebar\gadgets\SlideShow.Gadget
PrivateSetting_Enabled=true
[Section 3]
PrivateSetting_GadgetName=%PROGRAMFILES%\windows sidebar\gadgets\RSSFeeds.Gadget
PrivateSetting_Enabled=true
loadFirstTime=defaultGadget

As you can see, the default settings indicate that Sidebar should be on by default and that the Clock, SlideShow and RSSFeeds gadgets are loaded.

The unattend.xml file can be used by OEMs and Corporations to override certain default properties of Windows components, including Sidebar, during Windows setup. Using the unattend.xml file, OEMs and Corporations my override the following Sidebar default settings:

Whether Sidebar is on by default when Windows boots
Whether Sidebar is visible by default when it is running
Control up to five default gadgets

Whether Sidebar starts when Windows boots is controlled by the “SidebarOnByDefault” unattend value. Whether Sidebar is visible by default when it runs is controlled by the “SidebarVisible” unattent setting. To have Sidebar not start by default when Windows load, you would add the following to your unattend.xml:

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarOnByDefault>false</SidebarOnByDefault>
      </component>
   </settings>
</unattend>

To have Sidebar start when Windows is booted but not be visible by default, you would add the following to your unattend.xml file:

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarVisible>false</SidebarVisible>
         <SidebarOnByDefault>true</SidebarOnByDefault>
      </component>
   </settings>
</unattend>

To use the Gadget settings, you need the information from the default settings.ini file. It’s also best to think of the Gadget settings as slots to hold up to five gadgets. Each slot (Gadget1,…, Gadget5) contains two pieces of information; the path of a preinstalled gadget and whether that gadget is enabled (true) or disabled (false). These five gadget slots override the settings in the default settings.ini file (which controls which gadgets start by default). Let’s consider a few examples.

Example 1. Suppose you want to have Clock, SlideShow, RSSFreeds and your own custom preinstalled Foo gadget to load in that order. Since Clock, SlideShow, and RSSFeeds are already the default gadgets that load (and in that order) for Vista, you could just add the following to unattend.xml:

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarVisible>true</SidebarVisible>
         <SidebarOnByDefault>true</SidebarOnByDefault>
         <Gadget4>%PROGRAMFILES%\windows sidebar\gadgets\Foo.Gadget,true</Gadget4>
      </component>
   </settings>
</unattend>

However, it’s best to avoid dependencies on the default values in settings.ini as much as possible since those could change in later versions of the operating system. You could accomplish the same thing in a safer way by adding the following to unattend.xml:

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarVisible>true</SidebarVisible>
         <SidebarOnByDefault>true</SidebarOnByDefault>
         <Gadget1>%PROGRAMFILES%\windows sidebar\gadgets\SlideShow.gadget,true</Gadget1>
         <Gadget2>%PROGRAMFILES%\windows sidebar\gadgets\Clock.Gadget,true</Gadget2>
         <Gadget3>%PROGRAMFILES%\windows sidebar\gadgets\RSSFeeds.Gadget,true</Gadget3>
         <Gadget4>%PROGRAMFILES%\windows sidebar\gadgets\Foo.Gadget,true</Gadget4>
      </component>
   </settings>
</unattend>

Example 2: Now suppose you wanted only your Foo gadget to load. In this case, if you just add a Gadget4 setting for Foo.Gadget, you will still have SlideShow, Clock and RSS starting since the unattend settings are just overrides (nothing has overridden the first three slots). There is no way to explicitly remove a gadget entry using the unattend.xml file, but you can disable a default gadget. So, to have only Foo load by default, you could add the following to unattend.xml:

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarVisible>true</SidebarVisible>
         <SidebarOnByDefault>true</SidebarOnByDefault>
         <Gadget1>%PROGRAMFILES%\windows sidebar\gadgets\SlideShow.gadget,false</Gadget1>
         <Gadget2>%PROGRAMFILES%\windows sidebar\gadgets\Clock.Gadget,false</Gadget2>
         <Gadget3>%PROGRAMFILES%\windows sidebar\gadgets\RSSFeeds.Gadget,false</Gadget3>
         <Gadget4>%PROGRAMFILES%\windows sidebar\gadgets\Foo.Gadget,true</Gadget4>
      </component>
   </settings>
</unattend>

In the above case, we just disabled the three existing gadgets and added a new entry for Foo. Another way to accomplish that could be to replace the slot 1 gadget with Foo and disable the other two slots, like so:

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarVisible>true</SidebarVisible>
         <SidebarOnByDefault>true</SidebarOnByDefault>
         <Gadget1>%PROGRAMFILES%\windows sidebar\gadgets\Foo.gadget,true</Gadget1>
         <Gadget2>%PROGRAMFILES%\windows sidebar\gadgets\Clock.Gadget,false</Gadget2>
         <Gadget3>%PROGRAMFILES%\windows sidebar\gadgets\RSSFeeds.Gadget,false</Gadget3>
      </component>
   </settings>
</unattend>

Example 3: Finally, let’s say you want to have three instances of Clock start up and then two instance of SlideShow.

<unattend xmlns="urn:schemas-microsoft-com:unattend" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State">
   <settings pass="oobeSystem">
      <component name="Microsoft-Windows-Sidebar" publicKeyToken="31bf3856ad364e35" language="neutral"
                 versionScope="nonSxS" processorArchitecture="x86">
         <SidebarVisible>true</SidebarVisible>
         <SidebarOnByDefault>true</SidebarOnByDefault>
         <Gadget1>%PROGRAMFILES%\windows sidebar\gadgets\Clock.gadget,true</Gadget1>
         <Gadget2>%PROGRAMFILES%\windows sidebar\gadgets\Clock.Gadget,true</Gadget2>
         <Gadget3>%PROGRAMFILES%\windows sidebar\gadgets\Clock.Gadget,true</Gadget3>
         <Gadget4>%PROGRAMFILES%\windows sidebar\gadgets\SlideShow.Gadget,true</Gadget4>
         <Gadget5>%PROGRAMFILES%\windows sidebar\gadgets\SlideShow.Gadget,true</Gadget5>
      </component>
   </settings>
</unattend>

Note that configuration of a gadget (beyond whether it’s enabled or disabled) is not supported via the unattend.xml file at this time.

Pre-configuration of Sidebar Gadgets using unattend.xml

Additional resources