How to deploy an ArcGIS Engine application using a setup project

Summary This topic shows how to deploy an ArcGIS Engine application by creating a setup project in Visual Studio.

In this topic

Requirements for deploying an ArcGIS Engine application using a setup project

Review the following requirements before proceeding:
  • An ArcGIS Engine application (called EngineWindowsApplication) using Visual Studio on a development computer has been created. The name of the EngineWindowsApplication executable in this topic is EngineWindowsApplicaiton_NoCode.exe.
  • EngineWindowsApplication will be deployed on another Windows computer (target PC) where the host set of runtime libraries will be ArcGIS Engine Runtime. 
  • The target PC has the .NET Framework 3.5 SP1 installed.
  • In the EngineWindowsApplication code, a call to the following method is used to target ArcGIS Engine Runtime: 
    • ESRI.ArcGIS.RuntimeManager.Bind(ESRI.ArcGIS.ProductCode.Engine)
  • EngineWindowsApplication was built using the release version (not the debug version) in Visual Studio. This makes a smaller deployment footprint and an optimized binary file.
  • EngineWindowsApplication has an icon embedded in the development project. This serves as the image for the shortcut that is created as part of the setup install.
  • EngineWindowsApplication .exe is located on the hard drive in \\DevelopmentPC\image\bin.
  • An ArcGIS Engine authorization file (.prvc) has been obtained from ESRI Customer Service to unlock ArcGIS Engine Runtime software components.
  • EngineWindowsApplication will be deployed using a setup.exe application.

Creating the setup project and setting properties

Do the following steps to create a setup.exe:
  1. Start Visual Studio.
  2. Click File, New, then Project. The New Project dialog box appears. 
  3. On the New Project dialog box, click to expand the Other Project Types node under the Project Types area, select Setup and Deployment, then select Setup Project under the Templates area.
  4. Add the following information on the new Project dialog box:
    1. Type MyEngineApp in the Name text field.
    2. Click Browse to find an appropriate location or type a location in the Location field.
    3. Type MyEngineApp in the Solution Name text field.

      See the following screen shot:


  1. Click OK on the New Project dialog box. The project is created and the files show on the Solution Explorer.
  2. Select the MyEngineApp project in the Solution Explorer, then press F4. The Properties window appears.
  3. On the Properties window, set the following for your application:
    1. Author—GISDeveloper.
    2. InstallAllUsers—Set to True to install for all users on the machine. Set to False if you want the application to only install for the user running the setup.
    3. Manufacturer—MyGISCompany.
    4. ProductName—MyEngineApp.
    5. Version—1.0.0.

      See the following screen shot:

Adding application files to the setup project

The setup project is now ready for the EngineWindowsApplication .exe file that will be deployed to the target PC. Since the image folder with the .exe already exists, add it to the setup project by dragging and dropping it into Visual Studio.
  1. On the Solution Explorer, click the File System Editor button. The File System Editor pane appears. See the following screen shot:


  2. On the File System Editor pane, there is a File System on Target Machine node and an Application Folder node. Drag and drop the \\DevelopmentPC\image\bin folder in Windows Explorer into that location. See the following screen shot:

  1. Visual Studio automatically adds any dependency files that are used by the EngineWindowsApplication .exe file into the setup project. These added dependency files are in the Solution Explorer under the Detected Dependencies folder. It is a violation of ESRI's license agreement to distribute ESRI assemblies and binary files as part of the setup project. All ESRI assemblies and binary files are installed as part of the core ArcGIS Engine Runtime installation.
    1. Remove the automatically detected ESRI assemblies and binary files by selecting them in the Solution Explorer.
    2. Right-click and choose Exclude. The only files that are not excluded are the EngineWindowsApplication .exe and the Microsoft .NET Framework. See the following screen shot:

Setting the default installation location

When the user runs setup.exe on the target PC, the default location the install uses needs to be set. Do the following to set this location:
  1. Click the Application Folder node on the File System Editor pane, then press F4. The Properties window appears.
  2. On the Properties window, set the DefaultLocation to [ProgramFilesFolder]\[ProductName]. See the following screen shot:

Creating a shortcut on the user's program menu

Do the following steps to create a shortcut on the program menu when the application is installed:
  1. On the File System Editor pane, click to expand the Application Folder and bin folder nodes. Right-click the EngineWindowsApplication_NoCode.exe file, then select Create Shortcut to EngineWindowsApplication_NoCode.exe. See the following screen shot:


  1. Name the shortcut EngineWindowsApplication_NoCode.exe. The shortcut is created in the bin folder; however, the shortcut needs to be in the User's Programs Menu folder. See the following screen shot:

  1. Click the User's Programs Menu folder on the File System Editor pane. Right-click and select Add. Rename the new folder, MyEngineApp. See the following screen shot:


  2. Drag and drop the shortcut from the bin folder into the new MyEngineApp folder. See the following screen shot:



    See the following screen shot that shows the shortcut in the MyEngineApp folder:



    The shortcut will not point to the same icon as the one in the bin folder. Do the following steps to correct this issue:
  3. Select the shortcut in the User's Programs Menu > MyEngineApp folder, then press F4. The Properties window appears.
  4. On the Properties window, click the Icon property drop-down arrow, then click Browse. See the following screen shot:


  5. After you click Browse on the preceding screen shot, the Icon dialog box appears. See the following screen shot:


  6. Click Browse on the Icon dialog box. The Select Item in Project dialog box appears. Click the Look in drop-down arrow and click Application Folder, then select the bin folder that you added to the setup. See the following screen shot:

  1. Select EngineWindowsApplication_NoCode.exe, then click OK. 
  2. Select the icon Visual Studio extracted from the .exe file to apply it to your shortcut. See the following screen shot:

Adding launch conditions

The setup program now knows where to place the EngineWindowsApplication .exe on disk. A successful setup program verifies that any requirements are met before allowing the installation to complete. In the case of an ArcGIS Engine application, ArcGIS Engine Runtime needs to exist first. Do the following steps to add an error message that appears if the target PC does not have ArcGIS Engine Runtime installed:
  1. On the Solution Explorer, click the Launch Conditions Editor button. See the following screen shot:

  1. After you click the Launch Conditions Editor button, the Launch Conditions pane appears with a Requirements on Target Machine node. On the Launch Conditions pane, Visual Studio has detected and added a launch condition for the .NET Framework.
  2. Right-click the Requirements on Target Machine node, then choose Add Registry Launch Condition since you know the registry key for ArcGIS Desktop. See the following screen shot:


  1. A Search for RegistryEntry1 node is added under the Search Target Machine folder, and a Condition1 has been added under the Launch Conditions folder. See the following screen shot:


  1. Click Search for RegistryEntry1 and press F4. The Properties window appears. Set the following values on the Properties window:
    1. RegKey—SOFTWARE\ESRI\Engine10.0
    2. Value—RealVersion

      See the following screen shot:


  1. On the Launch Conditions pane, click to expand the Launch Conditions node, then click Condition1. Set the following properties on the Properties window:
    • Condition—REGISTRYVALUE1="10.0"
    • Message—ArcGIS Engine 10.0 is required before you can complete this setup.

      See the following screen shot:


You can review what the RealVersion Value Data attribute is in Windows registry by typing regedit at a run line to open the Registry Editor, then click to expand the following nodes:
  • My Computer\HKEY_LOCAL_MACHINE\SOFTWARE\ESRI\Engine10.0
If you run the setup.exe test at this point and you do not have ArcGIS Engine 10 installed, the following dialog box appears and the installation terminates:

Testing the setup.exe

Do the following steps to test the setup program on the target PC:
  1. Copy the setup.exe and setup.msi files from the development PC onto the target PC.
  2. Double-click the setup.exe and proceed through the series of wizards. See the following screen shot:


  3. When the setup is complete, ensure EngineWindowsApplication is installed properly on the target PC. To check that a shortcut exists and EngineWindowsApplication runs, click Start, All Programs, MyEngineApp, then EngineWindowsApplication_NoCode.exe. See the following screen shot:

  1. You can also look on the hard drive for the specified location as part of the setup to view where the EngineWindowsApplication .exe was placed. See the following screen shot:


  1. A successful setup program also uninstalls all files on the hard drive, as well as remove any shortcuts. To test the uninstall, open the Add or Remove Programs dialog box in the Control Panel and click Remove for the MyEngineApp program. See the following screen shot:



    When the uninstall is complete, EngineWindowsApplication is no longer available as a shortcut, and all MyEngineApp files and directories (pertaining to the MyEngineApp application) are removed from the hard drive. 


See Also:

Deploying stand-alone applications



Development licensing Deployment licensing
Engine Developer Kit Engine Runtime