Implementing a Deployment Solution

Visual Studio .NET includes the tools necessary to build deployment projects for desktop applications, Web applications, and device applications. For each target application type, the necessary steps and tools are similar. In all cases, the steps include creating a deployment project, adding necessary files, adding necessary Registry keys, polishing the user interface, and adding any special conditions.

Creating the Deployment Project

You create an installation project just like any other project. Begin by selecting the IssueTracker solution and choosing Add ˜ New Project from the context menu. The Add New Project dialog box displays, as shown in Figure 14-2.

Figure 14-2: Creating a new deployment project in the Add New Project dialog box

Select the Setup and Deployment Projects folder and a template that matches the type of installation project necessary. There are four setup projects to choose from and a wizard that helps determine which of the four templates best matches a particular application.

Specifying the Deployment Project Type

The four standard setup project types target desktop applications, Web applications, merge modules, and cabinet files. The first step in implementing the deployment project is selecting the application type. It is normal for an enterprise application to contain multiple setup projects within one solution. The IssueTracker solution will contain a deployment project for the enterprise Web application, another for the desktop client application, and another for a device application.

Deploying Desktop Applications

The Setup Project template creates a distribution medium for deploying desktop applications. You can configure the project to create folders, move files, set Registry values, and create shortcuts. The output from a setup project is an .msi installer file that contains the application to be deployed, its dependent files, and related application settings.

The Setup Project template is highly configurable. You can customize the user experience to add or remove user steps driving the installation. You can specify the targeted deployment directory and tie it directly back to another project's generated output. Multiple deployment projects might exist within a solution to support different application configurations.

Deploying Web Applications

The Web Setup Project template creates a distribution medium for deploying Web applications. The Web Setup Project template is similar to the standard Setup Project template. Both configure files, folders, Registry keys, actions, and launch conditions that affect deployment to the target computer. However, the Web Setup Project template includes the ability to create virtual directories within the Internet Information Services (IIS) environment.

Distributing Merge Modules

Merge modules package files, resources, and Registry values that multiple applications might share. The output from a merge module project is an .msm file that can be later included by any other deployment project in the same manner that .dll files enable multiple applications to share the same code. And like a .dll, an .msm file cannot be launched independently ”only as a part of a completed .msi deployment application.

Distributing Cabinet Files

Cabinets package multiple files into a single file for download. They simply package files or project output into a single compressed file, much like a .zip file. Cabinet project properties specify the level of compression and whether Authenticode signing should be applied. Cabinet files are most widely used in deploying device applications.

Using the Deployment Editors

Visual Studio .NET provides different editors to interact with the deployment project. These editors customize the files to be deployed, the Registry values to be set, the file types to be associated, the user interface forms to be displayed, the custom actions to take, and the launch conditions to evaluate.

Selecting Files with the File Editor

The Deployment File Editor displays folders that abstract the true destination of files installed on the target computer (see Figure 14-3). Several built-in folder abstractions exist, including the Program Files folder, the Windows folder, the System folder, and the Fonts folder. Application files and shortcuts reside in these different abstract folders, relying upon the Windows Installer to resolve the actual directories on the target computer during installation.

Figure 14-3: Adding distribution files with the Deployment File Editor

Open the Deployment File Editor by selecting the deployment project within the Solution Explorer and choosing View ˜ File System from its context menu. You can add files, assemblies, and project outputs to each abstract folder by selecting the folder name and choosing Add from its context menu. Also, you can create any number of child folders beneath an abstract folder to create any necessary folder structure.

Adding Registry Values with the Registry Editor

The Deployment Registry Editor displays a hierarchy of Registry values that are standard to most versions of the Windows operating system (see Figure 14-4). Additions to the hierarchy of values represent Registry changes that the Windows Installer will need to make during application installation.

Figure 14-4: Adding new Registry keys using the Deployment Registry Editor

Open the Deployment Registry Editor by selecting the deployment project and choosing View ˜ Registry. You can create any number of Registry keys within the hierarchy by choosing from the nodes' context menus . Registry keys can reference installation variable values, such as [Manufacturer] and [ProductName]. For every new key, you can create a new string, binary, or DWORD value. You can also create Registry keys and values conditionally during install time.

Configuring File Types with the File Types Editor

The Deployment File Types Editor configures the target computer to associate a particular file type with an application based on the file's extension (see Figure 14-5). You accomplish this by adding the document type, associating a file extension with the document type, and then associating an application with the file extension.

Figure 14-5: Adding document associations using the Deployment File Types Editor

To associate a file type with an application, select the root node within the Deployment File Types Editor. Choose Add File Types from its context menu to add a new document type node beneath the root node. Type a short description for the new file type, such as IssueTracker Data . Next , open the Properties view and set the Extensions property to the file extension to be associated. Be sure to not precede the extension with a period. You can associate multiple file extensions by delimiting them with a semicolon. Finally, associate the file extension to an application by selecting the Command property and pointing it to the executable application within the distribution, such as Application Folder ˜ Primary Output from WinUI.

You can also associate multiple actions with a file extension. If a deployment project packages separate applications to open, edit, and copy a specific file, then you can add each separate action to associate the same file extension with different application executables.

Note  

When taking ownership of a file extension, be sure to check for existing conflicts. You can find a detailed list of known file extensions online at http://www.filext.com .

Displaying Wizard Steps with the User Interface Editor

You can use the deployment User Interface Editor to add or remove user interface steps displayed within the Setup Wizard during the application deployment (see Figure 14-6). Several predefined dialog boxes exist to collect different information and to present different types of status to the user.

Figure 14-6: Setting wizard steps using the deployment User Interface Editor

Open the deployment User Interface Editor by selecting the deployment project and choosing View ˜ User Interface from its context menu. Although you can display standard setup wizard dialog boxes, such as Welcome, License Agreement, and Destination Folder, Visual Studio .NET also includes several custom dialog boxes to collect custom user choices. These choices are then associated with custom actions that allow the Windows Installer to perform special deployment-related tasks . You can configure each dialog box to display a default Windows Installer message or a custom message.

The editor also separates the general user's view of the setup program from the administrator's view. This function provides the administrator with all steps of the Setup Wizard, including the target folder. Administrators can then create an image of the installation that has optional fields, such as target folder, set to a new default value. Internal company employees could download the image from the local intranet and interact with a limited subset of the Setup Wizard.

Adding Functional Steps with the Custom Actions Editor

The deployment Custom Actions Editor invokes custom actions implemented in external binary files (see Figure 14-7). The Windows Installer supports custom actions that are implemented in .dll, .exe, script, or assembly files to be invoked during the install, uninstall, rollback, or commit stages of the deployment. You can use custom actions for a variety of tasks, including creating or configuring the application data sources.

Figure 14-7: Adding custom actions using the deployment Custom Actions Editor

You can invoke custom actions after the actual installation completes; you do not have access to properties set during the installation. To pass information from the install program to a custom action, set the CustomActionData property. Custom actions that fail will result in the entire installation failing, causing a complete setup rollback. You can place conditions on any custom action using the Condition property.

Setting Conditions with the Launch Conditions Editor

The deployment Launch Conditions Editor sets conditions for the installation (see Figure 14-8). Launch conditions allow the setup program to install specific files depending upon tested conditions, such as operating system version or the installed presence of the .NET Framework. To test conditions, the editor also enables searches for files, Registry settings, or registered components .

Figure 14-8: Adding launch conditions usng the deployment Launch Conditions Editor

Visual Studio automatically adds a launch condition that checks for the existence of the .NET Framework runtime environment. To add a launch condition to a deployment project, first add search criteria. Select the Search Target Machine node and choose Add File Search. You add new search criteria to the tree, and file search properties appear in the Properties window. Set the file properties necessary to locate the file on the target computer, such as FileName, Folder, MinDate, and MaxDate. Next, create a new launch condition by selecting the Launch Conditions node and choosing Add Launch Condition from its context menu. For the launch condition's properties, select the search criteria to link to, a Uniform Resource Locator (URL) pointing to the download location of the missing files, and an error message to present to the user.

Note  

You can find a complete reference of the installation properties at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/properties.asp .

Creating a Windows Application Setup

After selecting a project type and adding a new project to the solution, the next step is to add the distributable application files. Open the deployment File Editor by selecting the setup project in the Solution Explorer, opening its context menu, and choosing View ˜ File System. The Add Project Output Group dialog box will display. Select WinUI as the source project and choose Primary Output, Localized Resources, and Content Files for the distributable files, as shown in Figure 14-9.

Figure 14-9: Adding project output files to the distribution

This instructs Visual Studio to pull the built .dll or .exe output from the selected project directly into the distribution package. After the output group is selected, Visual Studio attempts to resolve the project's dependencies and inserts additional nodes into the Solution Explorer, as shown in Figure 14-10.

Figure 14-10: The Solution Explorer view of deployment dependencies checked

After specifying the distribution files and validating the dependencies, add the application shortcuts. You can create a shortcut just about anywhere , but it typically appears in the user's Programs menu and Desktop. To add a shortcut to the Desktop, select the User's Desktop entry in the deployment File Editor, open its context menu, and select Create Shortcut to User's Desktop. In the right pane, open the context menu and select Create New Shortcut. In the Select Item in Project dialog box, select Primary Output from WinUI, as shown in Figure 14-11. This creates a shortcut pointing to the application's .exe file. To add a shortcut to any other distributed file, click the Add File button and browse to its location.

Figure 14-11: Creating application shortcuts linked to project output

After you have created the shortcut, edit the properties to specify a path to an icon or to enter command-line arguments. With folders created, files added, and shortcuts created, a minimal deployment project is complete. After building the setup project, start the .msi file and step through the wizard, as shown in Figure 14-12. Determine if you should add or remove any of the setup wizard steps.

Figure 14-12: A runtime look at the desktop application setup program

When the installation completes, the application should exist in the specified directory. Always test the final installation application on a "clean" computer to ensure that all necessary files have been copied successfully. Also, check that the shortcuts have been created and that the necessary Registry values have been set.

Creating a Web Application Setup

The Web application deployment project is similar to the desktop application deployment project. The most significant difference is the support for deploying files into a virtual directory within the IIS server. The deployment project must specify the alias for the targeted virtual directory; the read, write, browse, and script execution permissions; and the default document to load. The remaining options for specifying Registry values, file associations, launch conditions, and custom actions still apply.

The first step to implementing the Web application deployment project is to add the distributable application files. After creating the setup project within the IssueTracker solution, open the deployment File Editor. Next, select the Web Application Folder entry and choose Add ˜ Project Output from its context menu. In the Add Project Output Group dialog box, select WebUI as the source project and choose Primary Output, Localized Resources, and Content Files for the distributable files.

Visual Studio checks the dependencies associated with the WebUI project and adds them to the Detected Dependencies list. It adds dependencies in the form of .dll files to the Web application's bin directory. Also, it adds the WebUI project's created .dll file to the Web application's bin directory.

Next, you need to add related Web application content to the distribution. From the deployment File Editor, select the Web Application Folder and choose Add ˜ Web Folder from its context menu. Rename the new Web folder to images or to another content directory. Next, select the newly created Web folder and choose Add ˜ File from its context menu. Browse to the source content directory and select the files to be included.

Most applications will need to write application properties, such as product version or database connection information, to the system Registry. To add create a new Registry key on the target computer, open the deployment Registry Editor. Expand the Registry hierarchy to HKEY_LOCAL_MACHINE\Software\[Manufacturer]\[Program Name]. Choose New ˜ String Value from its context menu and edit the properties of the new Registry value. Set the Name property to Version and the Value property to 1.0.0. You can add any number of additional keys and values as needed.

After building the setup project, start the .msi file and step through the wizard, as shown in Figure 14-13. Determine if you should add or remove any of the Setup Wizard steps. Because IIS settings are being changed, the user installing the Web application must have administrative access to the computer.

Figure 14-13: A runtime look at the Web application setup program

When the installation completes, the Web application should exist in the specified virtual directory. Test the installation by opening a Web browser and pointing to the locally hosted Web application to ensure that all necessary files have been copied successfully.

Reusing Deployment Packages with Merge Modules

The merge module deployment project is similar to the desktop and Web deployment projects. However, because it is intended to represent only a part of the installation process, the user interface and launch conditions are omitted. In the deployment File Editor, there are two destination folders: Common Files Folder and Module Retargetable Folder.

Files packaged into a merge module's Common Files Folder are deployed to a directory specified by the merge module itself. Conversely, files packaged into a merge module's Module Retargetable Folder can be deployed to any directory specified by the host setup program. You set the overridden deployment directory using the merge module's exposed Module Retargetable Folder property.

To include an existing merge module into a desktop or Web deployment project, add the merge module project to the solution. Then, open the application deployment project's deployment File Editor and choose Add ˜ Project Output from the context menu. In the Add Project Output Group dialog box, select the merge module.

Once you have completed and distributed a merge module, you should never modify it. There is no integrated version control, and it is easy for an .msm file to be mixed up, causing the applications that rely on them to fail. Instead, create a new merge module for each successive version of the deployed package and ideally embed a version label into the .msm filename itself.

Deploying Device Applications with Cabinet Files

The CAB deployment project is probably the most different from the other deployment projects. This is largely because there are no custom deployment editors, and it does not interact at all with the Windows Installer. It is simply a compressed package file that contains multiple application files, much like a .zip file. Although it is little more than a convenient method of packing directories full of files, its greatest benefit is in building device deployment projects.

Device applications are typically simple in their organization. You can build and package a device application into a single cabinet file containing all application files. Once the cabinet file is moved to the device through a desktop synchronization, the contents of the file can be self-extracted into the appropriate device directory structure. This is actually how the .NET Compact Framework is deployed to devices.

To add device application files to a cabinet file, select the PocketUI project within the Solution Explorer and choose Build Cab File from its context menu. Visual Studio creates a new cabinet file in the project's output directory, complete with all device application files, the Compact Framework, and SQL Server CE. It creates multiple versions of the device deployment file for different device processors. You use the PocketUI_PPC.ARM.CAB file for deployment to a Compaq IPAQ running the Pocket PC operating system.

After copying the cabinet device deployment file to the device, the user can click it to trigger an automatic installation. All application files reside beneath the Program Files directory in a directory with the same name as the device application project. The device application will also appear in the ActiveSync application manager, as shown in Figure 14-14.

Figure 14-14: The ActiveSync application manager

As mentioned in Chapter 11, "Deploying .NET Applications on Wireless Devices," a device application built using the .NET Compact Framework first needs to deploy the Compact Framework to the device. The Compact Framework is also packaged into a cabinet file located in \Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\v1.0.5000\Windows CE\wce300. Beneath this folder are multiple cabinet files targeting the different device platforms, organized by device processor.

To install the Compact Framework on Compaq IPAQ, copy the cabinet files located within the arm directory to the device and click the file to initiate the self-extract process. After you have configured the Compact Framework on the device, the device application can follow.