Installing ArcGIS Engine Runtime for Windows


Summary
This topic introduces the technology used to create the installation program for ArcGIS Engine Runtime and discusses various installation mechanisms.

In this topic


About the ArcGIS Engine installation program

The ArcGIS Engine Runtime installation program, or setup, was created using the Windows Installer (MSI) technology from Microsoft. This technology uses a package file (.msi) and a client-side installer service (msiexec.exe). Windows Installer is a service that runs on your operating system. This service enables the operating system to manage the installation and uses the information contained within the package file to install the software.
The msiexec.exe program is a component of Windows Installer. Msiexec.exe uses a dynamic-link library (msi.dll) to read the package files (.msi), apply transforms (.mst), and incorporate command-line options.
An MSI-based setup consists of features. A feature is an individual portion of the application's total functionality that can be installed independently. The ArcGIS Engine setup consists of installation features shown in the following table:
Feature
Descriptive feature name
Description
ArcEngine
ArcGIS Engine
ArcGIS Engine
DotNetRuntime
ArcGIS Engine .NET
.NET assemblies
JavaRuntime
ArcGIS Engine Java
Java archives
Python
Python
Python 2.5.1 and Numerical Python 1.1
All ArcGIS Engine software-based applications depend on an installation of the ArcEngine feature. Applications that are built using the Java and .NET application programming interfaces (APIs) for ArcGIS Engine require installations of the JavaRuntime and DotNetRuntime features, in addition to the ArcEngine feature.
ArcGIS Engine is supported on Windows 2000, Windows XP Professional, Windows 7, Windows Vista, Windows Server 2008 Standard, Windows Server 2008 R2, and Windows 2003 Server.
For additional or updated information regarding ArcGIS Engine Runtime system requirements, see the ESRI Support Center at  http://support.esri.com .

Installing ArcGIS Engine

As previously mentioned, ArcGIS Engine software-based applications require that ArcGIS Engine Runtime be installed on the end user's machine. Installation of the runtime can be handled in one of the following two ways:
More information on the Windows Installer can be found in the Windows Installer Software Development Kit (SDK). To download the kit, see Platform SDK Components for Windows Installer Developers  from the Microsoft Developer Network (MSDN) Web site .
You cannot redistribute individual ArcGIS Engine Runtime files. The installation mechanisms discussed in this document are the only means of installing ArcGIS Engine Runtime files .
The following outlines the general requirements for the installation of the ArcGIS Engine Runtime—regardless of which installation mechanism you choose—and the necessary steps to install the runtime successfully using your chosen mechanism.
General installation requirements
Irrespective of the installation method you chose for ArcGIS Engine Runtime, you should be aware of the following:
End user installs ArcGIS Engine
In this case, the end user installs the ArcGIS Engine directly from the CD ESRI provided with the ArcGIS Engine product or from a CD that you created by copying the contents of the ArcGIS Engine CD image. 
Perform the following steps or provide similar instructions to your end users:
  1. Confirm that any currently installed ArcGIS products are the same version as the ArcGIS Engine Runtime setup to be installed. To check if any of these products are installed on the machine and to verify the version number, do the following:
    1. Click Start, Control Panel, and open the Add/Remove Programs dialog box.
    2. If ArcGIS Engine Runtime is listed in the programs list, it is installed on the machine. Confirm that ArcGIS Engine Runtime is the correct version. Click the support information link to determine the product version number. Close the window and proceed to the installation steps for <your application name> if needed.
    3. If no ArcGIS products are shown in the programs list, proceed to Step 2. If ArcGIS products are shown in the programs list, click the support information link to view the version of the product.
    4. If the versions displayed are the same, proceed to Step 2. If the versions displayed are not the same, the products need to be removed before installing ArcGIS Engine Runtime. Do not proceed to Step 2 until these products have been uninstalled.
  2. Launch the ArcGIS Engine Runtime installation program by navigating to the CD drive location and the \\Windows subfolder, then double-click the setup.exe file.
  3. In the installation, click Next if all Windows applications are closed.
  4. Review and accept the license agreement and click Next to proceed with the installation.
  5. Choose the installation type and click Next to continue. See the following screen shot:
If the ArcGIS Engine software-based application to be installed requires Java, choose the Custom option to manually select the JavaRuntime feature or choose the Complete option to install all ArcGIS Engine Runtime installation features.
  1. Follow any further instructions of the ArcGIS Engine Runtime installation until it indicates that the installation is complete. If needed, proceed to the installation steps for <your application name>.
The installation of ArcGIS Engine Runtime is now complete. If needed, proceed to the installation steps for <your application name>.
Installing an ArcGIS Engine Runtime service pack
If your application also requires an ArcGIS Engine service pack, you can either instruct your user to download the service pack from the ESRI Support Center or you can provide the service pack (.msp file) on the ArcGIS Engine Runtime CD.
Distribute the following steps or provide similar instructions to your users—the steps assume ArcGIS Engine Runtime is already on the target machine:
  1. Check whether the required ArcGIS Engine Runtime service pack has been installed to the target machine by doing the following:
    1. Click Start, then Run. In the Run dialog box, type Regedit to open the Registry Editor.
    2. Check for the SPNumber registry key under the following registry hive: HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\. The SPNumber value reflects the service pack number installed.
  2. Install the service pack using the following command line:
    msiexec.exe /p <location of msp file>\ArcGIS<Product>.msp REINSTALL=ALL REINSTALLMODE=omus
ArcGIS Engine Runtime setup included in the application's installation program
The second way to distribute the ArcGIS Engine Runtime is to incorporate its setup in your ArcGIS Engine software-based application's installation program. This is possible because ArcGIS Engine Runtime can be installed without a graphical user interface by running the setup using Windows Installer command line parameters. This process utilizes the .msi file and client-side installer service (msiexec.exe) command line parameters.
The following table shows some available msiexec.exe command line parameters:
 
Option
Parameters
Description
/I
Package | ProductCode
Installs or configures a product
/a
Package
Administrative installation option—installs a product on the network
/x
Package | ProductCode
Uninstalls a product
/q
n | b | r | f
Sets user interface (UI) level:
  • q:No UI.
  • qn:No UI.
  • qb:Basic UI—use qb! to hide the Cancel button.
  • qr:Reduces UI with no modal dialog box displayed at the end of the installation.
  • qf:Full UI and any authored FatalError, UserExit, or Exit modal dialog boxes at the end.
  • qn+: No UI except for a modal dialog box displayed at the end.
  • qb+: Basic UI with a modal dialog box displayed at the end. The modal dialog box is not displayed if the user cancels the installation—use qb+! or qb!+ to hide the Cancel button.
  • qb–: Basic UI with no modal dialog boxes. Please note that /qb+– is not a supported UI level—use qb–! or qb!– to hide the Cancel button.
The!option is available with Windows Installer 2.0 and works only with a basic UI. It is not valid with a full UI.
/? or /h
 
Displays copyright information for Windows Installer.
 
Option parameters description
These commands can be used to perform various installation functions. The available features to install are specified with the ADDLOCAL parameter. As previously shown , ArcGIS Engine has the following installation features:
Feature
Descriptive feature name
Description
ArcEngine
ArcGIS Engine
ArcGIS Engine
DotNetRuntime
ArcGIS Engine .NET Runtime
.NET assemblies
JavaRuntime
ArcGIS Engine Java Runtime
Java archives
Python
Python
Python 2.5.1 and Numerical Python 1.0.3
The following shows some example functions and the commands used to achieve them:
Command line parameters can be used to include the ArcGIS Engine Runtime setup in your application's setup in any of the following three methods:
If your application requires an ArcGIS Engine Runtime service pack, one of the following standard command lines can be used to apply a service pack (these examples are for installing a service pack with the filename  ArcGISEngine93sp1.msp ):
In addition to the general installation requirements  that apply to any installation of ArcGIS Engine Runtime, the following are applicable to installs that are incorporated in other applications:
Setup process steps
Include the following steps in the setup process:
  1. Before launching the ArcGIS Engine Runtime setup, check whether ArcGIS Engine Runtime and any needed optional features—JavaRuntime and DotNetRuntime—have already been installed to the target machine. If your application also requires an ArcGIS Engine Runtime service pack, check that the current service pack is on the user's machine.
    1. For ArcGIS Engine Runtime, check for the following registry key:
      HKEY_LOCAL_MACHINE\Software\ESRI\ArcGIS Engine Runtime. T he RealVersion registry key will have a value of 9.3.

      If the key exists, ArcGIS Engine Runtime has been installed on the target machine, and you may not need to launch the ArcGIS Engine Runtime setup. Continue to Step 1b if your application requires the Java feature or Step 1c if your application requires the .NET feature. Otherwise, proceed with the installation of your application.

      If the key does not exist, ArcGIS Engine Runtime has not been installed. Continue to Step 1b if your application requires the Java feature or Step 1c if your application requires the .NET feature. Otherwise, proceed to Step 2.

    1. For Java, check the following registry entry:
      HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\ArcGIS Engine Runtime

    The JAVA_Support registry key will have a data value of TRUE if the ArcGIS Engine Runtime Java feature is installed. Proceed to Step 1c if your application requires the .NET feature. Otherwise, proceed with the installation of your application.

    If the value displayed is FALSE,  the Java feature is not installed. Proceed to Step 1c if your application requires the .NET feature. Otherwise, proceed to Step 2 to install the Java feature.
    1. For .NET, check the following registry entry:
      HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\ArcGIS Engine Runtime

      The .NET_Support registry key will have a data value of TRUE if the ArcGIS Engine Runtime .NET Support feature is installed.

      If the value displayed is "FALSE the .NET Support feature is not installed. Proceed to Step 2 to install the DotNetRuntime feature.
     
  2. Launch the ArcGIS Engine Runtime setup at the end of an MSI-based setup , in a batch file , or in a scripted setup .
If your application requires the Java Runtime or DotNetRuntime features of the ArcGIS Engine Runtime, install them using the ADDLOCAL Windows Installer command in your script, for example, ADDLOCAL=DotNetRuntime or ADDLOCAL=JavaRuntime.
If you choose to install only the DotNetRuntime or JavaRuntime feature and the core ArcGIS Engine Runtime (ArcEngine feature) does not exist on the target machine, the setup will automatically install the ArcEngine feature as well as the Java and .NET features. The .NET feature is included in the complete install if the .NET Framework is detected on the target machine.
Launching the installation at the end of an MSI-based setup
Launching the ArcGIS Engine Runtime installation program at the end of an MSI-based setup is an example of installing the necessary ArcGIS Engine Runtime features without having to perform the installation directly from the ArcGIS Engine Runtime CD provided by ESRI. The following example discusses this installation mechanism.
Example 1: ArcGIS Engine Runtime 9.3 is required
In this example, the ArcGIS Engine Runtime setup launches once the Finish button is clicked to complete the installation of your application. The MSI authoring tools included with Wise for Windows Installer are used to add custom actions behind the Finish button. This example assumes that the ArcGIS Engine Runtime setup resides in the same location as your application's setup program. In this case, setup.exe resides in a folder named ArcEngine.

Perform the following steps to launch the setup.exe file for ArcGIS Engine Runtime when it is located in an ArcEngine folder on your application's media:
  1. Create the properties MSI_PATH and ArcEngineExists and initialize them to 1 in the Property table.
  2. Perform a system check for ArcGIS Engine Runtime at the beginning of your setup program. The system check should search for the RealVersion registry key and set the property ArcEngineExists to true if the registry value returned is 9.3—for applications built on 9.3— HKEY_LOCAL_MACHINE\Software\ESRI\ArcGIS Engine Runtime.
  3. In the Custom Action Name text box of the Execute Program From Path dialog box, create the custom action Launch_Engine_MSI. In the Property field, set the property of this custom action to MSI_PATH (the path from which to execute the program). Leave the Command Line field blank, as setup.exe is being launched. See the following screen shot:

  1. In the Exit dialog box of your application's setup program, add two actions behind the Finish button control. See the following screen shot:



    The first action sets the MSI_PATH property to [SourceDir]ArcEngine\Setup.exe. This will change depending on where the ArcGIS Engine Runtime setup is located on the media. In this example, setup.exe is located on the CD in a folder named ArcEngine. See the following screen shot:



    The second action calls the previously created Launch_Engine_MSI. See the following screen shot:



    Both of these custom actions should only execute if the property ArcEngineExists does not equal true.
Example 2: ArcGIS Engine Runtime and a service pack are required
In this example, ArcGIS Engine Runtime and a service pack are required by your application. This example results in the following two scenarios:
Scenario 1: Provide admin installation
P rovide an admin installation on the CD that consists of the original .msi file that has been patched with the required service pack. When deploying ArcGIS Engine Runtime with this deployment method, you do not launch the original setup.msi file followed by a .msp file (service pack file).
On your CD, you must provide an admin installation of ArcGIS Engine Runtime with the service pack applied. This creates a patched setup.msi file that you can install on your user's machine. The patched setup.msi file will contain both the entire ArcGIS Engine Runtime files and those files updated by the service pack. This is required for those users that do not have ArcGIS Engine Runtime and the required service pack.
To create an admin installation:
  1. Install ArcGIS Engine Runtime using the following command line:
    msiexec /a <Engine Runtime CD>\setup.msi
  2. Apply the service pack to this admin location using the following command line (in the example, the service pack is named ArcGISEngine93sp1.msp ):
    msiexec /a <location of admin installation>\setup.msi /p <location of msp file>ArcGISEngine93sp1.msp REINSTALL=ALL REINSTALLMODE=omus
  3. Copy the entire content of your admin installation—which will now have the service pack applied—to your application's CD for redistribution.
Do the following steps to launch the setup.exe file for ArcGIS Engine Runtime when it is located in an ArcEngine folder on your application's media:
  1. Create the properties MSI_PATH and ArcEngineExists. Initialize the created properties to 1 in the Property table.
  2. Perform a system check for ArcGIS Engine Runtime at the beginning of your setup program. The system check should search for the RealVersion and SPNumber registry key and set the property ArcEngineExists to true if the returned registry values match your requirement.
  3. In the Custom Action Name text box of the Execute Program From Path dialog box, create the custom action Launch_Engine_MSI. In the Property text box, set the property of this custom action to MSI_PATH (the path from which to execute the program). Leave the Command Line field blank, as setup.exe is being launched.

  1. In the Exit dialog box of your application's setup program, add two actions behind the Finish button control. See the following screen shot:  



    The first action sets the MSI_PATH property to [SourceDir]ArcEngine\Setup.exe. This will change depending on where the ArcGIS Engine Runtime setup is located on the media. In this example, setup.exe is located on the CD in a folder named ArcEngine. The setup.exe file will be the admin installation with the required service pack applied. See the following screen shot:



    The second action calls the Launch_Engine_MSI that you previously created. See the following screen shot:



    Both of these custom actions should execute only if the property ArcEngineExists does not equal true. ArcEngineExists should equal true only if ArcGIS Engine Runtime and the service pack are detected on the target machine.
Scenario 2: Provide required service pack
Provide the required ArcGIS Engine Runtime service pack (.msp file) on the CD. When deploying ArcGIS Engine Runtime in this particular deployment method, your user will have ArcGIS Engine Runtime already on the target machine and only the service pack is required. Do the following steps to launch the ArcGIS Engine Runtime service pack when it's on your application's media:
  1. Create Properties MSP_PATH, MSIEXEC_PATH, and InstallSP. Initialize them to 1 in the Property table.
  2. Perform a system check for ArcGIS Engine Runtime and the service pack at the beginning of your setup program. The system check should search for the ArcGIS Engine Runtime RealVersion registry key and SPNumber registry key. The InstallSP property should be set to true if the RealVersion registry key value matches your requirement but the SPNumber registry key value does not match your requirement. In this case, the machine has the ArcGIS Engine Runtime product installed but does not have the required service pack.
  3. In the Custom Action Name text box of the Execute Program From Path dialog box, create the custom action Launch_Engine_SP_1. You can change the number to the version of the ArcGIS Engine Runtime service pack your application requires. This example is installing ArcGIS Engine Runtime service pack 1. This custom action will launch the service pack (.msp file) using the following syntax:
    msiexec.exe /p <location of service pack>\ArcGISEngine93sp1.msp /qn
  4. In the Execute Program From Path dialog box, set the property to MSIEXEC_PATH. In the Command Line field, add [MSP_PATH]. MSP_PATH is the path to the ArcGIS Engine Runtime service pack 1 .msp file that will be available on the media. Using the previous syntax, MSIEXEC_PATH will be [SystemFolder]msiexec.exe. MSP_PATH will be /p <location of service pack>\ArcGISEngine93sp1.msp /qn. These two properties will be defined in the Exit dialog box's Finish button. See the following screen shot:


  5. In the Exit dialog box of your application's setup program, add three actions behind the Finish button control.
  6. The first action sets the MSIEXEC_PATH property to [SystemFolder]msiexec.exe. See the following screen shot:

  1. The second action sets the MSP_PATH to /p [SourceDir]ArcEngine\ArcGISEngine93sp1.msp /qn. MSP_PATH will change depending on where the ArcGIS Engine Runtime service pack is located on the media. In this example, ArcGISEngine93sp1.msp is located on the CD in the ArcEngine folder. See the following screen shot:

  1. The third action calls the Launch_Engine_SP_1 that you previously created. See the following screen shot:

These three custom actions should execute only if the LaunchSP property does not equal true.
Launching the ArcGIS Engine Runtime installation in a scripted setup
A second way to install the ArcGIS Engine Runtime in your application is with a scripted setup that utilizes the available command line parameters. The following code example was created using the Wise InstallMaster setup authoring software—it includes the installation of ArcGIS Engine Runtime and service pack 1:
Rem Set variable
Set variable MSI_PATH to <CDROM>\ArcEngine\setup.msi
Set variable MSP_PATH to <CDROM>\ArcGISEngine93sp1.msp
Rem launch ArcGIS Engine Runtime setup program silently – No UI
Execute %SYS32%\msiexec.exe /i %MSI_PATH% /qn (Wait)
Rem launch ArcGIS Engine Runtime service pack silently – No UI
Execute %SYS32%\msiexec.exe /p %MSP_PATH% /qn (Wait)
Launching the ArcGIS Engine Runtime installation in a batch file
Another way the ArcGIS Engine Runtime setup can be combined with your application's installation program is in batch files. Again, the following code example takes advantage of the available command line parameters and implements them in a batch file rather than a scripted setup —t his code example includes the installation of ArcGIS Engine Runtime and service pack 1:
REM ############################
REM Set variables
SET MSI_PATH=<CDROM>\ArcEngine\Setup.msi
SET MSP_PATH=<CDROM>\ArcGISEngine93sp1.msp
REM ############################
REM Launch MSI Silently - NO UI
msiexec.exe /i "%MSI_PATH%" /qn
msiexec.exe /p "%MSP_PATH%” /qn
REM Launch MSI Silently - Reduced UI
msiexec.exe /i "%MSI_PATH%" /qb
msiexec.exe /p "%MSP_PATH%" /qb
REM Launch MSI Silently - No UI except for a modal dialog box displayed at the end.
msiexec.exe /i "%MSI_PATH%" /qn+
msiexec.exe /p "%MSP_PATH%" /qn+
The following code examples also show the use of a batch file; however, these show the command line parameters that should be used to install the ArcGIS Engine JavaRuntime or DotNetRuntime features:
 
ArcGIS Engine Runtime menu shortcuts
By default, a complete installation of ArcGIS Engine Runtime creates the following shortcuts on the ArcGIS menu (accessed from Start, All Programs or from Start, Programs):
See the following screen shot:
The following command line parameters provide options to display or not display the shortcuts on the ArcGIS menu:
In the following example, ArcGIS Engine Runtime is installed silently without shortcuts:
Uninstalling ArcGIS Engine Runtime
Consider the following before uninstalling ArcGIS Engine Runtime:


See Also:

Installing ArcGIS Engine Runtime silently