Creating Installation Components

When you deploy an application, you might want to perform certain customized actions during the installation process. Some examples of customized actions include registering a Windows service with the service control manager, registering a serviced component with COM+ explorer, creating a database, installing event logs, and installing performance counters.

The .NET Framework provides you with an Installer class to help you perform customized installation actions like those mentioned previously. The Installer class is defined in the System.Configuration.Install namespace.

Understanding the Installer Class

The System.Configuration.Install.Installer class works as a base class for all the custom installers in the .NET Framework. Some important Installer class members that I will discuss in this chapter are listed in Table 10.3.

Table 10.3. Important Members of the Installer Class

Member Name	Type	Description
`Commit`	Method	The code in the `Commit()` method is executed if the `Install()` method executes successfully.
`Install`	Method	Performs the specified actions during an application's installation.
`Installers`	Property	Collection of Installer objects that are needed for this Installer instance to successfully install a component.
`Rollback`	Method	If the `Install()` method fails for some reason, the code in the `Rollback()` method is called to undo any custom actions performed during the Install method.
`Uninstall`	Method	Performs the specified actions when a previously installed application is uninstalled .

You can derive a class from the Installer class and override the methods given in Table 10.3 to perform any custom actions you like.

If you want the derived Installer class to execute when an assembly is installed using a Web Setup project or by using the Installer Tool (InstallUtil.exe), you need to decorate the class with the RunInstaller attribute set to true :

 <RunInstaller(True)>

Installer classes provide the infrastructure for making installation a transactional process. If an error is encountered during the Install() method, the Rollback() method will track down all the changes and undo them to leave the machine in the clean state it was in before the installation process started. The Rollback() method must know the order in which the installation steps were performed and exactly what changes were made so that it can undo those changes in the right order.

Similarly, when an application is uninstalled, the Uninstall() method of the Installer class is called. The responsibility of the Uninstall() method is again to undo the changes done by the installation process so that the machine is left clean, as if the program was never installed on it.

How does the Install() method communicate its installation information with the Rollback() and Uninstall() methods? This question becomes even more interesting when you see that the Install() and Uninstall() methods are not called in the same process. Install() is called when the application is installed, whereas Uninstall() is called when the application is uninstalled. These two events might occur separated by several days and computer restarts.

The Install() method communicates the installation state by persisting it in a file with the extension .InstallState . This file is placed in the installation directory of the application. The Installer class makes this file available to each of the Install() , Commit() , Rollback() , and Uninstall() methods by passing an IDictionary object to the contents of this file. Content in the .InstallState file is used by the Rollback() and Uninstall() methods to perform the required cleanup operation.

Predefined Installation Components

The .NET Framework provides five predefined installation components. Each of these installation components, as listed in Table 10.4, is associated with a specific server component.

Table 10.4. Predefined Installation Components

Installer Name	Description
`EventLogInstaller`	Allows you to install and configure a custom event log. This class belongs to the `System.Diagnostics` namespace.
`MessageQueueInstaller`	Allows you to install and configure a message queue. This class belongs to the `System.Messaging` namespace.
`PerformanceCounterInstaller`	Allows you to install and configure a custom performance counter. This class belongs to the `System.Diagnostics` namespace.
`ServiceInstaller`	Allows you to install a Windows service contained in a Windows service application. This class does work specific to a Windows service with which it is associated. The `ServiceInstaller` class belongs to the `System.ServiceProcess` namespace.
`ServiceProcessInstaller`	Allows you to install a Windows service application. This class does work common to all Windows services in an executable. The `ServiceProcessInstaller` class belongs to the `System.ServiceProcess` namespace.

Visual Studio .NET does not automatically add an installer for a server component, but it's easy to add one. For example, if you create a new Windows service project and access the Properties window for the project, you see a link, as shown in Figure 10.28, to add predefined installer classes for the Windows service in the project.

Figure 10.28. You can add a predefined installer for a server component by clicking on the Add Installer hyperlink in the Properties window.

Clicking on the Add Installer link adds an instance of the predefined installation component to a class named ProjectInstaller in your project. You can add as many instances of the installation components to the ProjectInstaller class as you need. Each instance of a predefined installation component is set with properties that help re-create that object on the production machine. All the installation components are added to the Installers collection of the ProjectInstaller class. When you compile the project to build an EXE or a DLL file, the ProjectInstaller class becomes part of the output assembly. The ProjectInstaller class has the RunInstaller attribute set to true so that at the time of installation, the ProjectInstaller class takes the responsibility of installing all the predefined installation components in an assembly.

You'll learn how to use predefined installation components to install a Windows service later in the chapter, in the section "Deploying Windows Services."

Custom Installation Components

You can also add custom Installer classes to a project to perform custom actions during installation, such as compiling the code to native image or creating a database on a target computer. These Installer classes are compiled with your project and are then added to the deployment project as custom actions that are run at the end of the installation. You need to do the following to create a custom Installer class:

Inherit a class from the Installer class.
Make sure that the RunInstaller attribute is set to True in the derived class.
Override the Install() , Commit() , Rollback() , and Uninstall() methods to perform any custom actions.
In the setup project, use the custom action editor to invoke this derived class to do the required processing.
If needed, pass arguments from the Custom Actions Editors to the custom Installer class using the CustomActionData property.

You'll learn how to use the preceding steps to create a custom installer class in the section "Deploying a Serviced Component."

Deploying an Assembly Containing the Installation Components

An assembly containing installation components can be deployed in one of the following two ways:

Using a Setup and Deployment Project To deploy an application that consists of installation components, you can create a Setup project or a Web setup project as you would normally. But this time, you will use the Custom Actions Editor to deploy the resources specified by the Installer class. At the time of deployment, the setup program will execute the ProjectInstaller class as a part of its custom installation action to create component resources. Step By Step 10.17 shows you how.
Using the Installer Tool ( InstallUtil.exe ) You can also use the command-line Installer Tool ( installutil.exe ) to install the assemblies that contain additional component resources. To install the resources contained in an assembly named Assembly1.dll , you can use the following form of the InstallUtil.exe command:
```
 InstallUtil.exe Assembly1.dll 
```
You can also install resources contained in multiple assemblies together, such as
```
 InstallUtil.exe Assembly1.dll Assembly2.dll Assembly3.dll 
```
If you instead want to launch the uninstaller for installation classes stored in an assembly, you will use the /u or /uninstall option with the command, such as
```
 InstallUtil.exe /u Assembly1.dll 
```

I already discussed using the Installer tool ( installUtil.exe ) in Chapter 6, "Windows Services." In the following section, I'll use the Visual Studio .NET Setup and Deployment projects to install the installation components.

EXAM TIP

InstallUtil.exe Performs Installation in a Transactional Manner If you are installing components from multiple assemblies using the InstallUtil.exe command and any one of the assemblies fails to install, InstallUtil.exe will roll back the installations of all other assemblies.

Top