Monday, August 25, 2008

Deploying .NET Applications

Though distributing libraries in the form of DLLs was a major step forward, it suffered from the now in-famous DLL hell. COM could avoid this but it had no versioning mechanism. Moreover a COM component had foot-prints at so many places that if one of them got modified/corrupted, the application used to break down. .NET has come up with more sophisticated approaches for deployment and versioning.

Deployment Issues

Deployment is a process by which you distribute a finished application or component to be installed on other computers. In Visual Studio .NET, deployment is based on Microsoft Windows Installer technology. Microsoft Windows Installer is a service shipped with Windows Me, Windows 2000, and Windows XP. It is used for installation and configuration of applications to be installed. Every .NET application is deployed in the form of one or more assemblies. Assemblies may be deployed as regular standalone files (DLL or EXE files), or they may be deployed using CAB, MSI, or MSM files. The simplest way of deploying a private assembly is to use an XCOPY, i.e. copying the assembly in the desired folder. On the other hand we can deploy shared assemblies by installing them in the Global Assembly Cache of the target machine by using the Gacutil.exe.

To help programmers develop setup and deployment solutions, Visual Studio .NET provides several templates and wizards. We can create a setup or deployment project by selecting ‘Setup and Deployment Projects’ in the ‘New Project’ dialog box shown in the following figure.

Let us first discuss the types of projects shown in the dialog box and see the usage of each. Later we have illustrated how to deploy different types of applications using these projects.

Setup Project

A setup project builds a Windows Installer file or an MSI file with the .msi extension. This file is used to install the specified files and resources on the target machine automatically. The .msi file contains the application, any dependent files, information about the application such as registry entries, and instructions for installation. When the .msi file is distributed and run on another computer, you can be assured that everything necessary for installation is included; if for any reason the installation fails (for example, the target computer does not have the required operating system version), the installation will be rolled back and the computer returned to its pre-installation state.

CAB Project

A CAB project creates a cabinet file with the .cab extension. It is much like a Zip file, compressing a number of specified files into an easy to use and easy to deploy package. The resulting cabinet (.cab) file can then be deployed or downloaded. The files present in the .cab file can be extracted by double-clicking the .cab file.

Merge Module Project

A Merge Module project produces a merge module file having a .msm extension. A Merge Module is a single package that contains all files, resources, registry entries, and setup logic necessary to install a component.

Merge Modules are used to install components that are shared by multiple applications. The basic distinction between a Merge Module (.msm) and a Windows Installer (.msi) is based on the user using these components. Whatever we wish to deploy directly to the end user of the application (executable files, documents, HTML pages) should be packaged in a Windows Installer, whereas, whatever we wish to deploy to the developer (DLLs, controls, resources) should be packaged in a Merge Module. The developer can then repack it in a Windows Installer for distribution to the end user. It is possible to put multiple components into a single Merge Module but it's best to create a Merge Module for each component in order to handle versioning problems. Once you have distributed a Merge Module it should never be modified; instead you should create a new Merge Module for each successive version of your component.

Web Setup Project

Web Setup Project helps us to deploy web-based applications. In addition to this any Windows application or its installer can be deployed to a web server so that users can later download and run them from a web site. In order to deploy web-based application we will have to build a Web Setup Project, copy it to the web server and run the installer to install it on the server.

Setup Wizard

The Setup Wizard is used to help us start creating any of the above-discussed projects in a fast and simple manner. We just have to follow some simple steps the wizard leads us through and the wizard does the initial job for us. Next we may extend the project further as per our requirements. Now let us understand the projects discussed above in detail.

Setup Projects

We know that a Setup Project creates an .msi file, which actually installs the application on the target computer. To demonstrate this we plan to deploy a simple Windows application using the Setup Project. Here we have assumed that the Windows application stands created and the .EXE named windowsapp1.exe is ready. To deploy this Windows application we need to select ‘New | Project’ and select ‘Setup and Deployment project’ from the available options. Next we must select ‘Setup Project’ as the project template and specify the name (say winsetup) and the location of the setup project and click OK. Then we are taken to the File System Editor. The File System Editor is shown in the following figure.

The File System Editor has three folders—the Application Folder, the User’s Desktop folder and the User’s Programs Menu folder. These folders actually represent the folders on the target machine. For example, whatever you put in User’s Desktop will be deployed on the desktop of the target machine. From the three folders in the file system editor, files from Application Folder would be deployed in the Program Files folder; typically it is ‘C:\Program Files\Company Name\Application Name’ of the target machine. User’s Desktop folder contains files and folders that would appear on the desktop of the target machine on a per-user basis. Typically the path is ‘C:\Documents and Settings \username\Desktop’. User’s Programs Menu folder contains user’s program groups that would usually get deployed in ‘C:\Documents and Settings \username\Start Menu\Programs’.

Now we need to add the Windows application EXE file into this project. For this we must right click on the Application Folder. A menu is popped. We must select Add | File and on doing so an ‘Add Files’ dialog is popped. Now we need to browse for ‘windowsapp1.exe’ file so that it gets added to the Application Folder. We can add the EXE to User’s Desktop and User’s Programs Menu as well but while doing so we must keep in mind that these two folders are on per-user basis. This means that only the user who installs the application would be able to access the file on his desktop and not the other users.

This completes the basic steps needed to build an installer. We can now build this project and an installer called ‘winsetup.msi’ would get created in the debug folder. Now all we need to do is to distribute this installer and on running the installer on the target machine the application would get installed there.

On running the installer we get a series of screens depicting different stages of installation. Note that if our application needs more files than just the ‘windowsapp1.exe’ then we can copy them to any of the above-mentioned folders.

There is much more to a Setup Project than what we discussed above. We saw the simplest form and there are several more features that we need to explore. All the deployment capabilities discussed below are not mandatory and we can customize our installation process according to the needs of our application.

Adding Shortcuts

We can add shortcuts to our application in any of the 3 folders. For this we need to right click on the application file (‘windowsapp1.exe’) that we added to the project and select ‘Create shortcut to windowsapp1.exe’. On doing so a shortcut for our application would get created. Now we must drag this shortcut in the User’s Desktop Folder. If we wish to add a shortcut in User’s Programs Menu also, we need to create another shortcut in the same manner discussed above and drag it in the folder. On building and installing the application, the shortcuts get added in the specified folders of the target machine.

Adding Registry Entries

We can make a provision that some registry entries would be added for a particular application during installation of the application. We can then access these entries later through our application’s code at run-time. To add the registry entries we must right click on winsetup in the Solution Explorer and select View | Registry. On doing so we will be presented with the Registry Editor shown in the following figure.

Suppose we wish to add a key-value pair to HKEY_CURRENT_USER | Software | [Manufacturer]. For this we must right click on it and select New | Key. We can rename the key as per our wish. To add a value we need to right click on the newly formed key and select the type of value we wish to add, i.e. whether it should be a String value, a DWORD value, a Binary value, etc. We can set it to some value using the Properties Window. Now if we build winsetup and install the application, the entry would be made in the registry. We can verify this by executing the Registry Editor RegEdit through the ‘Start | Run’ dialog box.

Adding Custom Installation Dialog Boxes

Once the MSI file is built and we double click on it, the installation starts. The user is presented with five dialog boxes during installation. These dialog boxes are predefined dialog boxes that get added to our project by default. We can customize these dialogs or new dialog boxes to our project using the User Interface Editor. This editor can be opened by right clicking on the project in Solution Explorer and selecting ‘View | User Interface’.

The User Interface Editor shows a tree control containing two sections—Install and Administrative Install. The Install section contains dialog boxes that will be displayed when any end user runs the installer. Administrative installation is a feature of Microsoft Windows Installer that allows us to install a source image of an application on a network share. Users in a workgroup who have access to the network share can then install the application from the source image. The User Interface Editor allows us to specify a different set of installation dialog boxes that will be displayed when an administrator installs the application to a network share via the command line as shown below:

Msiexec.exe /a Setup1.msi

This will start the installer of our application and dialog boxes specified for the Administrative Install will be displayed.

The default set of predefined dialog boxes is displayed in the User Interface Editor; we can rearrange or delete these if we wish. The default set of dialog boxes varies according to the type of deployment project. Predefined dialog boxes are divided into three categories:

Start Dialog Boxes

Start dialog boxes are displayed before the installation begins. Commonly they are used to gather customer information or to allow the user to change the installation directory.

Progress Dialog Boxes

A progress dialog box is displayed to provide feedback on the progress of an installation.

End Dialog Boxes

End dialog boxes are displayed once the installation has finished successfully. Common uses are notifying the user that the installation is complete or to allow the user to launch the application.

We can remove dialog boxes from the default set as per our wish or reposition them using the right click | Move Up/Move Down options. Note that all combinations are not possible here. For example, we cannot remove the Progress dialog box and place it in the Start dialog boxes category after the Welcome dialog box.

Now in addition to these dialog boxes we can add and configure our own custom dialog boxes that would get displayed during the installation. To do so we need to right click on the desired category and select ‘Add Dialog’. On doing so the Add Dialog Box gets displayed.

Here we are presented with several ready-made dialog boxes that we may want to get displayed during installation. Following table indicates the use of these dialog boxes.

Dialog Box


RadioButtons (2 buttons)

Gives the user a choice between two options through two radio buttons.

RadioButtons (3 buttons)

Gives the user a choice between three options through three radio buttons.

RadioButtons (4 buttons)

Gives the user a choice between four options through four radio buttons.

Checkboxes A, B, or C

Gives the user a choice to add 1, 2, 3 or 4 checkboxes in the same dialog.

Customer Information

Used to retrieve information including name, company, and serial number.

Textboxes A, B, or C

Used to retrieve custom information using 1, 2 or 3 text boxes.

License Agreement

Displays a license agreement for the user to read and acknowledge.

Read Me

Allows the user to view any Read me file in .rtf format.

Register User

Allows the user to submit registration information.


Displays a Splash Screen in .bmp format during installation.

Out of the several dialog boxes listed in this table we would discuss only the ones that are likely to be used more commonly. These include the Checkbox dialog box, Read Me Dialog box and the Splash dialog box.

The Checkbox Dialog Box

Suppose during installation we plan to ask the user whether he wants to add the ‘Disclaimer.txt’ file along with ‘windowsapp1.exe’ or not. To control this we plan to add the Checkbox dialog box. If the user checks the Checkbox, the text file gets installed. To add this custom dialog box we have followed the same steps discussed above and added the Checkboxes (A) Dialog. This dialog box would get added as the last dialog box of the Start dialog boxes category. So we can move it up by two positions. Next we have changed some properties of the Checkboxes (A) dialog box. These are shown in the following table.


Changed to...




Do you want to install the Disclaimer text file?


Install Disclaimer











Note that we have changed the visible property of the remaining checkboxes to false because we need just one checkbox. Now we need to add a folder in the Application Folder named Disclaimer. For this we must right click on the Application Folder and select ‘Add | Folder’. This would add a new folder we have renamed it to Disclaimer. Next we added a text file called ‘Disclaimer.txt’ to this folder. Hence the Application Folder would contain the ‘windowsapp1.exe’ along with the Disclaimer folder holding the ‘Disclaimer.txt’ file. Then comes the most important step of setting the Condition property of the ‘Disclaimer.txt’ file so that it would only get installed when the checkbox is checked. To do this we need to open the Properties Window of the ‘Disclaimer.txt’ and set its Condition property to CHECKBOXA1=1. On building the winsetup.msi project, and double clicking it we are presented with this dialog box in the second step of the installation process. The Disclaimer dialog box is shown in the following figure.

The Read Me Dialog box

This dialog box displays the Read Me file during installation procedure and installs it along with the application. To demonstrate this we must add the Read Me dialog box in the Start dialog boxes category. Next we need to associate a Rich Text File (rtf) with this dialog box. For this we have to create a ‘ReadMe.rtf’ file and add it to the Applications Folder. Next we have to set the ReadmeFile attribute of the Read Me Dialog box to this file. We can browse for this file and since we had added it to the Applications Folder we will find it there. Note that we cannot browse beyond the three folders (Application Folder, User’s Program and User’s Programs Menu), hence if we wish to make any file available in the project we have to first get it copied in one of these. Now after re-building the project and installing it we are presented with this Read Me dialog box as the 5th step of installation and this file gets copied along with the folder.

The Splash Dialog Box

We added the Splash dialog box just after the Welcome dialog box. The User Interface Editor after addition of all the dialog boxes is shown in the following figure.

To display a splash screen in the Splash dialog box, all we need to do is to set the SplashBitmap property of the dialog to a ‘.bmp’ file. To make the file available we must first add it to the Application Folder. On re-building this project and running the installer we are presented with the Splash dialog box.

In the next part we would see how to add launch conditions to the setup project.

No comments:

Your Title