Managing the Microsoft Windows Installer from Microsoft Office 2000 Solutions

Microsoft Corporation

April 1999

Summary: Introduces the new Microsoft® Windows® Installer, which manages the process of installing Microsoft Office 2000 on the user's computer. Discusses ways to modify code in order to take advantage of some of the Windows Installer's features, including handling advertised features and using the automation interface. (15 printed pages)

Contents

Introduction
Products, Features, and Components
Installation States
Handling Advertised Features from Visual Basic Code
Using the Windows Installer Automation Interface
Installing Advertised Features by Calling the Automation Interface
Determining the Installation State for a Feature
Where to Go from Here

Introduction

Microsoft Office 2000 uses the new Microsoft Windows Installer, which manages the process of installing Office on the user's computer. The Windows Installer is an operating system component that is installed on your machine when you begin the Office 2000 installation process. In future versions of Windows, the Windows Installer will be a fundamental part of the operating system.

The Windows Installer provides an application programming interface (API) that developers can use to build complex installation programs, such as the installation program for Office 2000 itself. Developers can also use the Windows Installer API to build programs that aid other users in creating their own custom installation programs.

As an Office solution developer, you don't need to call the Windows Installer API to create a setup program for your solution. You can use existing tools, such as the Package and Deployment Wizard included in Microsoft Office 2000 Developer, to create a setup program that installs the solution onto the user's computer.

There are situations, however, where it may be useful to control the Windows Installer from Visual Basic® for Applications code in an Office solution. In most cases you can do so by setting the Office FeatureInstall property from Visual Basic for Applications. In a few situations, however, you must call the Windows Installer API or use the Windows Installer automation interface, which provides a type library for accessing the API. The following sections briefly describe the Windows Installer and discuss ways in which you can modify your code to take advantage of some of the new features that the Windows Installer provides.

Products, Features, and Components

Information about an application that is installed by the Windows Installer is stored in a custom database. The database has a complex format, but in essence the information stored in this database is divided into three categories: products, features, and components.

• Products are whole applications, such as Microsoft Access. Products include features.
  
  
• Features are individual aspects of an application that don't have to be installed in order for the application to work. For example, the ActiveX® Calendar control that is included with Access is a feature. A feature may consist of one or more components.
  
  
• A component is a file or group of files, each of which is installed when the feature is installed. In the case of the Access Calendar control, there are two components installed when you choose to install this feature: the Calendar control itself (Mscal.ocx) and the Calendar control's Help file (Mscal.hlp).

When you install Office 2000, if you choose Customize, you can select which products and features you want to install, and how you want to install them. You can't use the Office installation program to selectively install certain components that are part of a feature—you must install all components of a feature. If you choose to install the Calendar control, for example, both the control and the Help file are installed.

Installation States

When you perform a custom installation of Office 2000, you have several choices about how you want to install each product and feature. You can choose not to install a product or feature, so that it is never available. Or you can choose to install the product or feature it on your computer, in which case it is always available. You can also specify that a product or feature be run from the network. Finally, you can specify that a particular feature be installed on first use, meaning that the feature will not be installed until the user attempts to use it.

When you choose the Installed on First Use option, the Windows Installer installs the appropriate shortcuts and icons and registers the feature in the Windows registry, but doesn't actually install the files that make up the feature until the first time you use that feature. Features that are installed on first use are said to be "advertised."

Note   Currently only features can be advertised. In future versions of Microsoft Windows, products may also be advertised.

The following table summarizes the different installation states that an Office product or feature may have:

Table 1. Installation States

Because users can choose to advertise a particular feature rather than installing it, it's possible that a user will have chosen to advertise a feature that your solution requires. The following section describes what you can do to handle this case.

Handling Advertised Features from Visual Basic Code

The Application object for each of the Office applications has a FeatureInstall property. This property specifies how the Windows Installer should respond if Visual Basic for Applications code refers to a feature that is advertised but not actually installed on the user's computer. The FeatureInstall property has three possible settings, described in the following table:

Table 2. FeatureInstall Property Settings

Note   The Windows Installer attempts to install only advertised features on demand, which are those marked Installed on First Use in the Office installation program. It will not install a feature that is not advertised—that is, marked Not Available—no matter how you set the FeatureInstall property. On the other hand, if a feature is installed—that is, marked Run from CD, Run from Network, or Run from My Computer—the FeatureInstall property is ignored. In other words, the FeatureInstall property exists only to deal with the case in which the feature is advertised.

When you're developing your solution, you probably can't know for certain whether users have installed a particular feature on their computers, whether they've advertised it, or whether they've chosen not to install it at all. You also can't predict whether or not users will choose to cancel the installation process for an advertised feature. For these reasons, it's important to include solid error handling in procedures that refer to objects provided by advertised features.

A run-time error will occur in each of the following cases:

• Your code refers to a feature that is not installed.
  
  
• Your code refers to a feature that is advertised, but the FeatureInstall property is set to msoFeatureInstallNone.
  
  
• Your code refers to a feature that is advertised, and the FeatureInstall property is set to msoFeatureInstallOnDemand or msoFeatureInstallOnDemandWithUI, but the user cancels the installation process before it is complete.

Each of these scenarios causes the same run-time error, so you can write one error handler to address all three cases. Which run-time error occurs depends on the feature being installed.

By default, the FeatureInstall property is set to msoFeatureInstallNone. If the FeatureInstall property is set to msoFeatureInstallNone, the result you see when your code refers to an advertised feature is the same as what you see if you try to refer to a feature that is not available—you get a run-time error. With this setting for the FeatureInstall property, an Office 2000 solution behaves in exactly the same way as an Office 97 solution that refers to a feature that is not installed.

If you set the FeatureInstall property to msoFeatureInstallOnDemand or msoFeatureInstallOnDemandWithUI, the Windows Installer will attempt to install any advertised feature to which your code refers when the code runs. The user can cancel the installation by clicking Cancel in the Windows Installer dialog box. If the network share or CD-ROM containing the Office 2000 files is not available, the Windows Installer displays an error and prompts the user to cancel or choose a different location.

For example, the Office Assistant is a feature that can be advertised. If your solution uses the Assistant, you can write code to handle all of the possible installation states for the Assistant. If the Assistant is already installed or set up to run from the network, your code doesn't need to do anything. If the Assistant is advertised, the Windows Installer will attempt to install it if the FeatureInstall property is set to msoFeatureInstallOnDemand or msoFeatureInstallOnDemandWithUI. If the user cancels the installation, or if the Assistant is not advertised, you can handle the error gracefully.

The following procedure examines the value of a check box on a form that the user can check to specify whether to display the Assistant. If the user chooses to display the Assistant, the procedure sets the FeatureInstall property to msoFeatureInstallOnDemandWithUI, and then sets the On property of the Assistant to True to display it.

As outlined above, if the Assistant is already installed, then it is displayed and the FeatureInstall property is ignored. If the Assistant is not installed (marked Not Available in the Office 2000 installation program), an error will occur when the On property is set to True. The procedure handles the error and displays a message to the user. If the Assistant is advertised (marked Installed On First Use), the Windows Installer begins installing it. If the user cancels the installation, an error occurs and is handled by the procedure.

Note   The error that occurs when the Assistant is not available is the same error that occurs when the user cancels the installation after it has begun. The error is generated by the Assistant, not by the Windows Installer; the error occurs when the Assistant's On property is set to True, when the Assistant is unavailable.

Private Sub chkDisplayAssistant_Click()
   ' Turns the Assistant on or off, depending on the user's choice
   ' and on the installation state for the Assistant.
   
   Const ASST_NOT_AVAILABLE As Long = -2147467259
   
   If chkDisplayAssistant.Value = True Then
      ' If Assistant is already installed, or not
      ' available, setting the FeatureInstall property
      ' has no effect. The FeatureInstall property affects
      ' only features marked as "Installed on First Use" in
      ' the Office 2000 installation program.
   
      ' Turn on Assistant. If Assistant is not available,
      ' or if user cancels installation, error will occur here.
      On Error Resume Next
      Assistant.On = True
      ' Handle the error. Note that the same error is returned
      ' whether the Assistant was not available or the user
      ' canceled the installation.
      If Err.Number <> 0 Then
         If Err.Number = ASST_NOT_AVAILABLE Then
            MsgBox "Sorry, the Assistant is not currently available."
            GoTo Event_End
         End If
      End If
      Assistant.Filename = cboAssistants.Value & ".acs"
      ' Make Assistant visible.
      Assistant.Visible = True
      ListAssistants
   Else
      ' Turn Assistant off if it's on.
      Assistant.On = False
   End If
   
Event_End:
   Exit Sub
End Sub

This sample procedure appears in the frmDisplayAsst module in the InstallerSamples.xls sample file, which is available in the Sample Applications \Installer folder on the companion CD-ROM to the Microsoft Office 2000/Visual Basic Programmer's Guide (Microsoft Press®, 1999).

Using the Windows Installer Automation Interface

Even if you have the FeatureInstall property set to msoFeatureInstallOnDemand or msoFeatureInstallOnDemandWithUI, the Windows Installer will not install an advertised file given only the file's path name. This means that in order to install Office templates, add-ins, and sample applications from Visual Basic for Applications, you need to call the Windows Installer API, either directly or through the automation interface.

For example, suppose that your solution creates a new Word document based on the built-in Elegant Resume template (Elegant Resume.dot). If this template is advertised, the following code will not install it, and will result in the same run-time error that you would get if the file were not installed at all.

Sub CreateElegantResume()
   Dim doc As Word.Document
   
   Word.Application.FeatureInstall = msoFeatureInstallOnDemand
   Set doc = Word.Documents.Add("C:\Program Files\Microsoft 
Office\Templates" _
      & "\1033\Elegant Resume.dot")
End Sub

To use the Windows Installer automation interface, first set a reference to the Microsoft Windows Installer object library. If this library doesn't appear in the list of available references, click Browse and look for Msi.dll, which should be in the Windows\System folder.

If you prefer to call the Windows Installer API directly, you can do so. The functions that make up the Windows Installer API are available in Msi.dll. For information about how to call a function in a DLL, see Chapter 10, "The Windows API and Other Dynamic-Link Libraries," in the Microsoft Office 2000/Visual Basic Programmer's Guide.

For more information about using either the automation interface or the API, see the Microsoft Windows Installer Programmer's Reference in the Platform SDK.

Installing Advertised Features by Calling the Automation Interface

There are several objects in the automation interface, but as a Visual Basic for Applications developer, you're most likely to use the Installer object. The Installer object is the top-level object in the library, and the one that you use to install a particular feature.

To create a new instance of the Installer object, declare an object variable of type WindowsInstaller.Installer, then use the CreateObject function to create a new instance and assign a reference to the object variable:

Dim msiInstaller As WindowsInstaller.Installer

Set msiInstaller = CreateObject("WindowsInstaller.Installer")

Once you've created a new instance of the Installer object, you can use the ProvideQualifiedComponent method to install an advertised component. Here's the syntax for the ProvideQualifiedComponent method:

ProvideQualifiedComponent(Category, Qualifier, InstallMode)

The three arguments:

• The Category argument takes a String value containing a globally unique identifier (GUID) that uniquely identifies the type of component that you want to install. One or more components can fall under a category. This GUID is stored in the database that provides information to the Windows Installer.
  
  
• The Qualifier argument takes a String value that identifies the particular component that you want to install. It is also stored in the Windows Installer database for the application.
  
  
• The InstallMode argument takes a constant value indicating how a component should be installed, depending on whether related files are installed. For Office solutions, the default constant, msiInstallModeDefault, should be adequate.

Note   When you install an individual component, all of the other components in the feature are installed at the same time. For example, if you install the Elegant Resume template, the other three resume templates are also installed.

Note   The MsiProvideQualifiedComponent function in Msi.dll is the API equivalent of the ProvideQualifiedComponent method.

In order to install a component, you need the GUID for the Category argument and the string for the Qualifier argument. The Sample Applications\Installer folder on the companion CD-ROM to the Microsoft Office 2000/Visual Basic Programmer's Guide includes an Access database, PublishComponents.mdb, which contains the necessary information from the Windows Installer database. You can use this database to find component and feature information for Office applications.

For example, the following code installs the Elegant Resume template if the resume templates are advertised:

Dim msiInstaller As WindowsInstaller.Installer

Set msiInstaller = CreateObject("WindowsInstaller.Installer")
MsiInstaller.ProvideQualifiedComponent("{CC29EB9B-7BC2-11D1-A921-
00A0C91E2AA2}", _
   "1033\elegresu.dot", msiInstallModeDefault)

Note   As with setting the FeatureInstall property, calling the ProvideQualifiedComponent method installs only advertised features. If you attempt to install a feature that is not available, a run-time error occurs.

The InstallerSamples.xls sample file, also available in the Sample Applications\Installer folder, contains a custom class module named OfficeInstall. This class includes a method called InstallOfficeComponent, which you can use to install an Office feature. The InstallOfficeComponent custom method takes a constant that identifies a feature and uses that value to extract the corresponding component ID and component qualifier from the PublishComponents.mdb database. The method optionally takes a Dictionary object and adds to it the names of the files that were installed.

Note   The constants that identify features in the OfficeInstall class are defined in a custom enumeration, the opgInstallFeature enumeration. These constants are provided only to make it easier to extract data from the PublishComponents.mdb database; they do not correlate to any values in the Windows Installer database, nor are they supported by Microsoft.

Const DB_NAME As String = "PublishComponents.mdb"

Function InstallOfficeComponent(lngFeature As opgInstallFeature, _
   Optional dctFiles As Scripting.Dictionary) As Boolean

   ' Installs components associated with specified feature.
   ' Fills Dictionary object with names of all successfully
   ' installed components.

   Dim rstData                  As ADODB.Recordset
   Dim strDbPath               As String
   Dim strSQL                  As String
   Dim strReturn               As String
   Dim strComponentID            As String
   Dim strComponentQualifier   As String
   
   ' Construct SQL statement.
   strSQL = "SELECT ComponentID, Qualifier FROM tblOfficeComponents " _
      & "WHERE OPGFeatureID =" & lngFeature & ";"
   ' Open recordset on active connection.
   Set rstData = New ADODB.Recordset
   rstData.Open strSQL, p_cnnData, adOpenKeyset

   With rstData
      ' If recordset contains records, attempt to install each
      ' component in specified feature.
      If .RecordCount > 0 Then
         Do Until .EOF
            ' Get ComponentID.
            strComponentID = .Fields("ComponentID")
            ' Get component qualifier.
            strComponentQualifier = .Fields("Qualifier")
            
            On Error Resume Next
            ' Install component.
            strReturn = 
p_msiInst.ProvideQualifiedComponent(strComponentID, _
               strComponentQualifier, MsiInstallModeDefault)
            If Err.Number = 0 Then
               If Not dctFiles Is Nothing Then
                  ' Add file name to dictionary.
                  dctFiles.Add Key:=strComponentQualifier, 
Item:=strReturn
               End If
            Else
               InstallOfficeComponent = False
               GoTo InstallOfficeComponent_End
            End If
            ' Move to next record.
            .MoveNext
         Loop
      Else
         Err.Raise ERRNUM_INVALID_FEATURE, , ERRDES_INVALID_FEATURE
      End If
   End With
   
   InstallOfficeComponent = True
   
InstallOfficeComponent_End:
   rstData.Close
   Set rstData = Nothing
   Exit Function
End Function

Determining the Installation State for a Feature

To determine the installation state of a particular feature, you can check the FeatureState property of the Installer object. The FeatureState property takes two arguments: a string containing a GUID that identifies a product, and a string that names a feature.

All of the Office applications are identified by a single GUID, which is returned by the ProductCode property of any Office Application object. You can pass this value as the first argument for the FeatureState property.

The second argument is maintained in the Windows Installer database. Again, the PublishComponents.mdb file on the companion CD-ROM to the Microsoft Office 2000/Visual Basic Programmer's Guide also contains the necessary information. The OfficeInstall custom class found in the InstallerSamples.xls file includes a method named GetFeatureInstallState, which takes a custom constant that identifies a feature, uses that constant to look up the feature in the PublishComponents.mdb database, and extracts the data required by the FeatureState property.

The FeatureState property returns a numeric value that indicates the installation state for the feature. The msiInstallState enumeration contains constants that correspond to different installation states.

The GetFeatureInstallState method of the OfficeInstall class takes a constant that's provided by the opgInstallFeature custom enumeration and returns a constant value specified by the msiInstallState enumeration:

Function GetFeatureInstallState(lngFeature As opgInstallFeature) As 
MsiInstallState
   ' Returns a constant indicating the installation state of
   ' the specified feature.
   Dim rstData            As ADODB.Recordset
   Dim strDbPath         As String
   Dim strSQL            As String
   
   ' Construct SQL statement to retrieve string that 
   ' specifies feature from database.
   strSQL = "SELECT Feature FROM tblFeatures " _
      & "WHERE OPGFeatureID =" & lngFeature & ";"
   ' Open recordset.
   Set rstData = New ADODB.Recordset
   rstData.Open strSQL, p_cnnData, adOpenKeyset
   
   With rstData
      ' If recordset contains records, attempt to install each
      ' component in specified feature.
      If .RecordCount > 0 Then
         ' Check FeatureState property. Pass in the Office
         ' product code (which is the same for all of the Office
         ' applications) and the text string from the database
         ' that specifies the desired feature.
         GetFeatureInstallState = _
            p_msiInst.FeatureState(Application.ProductCode, _
            .Fields("Feature").Value)
      Else
         Err.Raise ERRNUM_INVALID_FEATURE, , ERRDES_INVALID_FEATURE
      End If
   End With
   
   rstData.Close
End Function

For example, the following procedure calls the GetFeatureInstallState custom method of the OfficeInstall object to determine whether the Calendar control is available. The Calendar control can't be advertised; in order for it to be available, it must be installed locally or used over the network or from the CD-ROM.

Function IsCalendarPresent() As Boolean
   ' Determine whether the Calendar control (mscal.ocx) is installed.
   Dim ofiInstall As OfficeInstall
   
   ' Create new instance of OfficeInstall object.
   Set ofiInstall = New OfficeInstall
   
   ' Call the GetFeatureInstallState method to determine the
   ' installation state for the Calendar control.
   Select Case ofiInstall.GetFeatureInstallState(CalendarControl)
      ' If the function returns one of the following constants,
      ' the Calendar control is unavailable or broken.
      Case msiInstallStateAbsent, msiInstallStateBadConfig, _
         msiInstallStateBroken, msiInstallStateIncomplete, _
         msiInstallStateUnknown, msiInstallStateRemoved
         IsCalendarPresent = False
      ' If the function returns one of these constants,
      ' the Calendar control is installed locally or is
      ' run from the network. There's no option to advertise
      ' the Calendar control, so we don't have to consider
      ' that case.
      Case msiInstallStateLocal, msiInstallStateSource
         IsCalendarPresent = True
   End Select
End Function

Both the GetFeatureInstallState and the IsCalendarPresent procedures appear in the OfficeInstall class module in the InstallerSamples.xls sample file, which is available in the Sample Applications\Installer folder on the companion CD-ROM to the Microsoft Office 2000/Visual Basic Programmer's Guide.

The custom OfficeInstall class also includes a custom method named GetAllFeatureInstallStates. This method returns an ADO recordset containing information about the installation state for each Office 2000 feature on the computer. You can use the data returned by the GetAllFeatureInstallStates method to create a report. For example, the InstallerAddin.vbp project in the Sample Applications
\Installer folder uses the GetAllFeatureInstallStates method to generate a report showing current feature installation states for Office 2000. You can run this COM add-in from Microsoft Word, Excel, or PowerPoint®.

Where to Go from Here

For additional information about working with the Windows Installer, see the following resources:

Kelly, Mike. "Gain Control of Application Setup and Maintenance with the New Windows Installer." Microsoft Systems Journal, no. 9 (September 1998): 15–26.

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, this paper should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication. This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.

Microsoft, ActiveX, Microsoft Press, PowerPoint, Visual Basic, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.