How to deploy a custom component using a setup project

In this topic

• About deploying a custom component using a setup project
• Creating the setup.exe file
  • Creating the setup project and setting properties
  • Adding application files to the setup project
  • Setting the default installation location
  • Adding launch conditions
  • Registering the CustomComponent .dll file using ESRIRegAsm.exe
  • Testing the setup.exe file

About deploying a custom component using a setup project

• You have created an ArcGIS Desktop custom component for ArcMap (called CustomComponent) using the Esri integrated development environment (IDE) features in Visual Studio on a development computer (called DevelopmentPC). The name of the CustomComponent in this topic is ArcMapClassLibrary_Implements.dll.
• Within the CustomComponent, COM component category registration code calls have been used and the Visual Studio project properties have the "Register for COM interop" check box selected. For more information, see How to ensure that COM component category and COM interop are used in custom components.
• Within the CustomComponent, you can determine the Category and Caption properties. For more information, see Obtaining the Category and Caption property information of a custom component. In this topic, CustomComponents have a Developer Samples category and an ArcMapClassLibrary_Implements caption.
• The CustomComponent was built using the release version (not the debug version) in Visual Studio. This makes a smaller deployment footprint and an optimized binary file.
• The CustomComponent .dll file's location is \\DevelopmentPC\image\bin.

• You want to deploy the CustomComponent on another computer (called TargetPC) that has ArcGIS Desktop installed and fully licensed.
• You want to deploy the CustomComponent using a setup.exe application using Visual Studio's setup project template.
• Your deployment is essentially an out-of-the-box type of customization. Other developers will not consume or extend your custom .dll file via additional programming. 

Creating the setup.exe file

Creating the setup project and setting properties

Adding application files to the setup project

1. On the Solution Explorer, click the File System Editor button. The File System Editor tabbed window appears. See the following screen shot that shows the File System Editor button:
   
   
   
2. On the File System Editor window, the File System on Target Machine node shows with an Application Folder node. Drag and drop the bin folder (DevelopmentPC\image\bin) in Windows Explorer into the Application Folder. See the following screen shot that shows the bin folder and the Application Folder:
   
   
   
3. Visual Studio automatically adds dependency files that are used by the CustomComponent .dll file into the setup project. These added dependency files show on the Solution Explorer in the Detected Dependencies folder. It is a violation of the Esri license agreement to distribute Esri assemblies and binary files as part of setup project. All Esri assemblies and binary files are installed as part of the core ArcGIS Desktop installation.
   1. Select the automatically detected Esri assemblies and binary files on the Solution Explorer.
   2. Right-click and choose Exclude. The only files that are not excluded is the CustomComponent .dll and the Microsoft .NET Framework.
   
   See the following screen shot that shows the excluded dependencies:
   
   

Setting the default installation location

1. Click the Application Folder on the File System Editor window, then press F4. The Properties window appears.
2. Set the DefaultLocation property to [ProgramFilesFolder]\[ProductName]. See the following screen shot that shows the DefaultLocation property:
   
   
   

Adding launch conditions

1. On the Solution Explorer, click the Launch Conditions Editor button. The Launch Conditions Editor tabbed window appears. See the following screen shot that shows the Launch Conditions Editor button:
   
   

2. On the Launch Conditions Editor window, there is a Requirements on Target Machine node. Under the Launch Conditions node, Visual Studio detected and added a launch condition for the .NET Framework.
   1. Select the Requirements on Target Machine node.
   2. Right-click and choose Add Registry Launch Condition (since you know the registry key for ArcGIS Desktop).
   3. A Search for RegistryEntry1 node is added under the Search Target Machine folder and a Condition1 is added under the Launch Conditions folder.
      
      See the following screen shot that shows the added launch conditions:
      
      
      
3. Click the Search for RegistryEntry1 node, then specify the following properties on the Properties window:
   • RegKey—SOFTWARE\ESRI\Desktop10.0
   • Value—RealVersion
     
   See the following screen shot that shows the specified properties on the Properties window:
   
   
   

4. On the Launch Conditions Editor window, click Launch Conditions, then Condition1. On the Properties window, check for ArcGIS Desktop 10, and specify the following properties:
   • Condition property—REGISTRYVALUE1="10.0"
   • Message property—ArcGIS Desktop 10.0 is required before you can complete this setup.
     
   See the following screen shot that shows the Condition and Message properties:
   
   
   

Registering the CustomComponent .dll file using ESRIRegAsm.exe

1. Start Visual Studio and click File, then New Project. The New Project dialog box appears.

using System;
using System.Collections;
using System.Collections.Generic;
using System.ComponentModel;
using System.Configuration.Install;
using System.Linq;
using System.Diagnostics;

namespace InvokeESRIRegAsm
{
    [RunInstaller(true)]
    public partial class Installer1: Installer
    {
        public Installer1()
        {
            InitializeComponent();
        }

        public override void Install(System.Collections.IDictionary stateSaver)
        {
            base.Install(stateSaver);

            //Register the custom component.
            //-----------------------------
            //The default location of the ESRIRegAsm utility.
            //Note how the whole string is embedded in quotes because of the spaces in the path.
            string cmd1="\"" + Environment.GetFolderPath
                (Environment.SpecialFolder.CommonProgramFiles) + 
                "\\ArcGIS\\bin\\ESRIRegAsm.exe" + "\"";
            //Obtain the input argument (via the CustomActionData Property) in the setup project.
            //An example CustomActionData property that is passed through might be something like:
            // /arg1="[ProgramFilesFolder]\[ProductName]\bin\ArcMapClassLibrary_Implements.dll",
            //which translates to the following on a default install:
            //C:\Program Files\MyGISApp\bin\ArcMapClassLibrary_Implements.dll.
            string part1=this.Context.Parameters["arg1"];

            //Add the appropriate command line switches when invoking the ESRIRegAsm utility.
            //In this case: /p:Desktop=means the ArcGIS Desktop product, /s=means a silent install.
            string part2=" /p:Desktop /s";

            //It is important to embed the part1 in quotes in case there are any spaces in the path.
            string cmd2="\"" + part1 + "\"" + part2;

            //Call the routing that will execute the ESRIRegAsm utility.
            int exitCode=ExecuteCommand(cmd1, cmd2, 30000);
        }

        public override void Uninstall(System.Collections.IDictionary savedState)
        {
            base.Uninstall(savedState);

            //Unregister the custom component.
            //-----------------------------
            //The default location of the ESRIRegAsm utility.
            //Note how the whole string is embedded in quotes because of the spaces in the path.
            string cmd1="\"" + Environment.GetFolderPath
                (Environment.SpecialFolder.CommonProgramFiles) + 
                "\\ArcGIS\\bin\\ESRIRegAsm.exe" + "\"";
            //Obtain the input argument (via the CustomActionData Property) in the setup project.
            //An example CustomActionData property that is passed through might be something like:
            // /arg1="[ProgramFilesFolder]\[ProductName]\bin\ArcMapClassLibrary_Implements.dll",
            //which translate to the following on a default install:
            //C:\Program Files\MyGISApp\bin\ArcMapClassLibrary_Implements.dll.
            string part1=this.Context.Parameters["arg1"];

            //Add the appropriate command line switches when invoking the ESRIRegAsm utility.
            //In this case: /p:Desktop=means the ArcGIS Desktop product, /u=means unregister the Custom Component, /s=means a silent install.
            string part2=" /p:Desktop /u /s";

            //It is important to embed the part1 in quotes in case there are any spaces in the path.
            string cmd2="\"" + part1 + "\"" + part2;

            //Call the routing that will execute the ESRIRegAsm utility.
            int exitCode=ExecuteCommand(cmd1, cmd2, 30000);
        }

        public static int ExecuteCommand(string Command1, string Command2, int
            Timeout)
        {
            //Set up a ProcessStartInfo using your path to the executable (Command1) and the command line arguments (Command2).
            ProcessStartInfo ProcessInfo=new ProcessStartInfo(Command1, Command2);
            ProcessInfo.CreateNoWindow=true;
            ProcessInfo.UseShellExecute=false;

            //Invoke the process.
            Process Process=Process.Start(ProcessInfo);
            Process.WaitForExit(Timeout);

            //Finish.
            int ExitCode=Process.ExitCode;
            Process.Close();
            return ExitCode;
        }
    }
}

Imports System.ComponentModel
Imports System.Configuration.Install

Public Class Installer1
    
    Public Sub New()
        MyBase.New()
        
        'This call is required by the Component Designer.
        InitializeComponent()
        
        'Add initialization code after the call to InitializeComponent.
    End Sub
    
    Public Overrides Sub Install(ByVal stateSaver As System.Collections.IDictionary)
    MyBase.Install(stateSaver)
    
    'Register the custom component.
    '-----------------------------
    
    'The default location of the ESRIRegAsm utility.
    'Note how the whole string is embedded in quotes because of the spaces in the path.
    Dim cmd1 As String="""" + Environment.GetFolderPath(Environment.SpecialFolder.CommonProgramFiles) + "\ArcGIS\bin\ESRIRegAsm.exe" + """"
    
    'Obtain the input argument (via the CustomActionData Property) in the setup project.
    'An example CustomActionData property that is passed through might be something like:
    '/arg1="[ProgramFilesFolder]\[ProductName]\bin\ArcMapClassLibrary_Implements.dll",
    'which translates to the following on a default install:
    'C:\Program Files\MyGISApp\bin\ArcMapClassLibrary_Implements.dll.
    Dim part1 As String=Me.Context.Parameters.Item("arg1")
    
    'Add the appropriate command line switches when invoking the ESRIRegAsm utility.
    'In this case: /p:Desktop=means the ArcGIS Desktop product, /s=means a silent install.
    Dim part2 As String=" /p:Desktop /s"
    
    'It is important to embed the part1 in quotes in case there are any spaces in the path.
    Dim cmd2 As String="""" + part1 + """" + part2
    
    'Call the routing that will execute the ESRIRegAsm utility.
    Dim exitCode As Integer=ExecuteCommand(cmd1, cmd2, 30000)
    
End Sub

Public Overrides Sub Uninstall(ByVal savedState As System.Collections.IDictionary)
MyBase.Uninstall(savedState)

'Unregister the custom component.
'---------------------------------

'The default location of the ESRIRegAsm utility.
'Note how the whole string is embedded in quotes because of the spaces in the path.
Dim cmd1 As String="""" + Environment.GetFolderPath(Environment.SpecialFolder.CommonProgramFiles) + "\ArcGIS\bin\ESRIRegAsm.exe" + """"

'Obtain the input argument (via the CustomActionData Property) in the setup project.
'An example CustomActionData property that is passed through might be something like:
'/arg1="[ProgramFilesFolder]\[ProductName]\bin\ArcMapClassLibrary_Implements.dll",
'which translates to the following on a default install:
'C:\Program Files\MyGISApp\bin\ArcMapClassLibrary_Implements.dll.
Dim part1 As String=Me.Context.Parameters.Item("arg1")

'Add the appropriate command line switches when invoking the ESRIRegAsm utility.
'In this case: /p:Desktop=means the ArcGIS Desktop product, /u=means unregister the Custom Component, /s=means a silent install.
Dim part2 As String=" /p:Desktop /u /s"

'It is important to embed the part1 in quotes in case there are any spaces in the path.
Dim cmd2 As String="""" + part1 + """" + part2

'Call the routing that will execute the ESRIRegAsm utility.
Dim exitCode As Integer=ExecuteCommand(cmd1, cmd2, 30000)

End Sub

Public Shared Function ExecuteCommand(ByVal Command1 As String, ByVal Command2 As String, ByVal Timeout As Integer) As Integer

'Set up a ProcessStartInfo using your path to the executable (Command1) and the command line arguments (Command2).
Dim ProcessInfo As ProcessStartInfo=New ProcessStartInfo(Command1, Command2)
ProcessInfo.CreateNoWindow=True
ProcessInfo.UseShellExecute=False

'Invoke the process.
Dim Process As Process=Process.Start(ProcessInfo)
Process.WaitForExit(Timeout)

'Finish.
Dim ExitCode As Integer=Process.ExitCode
Process.Close()
Return ExitCode
End Function

End Class

Testing the setup.exe file

1. Copy the setup.exe and setup.msi files from the DevelopmentPC onto the TargetPC.
2. Double-click the setup.exe file and progress through the wizards. See the following screen shot that shows the setup wizard:
   
   
   
3. When the setup is complete, start ArcMap.
4. Click Customize, then Customize Mode. The Customize dialog box appears.
5. Click the Commands tab, scroll down in the Categories section, then select the Developer Samples category. The Developer Samples category has the ArcMap ClassLibrary_Implements command. See the following screen shot that shows the category and command on the Customize dialog box:
   
   

6. Look on your hard drive for the location you specified as part of the setup to see where the .dll file was placed. See the following screen shot that shows this location:
   
   
   

See Also: