Installer Projects

Xcopy deployment can be easy to use, but there are times when the lack of functionality becomes an issue. To overcome this shortcoming, Visual Studio 2005 has six installer project types. Four of these options are based on the Windows Installer technology. The following table lists the project types.

Project Type	Description
Setup Project	Used for the installation of client applications, middle-tier applications, and applications that run as Windows Service.
Web Setup Project	Used for the installation of Web-based applications.
Merge Module Project	Creates merge modules that can be used with other Windows Installer–based setup applications.
Cab Project	Creates cab files for distribution through older deployment technologies.
Setup Wizard	Aids in the creation of a deployment project.
Smart Device CAB Project	CAB project for Pocket PC, Smartphone, and other CE-based applications.

Setup and Web Setup Projects are very similar. The key difference is that with Web Setup the project is deployed to a virtual directory on a Web server, whereas with Setup Project it is deployed to a folder structure. Both project types are based on Windows Installer and have all of the features of a Windows Installer–based setup program. Merge Module Project is generally used when you have created a component or library of functionality that is included in a number of deployment projects. By creating a merge module you can set any configuration items specific to the component and without having to worry about them in the creation of the main deployment project. The Cab Project type simply creates cab files for the application. Cab files are used by older installation technologies as well as some Web-based installation processes. The Setup Wizard project type steps through the process of creating a deployment project, asking specific questions along the way. The following sections discuss how to create each of these deployment projects, what settings and properties can be changed, and what customization you can add.

What Is Windows Installer?

Windows Installer is a service that manages the installation, update, repair, and removal of applications on most Windows operating systems. It is part of Windows ME, Windows 2000, and Windows XP and is available for Windows 95, Windows 98, and Windows NT 4.0. The current version of Windows Installer is 2.0.

Windows Installer tracks the installation of applications in a database. When an application has to be uninstalled, you can easily track and remove the registry settings that were added, the files that were copied to the hard drive, and the desktop and Start Menu icons that were added. If a particular file is still referenced by another application, the installer will leave it on the hard drive so that the other application doesn't break. The database also makes it possible to perform repairs. If a registry setting or a dll associated with an application becomes corrupt or is accidentally deleted, you can repair the installation. During a repair, the installer reads the database from the last install and replicates that installation.

The deployment projects in Visual Studio 2005 give you the ability to create a Windows Installation package. The deployment projects give you access to most of what you will need to do in order to install a given application. However, if you need even more control, check out the Windows Installer SDK, which is part of the Platform SDK — it contains documentation on creating custom installation packages for your application. The following sections deal with creating these installation packages using the Visual Studio 2005 deployment projects.

Creating Installers

Creating installation packages for client applications or for Web applications is not that difficult. One of the first tasks is to identify all of the external resources your application requires, including configuration files, COM components, third-party libraries, and controls and images. Including a list of dependencies in the project documentation was discussed earlier. This is where having that documentation can prove to be very useful. Visual Studio 2005 can do a reasonable job of interrogating an assembly and retrieving the dependencies for it, but you still have to audit the findings to make sure nothing is missing.

Another concern might be when in the overall process is the install package is created. If you have an automated build process set up, you can include the building of the installation package upon a successful build of the project. Automating the process greatly reduces the chance for errors in what can be a time-consuming and complicated process for large projects. What you can do is to include the deployment project with the project solution. The Solution Property Pages dialog box has a setting for Configuration Properties. You can use this setting to select the projects that will be included for your various build configurations. If you select the Build check box under Release builds but not for the Debug builds, the installation package will be created only when you are creating a release build. Thisis the process used in the following examples. Figure 18-1 shows the Solution Property Pages dialog box of the SampleClientApp solution. Notice that the Debug configuration is displayed and that the Build check box is unchecked for the setup project.

Figure 18-1

Simple Client Application

In the following example, you create an installer for the SimpleClientApp solution (which is included in the sample download, together with the completed installer projects).

For the SimpleClientApp you create two deployment projects. One is done as a separate solution, the other is done in the same solution. This enables you to see the pros and cons of choosing either option.

The first example shows you how to create the deployment project in a separate solution. Before you get started on creating the deployment project, make sure that you have a release build of the application that will be deployed. Next, create a new project in Visual Studio 2005. In the New Project dialog box, select Setup and Deployment Projects on the left. On the right select Setup Project and assign it a name of your choice (for example, SampleClientStandaloneSetup). At this point, what you see on your screen resembles Figure 18-2.

Figure 18-2

In the Solution Explorer window, click the project and then the Properties window. You will see a list of properties. These properties will be displayed during the setup of your application. Some of these properties are also displayed in the Add Remove Programs control panel applet. Because most of these properties are visible to the user during the installation process (or when they are looking at your installation in Add

Remove Programs), setting them correctly will add a professional touch to your application. The list of properties is important, especially if your application will be deployed commercially. The following table describes the properties and the values that you should enter.

Project Property	Description
AddRemove ProgramsIcon	The icon that appears in the Add/Remove dialog box.
Author	The author of the application. Generally this property setting is the same as the manufacturer. It is displayed on the Summary page of the Properties dia- log of the msi package, as well as the Contact field of the SupportInfo page on the Add/Remove dialog box.
Description	A freeform text field that describes the application or component that is being installed. This information is displayed on the Summary page of the Properties dialog of the msi package, as well as the Contact field of the SupportInfo page on the Add/Remove dialog box.
DetectNewer InstalledVersion	A Boolean value that, when set to true, will check to see if a newer version of the application is already installed. If so, the installation process will stop.
InstallAllUsers	Boolean value that, when set to true, will install that application for all users of the computer. If set to false, only the current user will have access.
Keywords	Keywords that can be used to search for the msi file on the target computer. This information is displayed on the Summary page of the Properties dialog of the msi package.
Localization	The locale used for string resources and registry settings. This affects the user interface of the installer.
Manufacturer	Name of the company that manufactured the application of component. Typ- ically this is the same information as specified in the Author property. This information is displayed on the Summary page of the Properties dialog box of the msi package as well as the Publisher field of the SupportInfo page in the Add/Remove dialog box. It is used as part of the default installation path of the application.
ManufacturerURL	The URL for a Web site that relates to the application or component being installed.
PostBuildEvent	A command that is executed after the build ends.
PreBuildEvent	A command that is executed before the build begins.
ProductCode	A string GUID that is unique to this application or component. Windows Installer uses this property to identify the application for subsequent upgrades or installs.
ProductName	A name that describes the application. Used as the description of an applica- tion in the Add/Remove dialog box as well as part of the default install path: C:\Program Files\Manufacturer\ProductName.
RemovePrevious	Boolean value that, if set to true, will check for a previous version of the
Versions	application. If yes, the uninstall function of the previous version is called before installation continues. This property uses ProductCode and Upgrade- Code to determine if uninstall should occur. UpgradeCode should be the same; ProductCode should be different.
RunPostBuildEvent	When the PostBuildEvent should be run. Options are On successful build or Always.
SearchPath	A string that represents the search path for dependent assemblies, files, or merge modules. Used when the installer package is built on the develop- ment machine.
Subject	Additional information regarding the application. This information is dis- played on the Summary page of the Properties dialog box of the msi package.
SupportPhone	A phone number for support of the application or component. This informa- tion is displayed in the Support Information field of the SupportInfo page on the Add/Remove dialog box.
SupportURL	A URL for support of the application or component. This information is displayed in the Support Information field of the SupportInfo page in the Add/Remove dialog box.
TargetPlatform	Supports the 32-or 64-bit versions of Windows.
Title	The title of the installer. This is displayed on the Summary page of the Prop- erties dialog box of the msi package.
UpgradeCode	A string GUID that represents a shared identifier of different versions of the same application. The UpgradeCode should not change for different ver- sions or different language version of the application. Used by the Detect- NewerInstalledVersion and RemovePreviousVersion.
Version	The version number of the installer, cab file, or merge module. Note that this is not the version of the application being installed.

After you have set the properties, you can start to add assemblies. In this example, the only assembly you have to add is the main executable (SampleClientApp.exe). To do this you can either right-click the project in the Solution Explorer or select Add from the Project menu. You have four options:

• Project Output. You explore this option in the next example.

• File. This is used for adding a readme text file or any other file that is not part of the build process.

• Merge Module. A merge module that was created separately.

• Assembly. Use this option to select an assembly that is part of the installation.

Choose Assembly for this example. You will be presented with the Component Selector dialog box, which resembles the dialog box you use for adding references to a project. Browse to the \bin\release folder of your application. Select SampleClientApp.exe and then click OK in the Component Selector dialog box. You can now see SampleClientApp.exe listed in the Solution Explorer of the deployment project. In the Detected Dependancies section, you can see that Visual Studio interrogated Sample ClientApp.exe to find the assemblies on which it depends; in this case AppSupport.dll is included automatically. You would continue this process until all of the assemblies in your application are accounted for in the Solution Explorer of the deployment project.

Next, you have to determine where the assemblies will be deployed. By default the File System editor is displayed in Visual Studio 2005. The File System editor is split into two panes: The left pane shows the hierarchical structure of the file system on the target machine; the right pane provides a detail view of the selected folder. The folder names might not be what you expect to see, but keep in mind that these are for the target machine; for example, the folder labeled User's Programs Menu maps to theC:\Documents and Settings\User Name\Start Menu\Programs folder on the target client.

You can add other folders at this point, either special folders or a custom folder. To add a special folder make sure that File System on Target Machine is highlighted in the left pane, and select Action menu on the main menu. The Add Special Folder menu choice provides a list of folders that can be added. For example, if you want to add a folder under the Application folder, you can select the Application Folder folder in the left pane of the editor and then select the Action menu. This time there will be an Add menu that enables you to create the new folder. Rename the new folder and it will be created for youon the target machine.

One of the special folders that you might want to add is a folder for the GAC. AppSupport.dll can be installed to the GAC if it is used by several different applications. In order to add an assembly to the GAC it does have to have a strong name. The process for adding the assembly to the GAC is to add the GAC from the Special Folder menu as described previously and then drag the assembly that you want in the GAC from the current folder to the Global Assembly Cache Folder. If you try and do this with an assembly that is not strongly named, the deployment project will not compile.

If you select Application Folder, you will see on the right pane that the assemblies that you added are automatically added to the Application folder. You can move the assemblies to other folders, but keep in mind that the assemblies have to be able to find each other. (For more details on probing, see Chapter 15, "Assemblies.")

If you want to add a shortcut to the application on the user's desktop or to the Start Menu, drag the items to the appropriate folders. To create a desktop shortcut, go to the Application folder. On the right side of the editor select the application. Go to the Action menu and select the Create Shortcut item to create a shortcut to the application. After the shortcut is created, drag it to the User's Desktop folder. Now when the application is installed, the shortcut will appear on the desktop. Typically, it is up to the user to decide if he or she wants a desktop shortcut to your application. The process of asking the user for input and taking conditional steps is explored later in this chapter. The same process can be followed to create an item in the Start Menu. Also, if you look at the properties for the shortcut that you just created, you will see that you can configure the basic shortcut properties such as Arguments and what icon to use. The application icon is the default icon.

Before you build the deployment project you might have to check some project properties. If you select Project menu then SampleClientStandaloneSetup Properties you will see the project Property Pages dialog box. These are properties that are specific to a current configuration. After selecting the configuration in the Configuration drop-down, you can change the properties listed in the following table.

Property	Description
Output file name	The name of the msi or msm file that is generated when the project is compiled.
Package files	This property enables you to specify how the files are packaged. Your options are: As loose uncompressed files. All of the deployment files are stored in the same directory as the .msi file. In setup file. Files are packaged in the .msi file (default setting). In cabinet file(s). Files are in one or more cab files in the same directory. When this is selected the CAB file size option becomes available.
Prerequisites URL	Allows you to specify where prerequisites such as the .NET Framework or Windows Installer 2.0 can be found. Clicking the Settings button will display a dialog that has the following technologies available to include in the setup: Windows Installer 2.0 .NET Framework Microsoft Visual J# .NET Redistributable Package 2.0 SQL Server 2005 Express Edition Microsoft Data Access Components 2.8 There is also an option to have the prerequisites downloaded from a prede- fined URL or to have them loaded from the same location as the setup.
Compression	This specifies the compression style for the files included. Your options are: Optimized for speed. Larger files but faster installation time (default setting). Optimized for size. Smaller files but slower installation time. None. No compression applied.
CAB size	This is enabled when the Package file setting is set to In cabinet files. Unlim- ited creates one single cabinet file; custom allows you to set the maximum size for each cab file.
Authenticode signature	When this is checked the deployment project output is signed using Authenticode; the default setting is unchecked.
Certificate file	The certificate used for signing.
Private key file	The private key that contains the digital encryption key for the signed files.
Timestamp server URL	URL for timestamp server. This is also used for Authenticode signing.

After you have set the project properties, you should be able to build the deployment project and create the setup for the SampleClientApp application. After you build the project you can test the installation by right-clicking the project name in the Solution Explorer. This enables you to access an Install and

Uninstall choice in the context menu. If you have done everything correctly, you should be able to install and uninstall SampleClientApp successfully.

Same solution project

The previous example works well for creating a deployment package but it does have a couple of downsides. For example, what happens when a new assembly is added to the original application? The deployment project will not automatically recognize any changes; you will have to add the new assemblies and verify that any new dependencies are covered. In smaller applications (like the example) this isn't that big of a deal. However, when you're dealing with an application that contains dozens or maybe hundreds of assemblies, this can become quite tedious to maintain. Visual Studio 2005 has a simple way of resolving this potential headache. Include the deployment project in your applications solution. You can then capture the output of the main project as your deployment assemblies. You can look at the SimpleClientApp as an example.

Open the SimpleClientApp solution in Visual Studio 2005. Add a new project using Solution Explorer. Select Deployment and Setup Projects and then select Setup Project, following the steps outlined in the previous section. You can name this project SimpleAppSolutionSetup. In the previous example, you added the assemblies by selecting Add Assemblies from the Project menu. This time, select Add Project Output from Project menu. This opens the Add Project Output Group dialog box (see Figure 18-3).

Figure 18-3

The top part of the dialog box has a drop-down list box that shows all projects in the current solution. Select the main startup project. Then select the items you want to include in your project from the list below. Your options are Documentation, Primary Output, Localized Resources, Debug Symbols, Content Files, and Source Files. First select Primary Output. This includes the output and all dependencies when the application is built. Another drop-down list box lists the valid configurations: Debug and Release plus any custom configurations you might have added. This also determines what outputs are picked up. For deployment you will most likely want to use the Release configuration.

After you make these selections, a new item is added to your deployment project in Solution Explorer. The name of the item is Primary output form SampleClientApp (Release .NET). You will also see the file AppSupport.dll listed under the dependencies. As before, no need to search for the dependant assemblies.

At this point all of the various project properties discussed in the previous section still apply. You can change the Name, Manufacturer, cab file size, and other properties. After setting the properties, do a Release build of the solution and test the installation. Everything should work as expected.

To see the advantage of adding the deployment package to the applications solution, add a new project to the solution. In the example it is called AppSupportII. In it is a simple test method that returns the string Hello World. Set a reference in SampleTestApp to the newly added project, and do another Release build of the solution. You should see that the deployment project picked up the new assembly without you having to do anything. If you go back and open up the standalone deployment project from the previous example, unless you specifically add the assembly it will not be picked up.

Simple Web application

Creating an installation package for a Web application is not that different than creating a client install package. The download examples include a SimpleWebApp that also utilizes the AppSupport.dll assembly. You can create the deployment project the same way that the client deployment projects are created, either standalone or in the same solution. In this example, the deployment project is built in the same solution.

Start the SimpleWebApp solution and add a new Deployment and Setup Project. This time be sure to choose Web Setup Project in the Templates window. If you look at the properties view for the project you will see that all of the same properties exist for Web applications as did for client applications. The only addition is RestartWWWService. This is a Boolean value that will restart IIS during the install. If you're using ASP.NET components and not replacing any ATL or ISAPI dlls you shouldn't have to do this.

If you look at the File System editor, you will notice that there is only one folder. The Web Application folder is what will be your virtual directory. By default the name of the directory is the name of the deployment project, and it is located below the Web root directory. The following table explains the properties that can be set from the installer. The properties discussed in the previous section are not included.

Property	Description
AllowDirectoryBrowsing	Boolean value that, if true, allows an HTML listing of the files and subfolders of the virtual directory. Maps to the Directory browsing property of IIS.
AllowReadAccess	Boolean value that, if true, allows users to read or download files. Maps to the Read property of IIS.
AllowScriptSourceAccess	Boolean value that, if true, allows users to access source code, including scripts. Maps to Script source access in IIS.
AllowWriteAccess	Boolean value that, if true, allows users to change content in write- enabled files. Maps to Write property of IIS.
ApplicationProtection	Determines the protection level of applications that are run on the server. The valid values are:
	Low. Applications run in the same process as Web Services.
	Medium. Applications run in same process but not the same as Web services.
	High. Application runs in its own process.
	Maps to the Application Protection property in IIS. Has no effect if the IsApplication property is false.
AppMappings	A list of application names and document or data files that are asso- ciated with the applications. Maps to the Application Mappings property of IIS.
Condition	A Windows Installer condition that must be met in order for the item to be installed.
DefaultDocument	The default or startup document when the user first browses to the site.
ExecutePermissions	The level of permissions that a user has to execute applications. The valid values are:
	None. Only static content can be accessed.
	ScriptsOnly. Only scripts can be accessed. Includes ASP.
	ScriptsAndExecutables. Any files can be accessed.
	Maps to Execute Permissions in IIS.
Index	Boolean value that, if true, would allow indexing of the content for Microsoft Indexing Service. Maps to the Index this resource property of IIS.
IsApplication	Boolean value that, if true, instructs IIS to create the application root for the folder.
LogVisits	Boolean value that, if true, logs visits to the Web site in a log file. Maps to the Log visits property of IIS.
Property	The named property that can be accessed at installation time.
VirtualDirectory	The virtual directory for the application. This is relative to the Web server.

You might notice that most of these properties are properties of IIS and can be set in the IIS administrator tool. So the logical assumption is that in order to set these properties in the installer, the installer will need to run with administrator privileges. The settings made here can compromise security, so the changes should be well documented.

Other than these properties, the process of creating the deployment package is very similar to the previous client example. The main difference between the two projects is the ability to modify IIS from the installation process. As you can see, you have a great deal of control over the IIS environment.

Client from Web server

Another installation scenario is either running the install program from a Web site or actually running the application from a Web site. Both of these are attractive options if you must deploy an application to a large number of users. By deploying from a Web site you eliminate the need for a distribution medium such as CD-ROM, DVD, or even floppy disks. By running the application from a Web site or even a network share, you eliminate the need to distribute a setup program at all.

Running an installer from a Web site is fairly simple. You use the Web Bootstrapper project compile option discussed earlier in this chapter. You will be asked to provide the URL of the setup folder. This is the folder in which the setup program is going to look for the msi and other files necessary for the setup to work. After you set this option and compile the deployment package you can copy it to the Web site that you specify in the Setup folder URL property. At this point when the user navigates to the folder, she will be able to either run the setup or download it and then run it. In both instances, the user must be able to connect to the same site to finish the installation.

No Touch Deployment

You can also run the application from a Web site or network share. This process becomes a little more involved and is a prime reason that you should design the application with deployment in mind. This is sometimes referred to as No Touch Deployment (NTD).

To make this process work, the application code must be written in a way to support it. A couple of ways exist to architect the application to take advantage of NTD. One way is to write the majority of the application code into dll assemblies. The dlls will live on a Web server or file share on the network. Then you create a smaller application exe that will be deployed to the client pcs. This stub program will start the application by calling into one of the dll assemblies using the LoadFrom method. The only thing thatthe stub program will see is the main entry point in the dll. Once the dll assembly has been loaded, the application will continue loading other assemblies from the same URL or network share. Remember that an assembly first looks for dependant assemblies in the application directory (that is, the URL that was used to start the application). Here is the code used in the stub application on the user's client. This example calls the AppSupportII dll assembly and puts the output of the TestMethod call in label1:

 Assembly testAssembly =  Assembly.LoadFrom("http://localhost/AppSupport/AppSupportII.dll"); Type type = testAssembly.GetType("AppSupportII.TestClass"); object testObject = Activator.CreateInstance(type); label1.Text = (string)type.GetMethod("TestMethod").Invoke(testObject,null); 

This process uses Reflection to first load the assembly from the Web server. In this example the Web site is a folder on the local machine (localhost). Next, the type of the class is retrieved (here: TestClass). Now that you have type information the object can be created using the Activator.CreateInstance method. The last step is to get a MethodInfo object (the output of GetMethod) and call the Invoke method. In a more complex application this is the main entry point of the application. From this point on, the stub is not needed anymore.

Alternatively, you can also deploy the entire application to a Web site. For this method, create a simple Web page that contains a link to the application's setup executable or perhaps a shortcut on the user's desktop that has the Web site link. When the link is clicked, the application will be downloaded to the user's assembly download cache, which is located in the Global Assembly Cache. The application will run from the download cache. Each time a new assembly is requested, it will go to the download cache first to see if it exists; if not, it will go to the URL that the main application came from.

The advantage to deploying the application in this way is that when an update is made available for the application, it has to be deployed in only one place. You place the new assemblies in the Web folder and when the user starts the application, the runtime will actually look at the assemblies in the URL and the assemblies in the download cache to compare versions. If a new version is found at the URL, it is then downloaded to replace the current one in the download cache. This way, the user always has access to the most current version of the application.

For more control over the update process and over security, ClickOnce is probably a better choice.