<< Click to Display Table of Contents >> RayPack > 7.3 u6 > User Guide > Reference and Cheat Sheets  Active Setup

Active Setup is a mechanism for executing commands once per user early during logon. Active Setup is used by some operating system components like Internet Explorer to set up an initial configuration for new users logging on for the first time. Active Setup is also used in some corporation’s software distribution systems to create an initial customized user environment. To understand why such a mechanism is necessary we need to take a step back.

 

Application programs use two different types of data: machine-specific data like the files in the installation directory, and user-specific data like the information which document a user last edited with the application. Installing machine-specific data is simple. Just copy it to C:\Program Files and HKEY_LOCAL_MACHINE and you are done. But how to get an initial user configuration into a user profile? Writing into the profile of the user doing the install does not help, because we need the initial configuration for all users logging on to the system.

 

One solution to this problem is Active Setup. It uses both machine-specific data and user-specific data. The machine part consists of a list of components each identified by a GUID. The user part is basically a mirror of the machine data, but, and this is the key point, it does not exist in new user profiles. Whenever a user logs on, Active Setup checks if each machine part component GUID is present in the user part. If not, the component’s command is executed and the component’s GUID is stored in the user part. If it is, the current user profile has already been initialized and no further action is required.

 

Active Setup runs before the shell is started, i.e. before the Desktop appears. Commands started by Active Setup run synchronously, blocking the logon while they are executing. Active Setup is executed before any Run or RunOnce registry entries are evaluated because Run(Once) is handled by the shell, Explorer.exe, which is started only after Active Setup is finished.

 

 

Registry Entries Related to Active Setup

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Active Setup\Installed Components

This is the root key containing all things Active Setup. The keys and values mentioned below are all located below this root key.

A duplicate of this machine key exists in the user profile.

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Active Setup\Installed Components

This is what is known as the “user part” Active Setup key.

 

GUID

•Type: registry key

•For each component, there is a GUID key below the root key. Technically, this need not be a GUID, but GUIDs have the advantage of being unique.

•Each GUID represents one component to be managed by Active Setup. The number of components is not limited and there can be zero, one or multiple components per application. The number of components is dependent on the number of commands that are to run – only one command per component is possible (see StubPath below). Typically, the ProductCode property of the msi package is used as the GUID, as this is guaranteed to be unique.

 

Default Value

•Type: REG_SZ

•Optional name of the component. If a name is stored here, it will be shown in the Active Setup user interface dialog when the component’s command is run. It is advisable to use the ProductName property here, as this is easy to recognize.

 

IsInstalled

•Type: REG_DWORD

•Possible values:

0: The component’s command will not run.

1: The component’s command will be run once per user. This is the default (if the IsInstalled value does not exist).

 

Locale

•Type: REG_SZ

•An arbitrary string specifying the installation language of the component. If this string is either not found in the user part or different from the machine part, the component is run. Please note that Active Setup does not impose any restrictions on the nature of this string, you could use “abc” just as well as “de” or “en”. Once run, the version number is copied to the user part. It is advisable to use an "asterisk" here (*).

 

StubPath

Type: REG_SZ or REG_EXPAND_SZ

•Format: Any valid command line, e.g. “notepad”

•This is the command that is executed if Active Setup determines this component needs to run during logon. Normally for use in msi packages, the StubPath contains the msi engine executable, the ProductCode property of the msi package, and any command lines that the msi engine requires. For example, msiexec.exe  /Fpums [ProductCode] /Qn

 

 

Version

•Type: REG_SZ

•Format: Four numbers separated by commas, e.g.: 1,2,3,4 (periods do not work)

•If a version value is present, the component’s command will run only if the corresponding version in the user part is smaller or not present. Once run, the version number is copied to the user part. If you want a component’s command to run again, you need to increase the version number. That is what Windows updates do, e.g. when you install Internet Explorer 8 on a machine that only had IE7 before. By increasing the version number, the initial user configuration is guaranteed to run again.

 

Things You Should Know

Active Setup employs neither a timeout nor any other mechanism to determine if a StubPath process it started is still alive. That means it is very easy to shoot yourself in the foot: if a process started by Active Setup hangs, Active Setup hangs, too, and there is typically no easy way to remedy the situation, except flipping the big red power switch. Therefore it is advisable to thoroughly test the implementation of any packages that use Active Setup to avoid problems when deploying the package.

 

Original text from Helge Klein