Visual Studio Deployment Projects

Visual Studio 2005 provides a set of project templates that can be used to help package your application and deploy it. Most of these templates use Windows Installer technology.

Project Templates

Before looking at the project templates, you should understand the difference between setup and deployment. Setup is the process that you use to package your application. Deployment is the process of installing an application on another machine, usually through a setup application/process.

The five project templates available within Visual Studio 2005 can be created by the same means as any other project type, by using the New Project dialog box, as shown in Figure 22-1.

Figure 22-1

As shown in Figure 22-1, you need to select the Other Project Types node and then the Setup and Deployment Projects node from the tree view of project types on the left side of the dialog box. Of the six available project templates, there are five actual project templates:

• CAB Project

• Merge Module Project

• Setup Project

• Web Setup Project

• Smart Device CAB Project

Also included is a wizard (called the Setup Wizard) that can be used to help create any of the project templates listed (except the Smart Device CAB Project).

The CAB Project Template

The CAB Project template is used to create a cabinet file. A cabinet file (.cab) can contain any number of files. It is often used to package a set of related components in an application.

Controls hosted within Internet Explorer are often packaged into a cabinet file, and a reference is added to the file in the Web page that uses the control. When Internet Explorer encounters this reference, it confirms that the control isn’t already installed on the user’s computer, at which point it downloads the cabinet file, extracts the control, and installs it to a protected part of the user’s computer. You can compress cabinet files to reduce their size, thereby reducing the time it takes to download them.

The Merge Module Project Template

The Merge Module Project template is used to create a merge module, which is similar to a cabinet file in that it can be used to package a group of files. The difference is that a merge module file (.msm) cannot be used by itself to install the files that it contains. The merge module file created by this project template can only be used within another setup project.

Merge modules were introduced as part of the Microsoft Windows Installer technology to enable a set of files to be packaged into an easy to use file that could be reused and shared between Windows Installer−based setup programs. The idea is to package all the files and any other resources (for example, registry entries, bitmaps, and so on) that are dependent on each other into the merge module.

This type of project can be very useful for packaging a component and all its dependencies. The resulting merge file can then be used in the setup program of each application that uses the component. This allows applications such as Crystal Reports to have a prepackaged deployment set that can be integrated into the deployment of other applications.

The Setup Project Template

The Setup Project template is used to create a standard Windows Installer setup for an application, which is normally installed in the Program Files directory of a user’s computer.

The Web Setup Project Template

The Web Setup Project template is used to create a Windows Installer setup program that can be used to install a project into a virtual directory of a Web server. It is intended to be used to create a setup program for a Web application, which may contain ASP.NET Web Forms or Web Services.

The Smart Device CAB Project Template

The Smart Device CAB Project template is used to create a CAB file for an application that runs on a device containing the .NET Compact Framework, such as a PocketPC device. Such applications are often referred to as mobile applications, and they have many capabilities and limitations that do not apply to other .NET-based applications. This book does not discuss mobile applications, so this template type is not discussed here.

The Setup Wizard

You can use the Setup Wizard to help guide you through the creation of any of the previous setup and deployment project templates except the Smart Device CAB template.

Creating a Deployment Project

A deployment project can be created in exactly the same way as any other project in Visual Studio 2005. The deployment project can be standalone or part of a solution that contains other projects.

To illustrate a typical deployment project, this section presents a simple walk-through of one of the most commonly used templates for a deployment project - the Setup Project, which is used to deploy a Windows application.

Walk-through

You first need to create an application that will serve as the desktop application you want to deploy. Create a new project, and choose Windows Application from the list of available Visual Basic project templates. Name the project “SampleForDeployment,” and don’t add any code to it.

Next, add a new project to the solution and choose Setup Project from the list of available Setup and Deployment Project templates. You will now have a Visual Studio solution containing two projects.

When created, the deployment project does not contain any files. It has a folder called Detected Dependencies, which is discussed later. You need to add the executable file from your Windows application SampleForDeployment to the deployment project.

You add files to a setup deployment project using the Add function, which is available in two places. You can select the deployment project in Solution Explorer and use the Add option from the Project menu, or you can right-click the setup project file in Solution Explorer and choose Add from the pop-up menu. Both these methods enable you to choose from one of four options:

• If you select File from the submenu, you are presented with a dialog box from which you can browse for and select a particular file to add to the setup project. Use this method when a file needed by the application is not the output from another project within the solution.

• The Merge Module option enables you to include a merge module in the deployment project. Third-party vendors can supply merge modules or you can create your own with Visual Studio.

• The Assembly option can be used to select a .NET component (assembly) to be included in the deployment project.

• If the deployment project is part of a solution (as in this walk-through), you can select Project Add Project Output. This enables you to add the output from any of the projects in the solution to the setup project.

You want to add the output of the Windows application project to the setup project. Select the Project Output menu item to bring up the dialog box shown in Figure 22-2.

Figure 22-2

The Add Project Output Group dialog box is split into several parts:

• The combo box at the top contains a list of the names of all the nondeployment projects in the current solution. In your case, there is only one project - SampleForDeployment.

• Below the combo box is a list box containing all the possible outputs from the selected project. You are interested in the Primary output, so make sure that this is selected. The different types of output are summarized in the following table.

• Below the list of possible outputs is a combo box that enables you to select the configuration to use for the selected project. Select the (Active) option, because this uses whatever configuration is in effect when the project is built.

Click OK to return to the solution.

Open table as spreadsheet

Project Output	Description
Primary output	The primary output of a project is the resulting DLL or EXE that is produced by building the particular project.
Localized resources	The localized resource of a project is a DLL that contains only resources. The resources within the DLL are specific to a culture or locale. This is often called a satellite DLL.
Debug Symbols	When the particular project in question is compiled, a special file is created that contains special debugging information about the project. These are called debug symbols. The debug symbols for a project have the same name as the primary output but with an extension of .pdb. The debug symbols provide information to a debugger when an application is being run through it.
Content Files	ASP.NET Web applications have content files that are part of the website, such as HTML files, images files, and so forth. This option allows inclusion of such content as part of a deployment.
Source Files	This includes all the source files for the selected project, including the project file. The solution file is not included.
Documentation Files	Source code for a project may contain comments that are formatted so that documentation in an XML format can automatically be produced. This option accesses those XML documentation files.
XML Serialization Assemblies	A project may contain XML schemas. If so, assemblies can be generated that contain classes based on those schemas. This option includes those assemblies.

Now, not only has the output from the Windows application been added to the setup project, but the DetectedDependencies folder also contains an entry.

Whenever you add a .NET component to this deployment project, its dependencies are added to this folder. The dependencies of the dependencies are also added and so on until all the required files have been added. The files listed in the DetectedDependencies folder are included in the resulting setup and, by default, are installed into the application’s directory as application-private assemblies. This default behavior helps reduce the possible effects of DLL hell by making the application use its own copies of dependent files.

If you do not want a particular dependency file to be included in the resulting setup, you can exclude it by right-clicking the particular entry under DetectedDependencies and selecting Exclude from the pop-up menu. For example, you may decide that you want to exclude a detected dependency from the setup of an application because you know that the dependency is already installed on the target computer. The dependency will then have the familiar, small “circle and slash” icon before its name to indicate that it has been excluded.

Tip 

Dependencies can also be excluded by selecting the particular dependency and using the Properties window to set the Exclude property to True. The listed dependencies are refreshed whenever a .NET file is added to or removed from the setup project, taking into account any files that have already been excluded.

You can select an item in the setup project in Solution Explorer and that particular item’s properties will be displayed in the Properties window. There are too many properties to discuss them all. Instead, we will take a look at the properties from the root setup node and each of the two different project items. Before we start the discussion, make sure that the root setup node is selected, and take some time to browse the list of available properties.

The root setup node represents the output from this deployment project type: a Windows Installer package (.msi). Therefore, the Properties window contains properties that affect the resulting .msi that is produced.

Important Properties of the Root Setup Node

The ProductName property is used to set the text name of the product that this Windows Installer package is installing. By default, it is set to the name of the setup project (in this case, Setup1). The value of this property is used throughout the steps of the resulting setup. For instance, it is used for the text of the title bar when the resulting .msi file is run. The property is used along with the Manufacturer property to construct the default installation directory:

 C:\ProgramFiles\<Manufacturer>\<ProductName>

The ProductName property is also used by the Add/Remove Programs control panel applet (see Figure 22-3) to show that the application is installed.

Figure 22-3

As shown in Figure 22-3, you can click a link to get support information about the selected application. That link yields a dialog similar to the one shown in Figure 22-4.

Figure 22-4

The information in this dialog is derived from several properties of the setup project:

Open table as spreadsheet

Support Information	Related Properties	Description
Publisher	Manufacturer	The Manufacturer property is used to help create the default installation directory for the project and display of the manufacturer of the application within the Windows Installer package.
Version	ManufacturerUrl	This property is used in conjunction with the Manufacturer property to make a hyperlink for the Publisher part of the support information. If a value is entered, the name of the publisher will be underlined, providing a clickable link to visit the publisher’s website.
	Version	This is the version number of the Windows Installer package. It can be changed to match the version number of the application that the package installs, but this has to be done manually.
Contact	Author	This property is used to hold the name of the company/person that created the Windows Installer package. By default, this has the same value as the Manufacturer property.
Support Information	SupportPhone	This property can be used to provide a support telephone number for the application.
	SupportUrl	This property can be used to provide a URL for the product’s support website. The value of this property is represented as a hyperlink in the support information window.
Comments	Description	This property can be used to include any information that you would like to appear in the support information window. For instance, it could be used to detail the opening hours of your support department.

You may need to set several additional properties of the root node. The AddRemoveProgramsIcon property enables you to set the icon that appears in the Add/Remove Programs control panel applet. The default of (None) means that the default icon will be used. You can select an icon with the (Browse) option. The icon can be a standalone icon file or you can select an executable or DLL that contains an icon you want to use.

The Title property is used to set the textual title of the application installed. By default, this property has the same name as the setup project. The remaining properties for the root setup node are for various advanced options, and are not discussed in this walk-through.

Properties of the Primary Output Project Item

Earlier, you added the primary output from the SampleForDeployment Windows application to your deployment project. It should now appear as an item in that project. Primary Output project items also have several important properties that you should know about, including the following:

Open table as spreadsheet

Property	Description
Condition	This enables you to enter a condition that will be evaluated when the installation is run. If the condition evaluates to True, then the file will be installed; if the condition evaluates to False, then the file won’t be installed. If you only wanted a particular file to be installed and the installation was being run on Microsoft Windows 2000 or better, you could enter the following for the condition: VersionNT >= 5.
Dependencies	Selecting this property displays a window that shows all the dependencies of the selected project output.
Exclude	Use this property to indicate whether you want the project output to be excluded from the resulting Windows Installer package.
Folder	This property enables you to select the target folder for the project outputs.
KeyOutput	This property expands to provide information about the main file that makes up the project output. In your case, it will show information for the WindowsApplication.exe file.
Outputs	Selecting this property displays a window listing all the files that are part of the project output, including where these files are located on the development machine.
Permanent	This property is used to indicate whether the files that make up the project output should be removed when the application is uninstalled (False) or left behind (True). It is advisable to remove all files installed by an application when the application is uninstalled. Therefore, this property should be set to False, which it is the default.
ReadOnly	This property is used to set the read-only file attribute of all the files that make up the project output. As the name suggests, this makes the file read-only on the target machine.
Register	This property enables you to instruct the Windows Installer to register the files contained within the project output as COM objects. This only applies to projects (for example, the Class Library project template) that have been compiled with the Register for COM Interop project property set.
Vital	This property is used to indicate that the files contained within the project output are vital to the installation - if the installation of these files fails, then the installation as a whole should fail. The default value is True.

Properties of the Detected Dependency Items

Items that reside in the DetectedDependencies folder have some of the preceding properties, and they also have some read-only properties that provide you with detailed information about the item. This chapter does not include a detailed discussion of those informational properties.

This has been a brief look at the Setup Project template. It uses all the project defaults and provides a standard set of steps to users when they run the Windows Installer package. Of course, a real application needs more than a single application file and its dependencies. The setup project can be customized extensively to meet those additional needs.

Besides adding more files to the deployment project, you may need to create shortcuts, directories, registry entries, and so on. These customizations and more can be accomplished using the set of built-in editors, covered in the section “Modifying the Deployment Project.”

Creating a Deployment Project for an ASP.NET Web Application

Another commonly used deployment scenario is that of a Web application that has been created using the ASP.NET Web Application Project template. Typically, the Web application is developed on a development Web server, and you need to create a deployment project to transfer the finished application to a production Web server.

For this scenario, the template to use is the Web Setup Project template. There is one major difference between this template and the previous Setup Project template: The Web Setup Project, by default, deploys the application to a virtual directory of the Web server on which the setup is run, whereas a Setup Project deploys the application to the Program Files folder on the target machine by default.

There are substantial similarities in producing a deployment project for this scenario and producing a Windows application deployment project as shown in the walk-through. They both produce a Windows Installer package and have the same set of project properties discussed earlier in the walk-through.

As in the previous walk-through, you need to add the output of the Web application to the deployment project. This is accomplished in pretty much the same way as the previous walk-through: by right-clicking on a Web setup project and selecting Add Project Output. There is one key difference. When you add the project representing the website, the only option you have for the type of files to add is Content Files, which encompasses the files that make up the website.

A typical resulting project will look similar to Figure 22-5.

Figure 22-5

As before, if you build such a project, the result in an .msi file, which can be used in this case to deploy a website.