Microsoft Component Installer Software Development Kit for Windows (MCISDK)

Microsoft Corporation

Spring 2005

Contents

Introduction: Microsoft Component Installer for Windows
Structure of PSetup
Web Download
CD Distribution
PSetup Application Flow
Packaging
Bug Reports

Summary: Provides an overview of how Microsoft Component Installer for Windows works, as well as how it can be customized to support third-party install scenarios. (7 printed pages)

You can download the SDK here.

Introduction: Microsoft Component Installer for Windows

Microsoft Component Installer for Windows (Psetup) is an application designed to simplify the process of installing application prerequisites on customer computers. It provides support for installing any or all of the following components (in the following order):

• Microsoft Data Access Components (MDAC) 2.8
• Microsoft .NET Framework 1.1
• Microsoft DirectX 9.0c
• Microsoft DirectX 9.0c for Managed Code
• Microsoft .NET Framework Version 1.1 Language Pack
• Microsoft .NET Framework 1.1 Service Pack 1
• Microsoft ASP.NET Security Update for Microsoft .NET Framework 1.1 Service Pack 1
• Microsoft Windows Installer 2.0
• Microsoft Windows Installer 3.1

PSetup provides a simple wizard user interface for end users and provides details for when an error occurs, or when the system needs to reboot as the result of an installer. PSetup is localized for over 20 languages and will auto-detect the system locale at launch and adjust its language support as appropriate.

Structure of PSetup

PSetup expects a certain set of files to be available when run:

Note that all the files mentioned in the Prereq subfolder require a distribution license if one intends to ship them on optical, solid-state, or magnetic media. If you want to distribute through the Web, Psetup will download the files directly from Microsoft download servers and you do not have to obtain an additional license.

PSetup was designed to be deployed in one of two possible ways: Web download and CD install.

Web Download

When used in the Web download deployment model, all PSetup files are packaged into a single redistributable (using an MSI or self-extracting EXE) and PSetup is executed once the package has been decompressed.

Although the publisher may choose to redistribute the Microsoft components with their application, the Web download model has been designed to automatically download the required installers if they are not packaged with the original download.

The simplest redistributable package could have the following decompressed structure:

In the above example, PSetup.ini would need to be configured to invoke a URL pointing to the publisher's installer upon completion. See "Post-Install Action" for details on how to do this.

CD Distribution

When used in the CD deployment model, all PSetup files are burned to a CD and run from disk. It is expected that all prerequisite installers will be redistributed with the CD, but if PSetup does not find them it will attempt to download them from Microsoft's servers. The simplest CD installer could have the following structure:

In the above example, PSetup.ini would need to be configured to invoke MyInstaller.msi upon completion. See "Post-Install Action" for details on how to do this.

PSetup Application Flow

As a prerequisite installer, PSetup has a fairly straightforward application flow with almost no use case branching. The steps PSetup follows are:

• PSetup Launched
• Determine Products to Install
• Display EULA
• Installation
• Post-Install Action

PSetup Launched

The first thing PSetup does upon launch is to check its command line options:

Determine Products to Install

After dealing with the command line, PSetup cracks the PSetup.ini file (expected in the same folder) to determine what packages are required on the computer. PSetup.ini looks like this:

[prereqchecks]
MDAC28=Yes
DotNetFW11=Yes
DirectX9=Yes
DirectX9Managed=Yes
DotNetFW11LanguagePack=Yes
DotNetFW11SP1=Yes
DotNetFW11QFE=Yes
MSI20=No 
MSI30=No 

For each "Yes", PSetup performs a check on the local computer to determine whether or not the current installed version of the required product meets or exceeds the version requirement. For example, if DirectX 9.0c is required, but already installed, it will not be installed again. If the value for a key is not "Yes", or if the key is not present, that package is not installed. The above example indicates that the top seven components are required and the last two are not.

Note that the applications will be installed in the order shown in the example above, regardless of whether or not their order is changed in a custom ini file. Also note that PSetup will "promote" components to "Yes" if it detects that they are prerequisites for other required components. For example, if you set DirectX9Managed to "Yes", DirectX and DotNetFW11 will be automatically promoted to "Yes" at run time since they are prerequisites for Direct X 9.0c for Managed Code.

If all required packages have been installed and the /uionlyifneeded option was used, the application exits silently. Otherwise it shows the user a message indicating that their system is up-to-date for this application and skips to the Post-Install Action step.

Display EULA

If PSetup determines from the last step that there are required packages to install, it loads the localized EULA (defaulting to the worldwide English EULA) and populates it with the names of the products to be installed. However, if PSetup was launched with the /continue option, it skips the EULA step, assuming the user has already accepted it. Otherwise the user must accept the EULA to continue to the install step.

Installation

PSetup iterates through the list of required components and installs them. If the application installer does not exist on disk, PSetup connects to Microsoft's servers to download it. Once the package is downloaded, PSetup compares its hash with a known hash for that package (embedded into PSetup) to ensure it hasn't been tampered with.

If one of the Windows components installed requires a reboot, PSetup explains this to the user and reboots the system upon their approval. PSetup writes its own path (adding the /continue option) to

HKEY_LOCAL_COMPUTER\Software\Microsoft\Windows\CurrentVersion\RunOnce

Or

HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\RunOnce

On Windows 98/Millenium computers.

Post-Install Action

Once all required components have been installed, PSetup can launch a post-install action as defined in PSetup.ini using ShellExecute. For example, the following action would launch the default browser and point it to https://www.microsoft.com:

PostInstallAction=https://www.microsoft.com

This action could also point to a local file or third-party URL that links to another installer.

Logging

During execution, PSetup will log its progress in a log file on the C drive. At this point, that log location is not configurable. The log name will be in the format:

psetup.[year].[month].[day]-[hour].[minute].[second].log
such as the following example created on April 26, 2005 at 10:01:56 PM:
psetup.2005.04.26-22.01.56.log

Within the log, each line has three components: a timestamp, a message, and an error code. For example:

2005-04-26 22:01:56 - Wizard started(0)
2005-04-26 22:01:56 - Beginning installation(0)
2005-04-26 22:01:58 - DirectX Managed must be installed(0)

In the event of a failed install, these logs will offer the best source of information regarding error codes. Note that each execution of PSetup creates its own log, so an install process that requires several reboots will create a unique log for each time it is executed.

Packaging

In order to deploy on your Web site you will need to package the psetup.exe application along with the psetup.ini and the unicows.dll files in an auto-extracting Web package and sign it with your own Authenticode signature (to make your customers identify the source of the application). To package the tool you can use any commercial installation package. For your convenience we included the IExpress product that enables you to package the files.

Bug Reports

To report bugs and send feedback on this SDK: http://lab.msdn.microsoft.com/productfeedback/default.aspx.

You can also send e-mail to mcisdk@microsoft.com.