Installer Packages

As mentioned in Chapter 2, "Planning the Deployment of .NET Framework-based Applications," Windows Installer packages can be created in a variety of applications. For the purposes of this section, we use Visual Studio .NET 2003 to show how the Windows Installer packages are created.

Note

If you are going to create your packages using a different application, you should consult that documentation for further information.

Visual Studio .NET 2003 creates Windows Installer packages from deployment projects. There are four types of deployment project used to create different types of installer packages. The following table shows the different types of package and the projects that correspond to them, along with details of what they may contain:

Table 3.1: Types of Deployment Project

Package	Deployment Project	Can Contain
Windows Applications and Services	Standard Setup Project	Project Output Groups Files and Folders Assemblies Application Resources Merge Modules CAB Files Dependencies Registry Settings Project Properties Custom Actions User Interface Design Settings
Web Applications and Services	Web Setup Project	Project Output Groups Files and Folders Assemblies Application Resources Merge Modules CAB Files Dependencies Registry Settings Project Properties Custom Actions User Interface Design Settings
Merge modules	Merge Module Project	Project Output Groups Files and Folders Registry Settings Assemblies Application Resources Custom Actions Settings
CAB files	CAB File Project	Project Output Groups ActiveX controls Controls activated by a Web service

To create Windows Installer files, you need to add some or all of the elements listed in the table to the appropriate deployment project. In this section we discuss each of the steps to follow to create an installer package. We focus on setup projects (standard and Web) as these allow you to create Windows Installer packages for Windows-based and Web-based applications and services. However, we also cover the specific issues related to creating merge module projects and CAB file projects.

Note

You can create deployment projects in Visual Studio .NET 2003 by using the setup wizard. For more information on the setup wizard, see "Distributing the Visual J# .NET Redistributable Package" on MSDN.

Adding Project Output Groups

The most important elements to add to your setup projects are one or more project output groups. These represent the application itself as built in Visual Studio .NET 2003. A project output group may include any or all of the following:

• Documentation Files (generated by C# projects)

• Project Output (the executable)

• Localized Resources

• Debug Symbols

• Content Files (for example html and aspx pages)

• Source Files

In some cases you can add all the information you need to a Windows Installer package simply by adding several project output groups. In others, a number of other steps are required, as detailed in the rest of this module.

• To add a project output group to a deployment project

  1. Select a target folder in the File System Editor.

  2. On the Action menu, point to Add, and then click Project Output.

  3. In the resulting Add Project Output Group dialog box, select a project from the Project list.

  4. Select the type of output from the outputs list. You can select multiple outputs from the list.

  5. Optionally, select a different configuration from the Configuration list.

  6. Click OK to apply the selection and close the window.

Note

The Project Output command is also available from the Project menu. Choosing this command from the Project menu rather than the Action menu causes the project outputs to be placed in the Application folder rather than in the target folder you have selected. This will also happen if you add the project from Solution Explorer rather than File System Editor.

The advantage of adding project output groups rather than the individual elements of a project is that much of the work has already been done for you. This means that it is easier to ensure that you add everything you need and Visual Studio .NET is already aware of any dependencies.

Note

In some cases you will not want to add all of the files in a project output group. For example, if you decide to add content files, it may not be appropriate to add all of those files to your production servers. You can add a filter to the project output group to control which files will actually be deployed. For more information see the article "Excluding Files from a Project Output Group" on MSDN. See More Information at the end of this chapter for further details.

Adding Files

After adding project output groups to your deployment project, you may need to add additional files. Your setup project should include all the files you need to add during the setup process. This will include some or all of the following:

Table 3.2: Files that May Be Added to a Setup Project

Potential Items in a Package	Standard Setup Project	Web Setup Project
Files and Folder
Executables
Libraries
Data Files
Services
COM/COM+ Components
Event Log Resources
Message Queue Resources
Performance Counters and Categories
Debug Symbols
Security Policies
NET Configuration files
Web Pages
Web Forms
Web Services
Discovery Files for Web Services
XML Schema Definition Files

You can use File System Editor in Visual Studio .NET 2003 to add files to a deployment project, to specify the locations where files will be installed on a target computer, and to create shortcuts on a target computer.

• To add files to a deployment project

  1. In Solution Explorer, select a deployment project.

  2. On the View menu, point to Editor, and then click File System.

  3. Select a target folder in the File System Editor.

  4. On the Action menu, point to Add, then click File…

  5. In the resulting Add Files dialog box, select a File, and click Open.

  6. Repeat steps 3-5 as required.

You can add special folders and custom folders to deployment projects. Special folders correspond to predefined Windows folders. The physical location of these folders can vary from one computer to another: for example, the System folder may be located in C:\Windows on one computer, D:\Windows on another, and C:\Winnt on a third. Regardless of the physical location, Windows recognizes the folder as the System folder by reading special attributes. Using special folders in a deployment project allows you to choose a destination folder on a target computer without knowing the actual path to that folder.

Custom folders represent other folders on a target computer. Unlike special folders, custom folders do not necessarily depend on existing folders on the target computer, but rather allow the setup package to create new folders at install time.

• To add special folders to a deployment project

  1. In Solution Explorer, select a deployment project.

  2. On the View menu, point to Editor, and then click File System.

  3. Select the File System on Target Machine computer icon, right-click and select Add Special Folder, and then select the folder you wish to include (such as the Global Assembly Cache).

  4. Add files and additional folders as necessary.

Note

For more information on Special Folders and custom folders, see "Special Folders and Custom Folders" on MSDN

Adding Configuration Files

Configuration files are deployed in the same way as any other files. However, they are of particular interest as they may contain information specific to the deployment of a .NET-based application.

As mentioned in Chapter 3, "Planning the deployment of .NET Framework-based Applications," one of the major challenges of configuration file deployment is that they may vary during the different stages of the application lifecycle. You need to ensure that the right configuration files are used at each stage.

A developer can use Visual Studio.NET to manage this process by specifying a configuration override file in the application project. The override file allows you to specify which configuration file should be built into a Windows Installer file when you build the setup project for your application. Exactly how you specify the file will vary depending on whether the application is developed in Visual Basic or C#.

Configuration Override File in Visual Basic Projects

To define the configuration override file option in Visual Basic projects, you should specify the appropriate configuration file on the Deployment page of the Configuration Properties section in the Property Pages dialog box. For example, if you are about to build a Windows Installer file for deploying your application to the production environment, you might specify Production.app.config or Production.web.config as the override file for your application's project.

When you come to build the deployment project, Visual Studio .NET 2003 packages the configuration override file with your other build outputs and renames it to the required name for you in the Windows Installer file. For example, if you are packaging an ASP.NET application, Visual Studio names the configuration override file web.config. When you run the installer, the configuration file is deployed along with your application.

Configuration File Override in C# Projects

The override file setting is not available in the property pages of C# applications, but you can still use configuration override files for your C# solutions. You need to edit the .csproj file to achieve this. The following example shows how to specify a configuration override file in the .csproj file for a C# Web application.

 … … <Config   Name = "Release"   AllowUnsafeBlocks = "false"   BaseAddress = "285212672"   CheckForOverflowUnderflow = "false"   ConfigurationOverrideFile = "production.web.config"   DefineConstants = "TRACE"   DocumentationFile = ""   DebugSymbols = "false"   FileAlignment = "4096"   IncrementalBuild = "false"   Optimize = "true"   OutputPath = "bin\"   RegisterForComInterop = "false"   RemoveIntegerChecks = "false"   TreatWarningsAsErrors = "false"   WarningLevel = "4" /> … … 

Note

In this example, the ConfigurationOverrideFile entry is set for the Release section — it is possible to modify the .proj file to specify different override files for different build configurations.

Adding Assemblies

The different elements of an assembly can reside in separate files, or, they can be grouped together in a single PE file, such as a .dll or an .exe file. For example, you might want large graphics or seldom used types to reside in separate files — that way they will only be loaded when required by the application.

Note

Instrumented assemblies need to be added to your project as custom actions and so are covered in that section.

As mentioned in Chapter 2, assemblies that are used by a single application should be deployed as a private assembly:

• To add a private assembly

  1. Select a target folder in the File System Editor.

  2. On the Action menu, point to Add, and then click Assembly.

  3. In the resulting Component Selector dialog box, browse to the assembly you want to add, click Select for each assembly you wish to apply, and click Close to apply the selections and close the window.

Note

The Component command is also available from the Project menu. Choosing this command from the Project menu rather than the Action menu causes the assembly to be placed in the Application folder rather than in the target folder you have selected.

Assemblies that will be used by multiple applications or used by a distributed application will often be installed in the global assembly cache. However, before you can install assemblies in the global assembly cache, you first need to ensure that the file system includes a reference to the global assembly cache folder itself. (By default it only includes references to three folders on the target machine: the Application folder, the user's desktop, and the user's Programs menu.)

• To add a reference to the global assembly cache

  1. Right-click on File System on Target Machine.

  2. Click Add Special Folder.

  3. Select Global Assembly Cache Folder.

Once the reference has been added, you are now in a position to add any strong-named assemblies to the global assembly cache.

• To create a shared assembly

  1. In the Files Editor, right-click Add, and select the Global Assembly Cache Folder.

  2. Select the Global Assembly Cache Folder, right-click and point to Add…, Click either Assembly or Project Output Group (that contains the assemblies you want added to the global assembly cache).

  3. Select the Assembly or Project Output Group and click OK. For each choice you will have another dialog box appear:

     For Assemblies:

     1. In the resulting Component Selector dialog box, browse to the assembly you want to add, and click Select for each assembly you wish to apply.

     2. Click OK to apply the selections and close the window.

     For Project Output Groups:

     1. In the resulting Add Project Output Group dialog box, select a project from the Project list.

     2. Select the type of output from the Outputs list. You can select multiple outputs from the list.

     3. Optionally, select a different configuration from the Configuration list.

     4. Click OK to apply the selection and close the window. You will now see the assemblies in the Global Assembly Cache folder.

Note

For more information on when to use the global assembly cache or for strong-naming assemblies, see Chapter 2, "Planning the Deployment of .NET Framework-based Applications."

Adding COM Components

Any COM components required by your .NET-based application should either already exist on the target computers or be deployed along with your application. If you are using Visual Studio .NET setup and deployment projects, the COM dependencies of your .NET assemblies are detected and included in the detected dependencies list. However, any other dependencies of the COM object cannot be automatically detected and must be manually included into the setup project for deployment.

• To set a COM component to register automatically on install

  1. Select the COM component, right-click and click Properties.

  2. Under the Register property select one of the five options:

     1. vdsrpDoNotRegister: The item requires no registration.

     2. vsdrpCOM: The item will be registered as a COM object.

     3. vsdrpCOMRelativePath: The item will be registered as an isolated COM object.

     4. vsdrpCOMSelfReg: The item will be self-registered as a COM object when it is installed. Not available for assemblies.

     5. vsdrpFont: The file will be registered as a font file when it is installed.

Along with your COM+ components, you also need to deploy the interop assembly that allows it to communicate with your .NET-based applications. You can either place the interop assembly in the global assembly cache or deploy it as a private assembly. As COM components have computer-wide visibility, you should normally install interop assemblies in the global assembly cache so that the interop assembly for the component is visible to all .NET applications on that computer.

When you deploy a primary interop assembly to development computers, you should always register the primary interop assembly with Regasm.exe on the development computer. This places entries into the registry that associate the primary interop assembly with the COM object. In addition to using Regasm.exe, you must then place the primary interop assembly in the global assembly cache on the development computer. When a developer then adds a reference to the COM component in Visual Studio .NET 2003, the fact that there is a primary interop assembly associated with this COM component is detected and Visual Studio .NET 2003 does not generate an alternate interop assembly. At run time, the primary interop assembly is found in the global assembly cache and loads properly on the development computer.

For more information about deploying all required COM components, see the following articles on MSDN:

• "Deploying COM+ Applications"

• "Application Deployment Using Microsoft Management Technologies"

Adding Security Policy

Security policy is managed by administrators at three different levels: enterprise, computer, and user. In addition, developers can specify security policy in code for their application domains.

Security policy can be easily distributed and applied using Windows Installer files. The .NET Framework configuration tool (Mscorcfg.msc) provides a wizard for creating Windows Installer files for your security policy. The wizard creates a Windows Installer file that corresponds to one of the three configurable policy levels (enterprise, computer, and user), but not all of them concurrently. If you are deploying security policy for all three configurable levels, you must create three different Windows Installer files and deploy them individually.

The wizard creates the Windows Installer file using the current policy settings of the computer where the wizard executes. For example, to create a user policy for deployment to a group of users, you configure the user policy on your current computer, create the Windows Installer file with the wizard, and then return the user policy of the current computer to its original state.

You need to ensure that the user account under which the policy is installed has adequate privileges to access the configuration files you are modifying. For example, if you are currently logged on using an account that does not have permission to modify the enterprise configuration file, and the Windows Installer file needs to modify that file, the installation does not succeed. Note that the Windows Installer package does not produce an error if the current account does not have sufficient permission to modify the configuration file.

If you need to deploy security policy with your application, you can create a nested setup whereby the security policy installer is launched from inside the application installer.

• To create the policy installer package

  1. Open the Microsoft .NET Framework 1.1 Configuration tool.

  2. Expand the Runtime Security Policy folder.

  3. Make sure the policies on this machine are the same as what should be published by the installer package.

  4. Select the Runtime Security Policy folder again.

  5. Under Tasks, click Create Deployment Package.

  6. Click your policy level (Enterprise, Computer or User) and indicate the location and filename of the installer package the wizard is about to create.

  7. Click Next.

  8. Click Finish.

Managing Merge Modules

The main advantage of using merge modules is that you only need to define the setup logic for the assemblies in the .msm file once, rather than for each instance of the application. The .msm file needs only to be added to the Windows Installer file once, even though multiple applications in the installer file depend on their components. If you need to upgrade the assemblies in the .msm file, you need to only create a new .msm file and include that in your Windows Installer file for redeployment.

Note

For more information about updating and redeploying components packaged in .msm files, see Chapter 4, "Maintaining .NET Framework-based Applications."

Here are some recommendations for using merge modules:

• For components that are shared across multiple applications (or have the potential to be shared) you should package each component in its own .msm file. This allows you to deploy that .msm file with the installer package of the application that uses the component without needing to repackage the component every time. While it is possible to put multiple components into a single merge module, it is best to create a separate merge module for each component to avoid distributing unnecessary files.

• Installer packages can include multiple applications, allowing you to install a suite of applications in a single step. In this case, the installer package should include merge modules for all components used by any of the included applications. If a merge module is used by more than one application it needs to be added to the installer package only once.

• You should capture all of the dependencies for a particular component. After you distribute a merge module, it should never be modified. Instead, you should create a new merge module for each successive version of your component in your merge module to ensure that the component is installed correctly.

• Each merge module contains unique version information that is used by the Windows Installer database to determine which applications use the component, preventing premature removal of a component. For this reason, a new merge module should be created for every incremental version of your component. A merge module should never be updated after it is included in an installer package.

• You should generally use merge modules for applications developed in-house, not for software that you ship externally, as you cannot prevent it becoming part of any other application. For most code that you are shipping externally, you should ship as an .msi instead.

In some cases you will be provided with existing merge module projects that you need to add to your setup project.

• To add an existing merge module project to a solution

  1. On the File menu, point to Add, and then click Existing Project.

  2. In the resulting Add Existing Project dialog box, browse to the location of the merge module project and click Open.

In other cases the work will not already have been done for you and you will need to create a new merge module.

• To create a new merge module

  1. On the File menu, point to Add, and then click New Project.

  2. In the resulting Add New Project dialog box, select the Setup and Deployment Projects folder.

  3. Click Merge Module Project.

  4. Add the files and components you require.

  5. Click OK.

• To add an existing merge module (from a third party developer) to a deployment project

  1. Right-click the deployment project, point to Add.

  2. Click Merge Module…

  3. Select the merge module (*.msm), and click Open.

Note

Deployment projects for applications that reference the .NET Framework automatically add a merge module (dotnetfxredist_x86_xxx.msm, where xxx represents the language code) in the detected dependencies folder. This merge module cannot be redistributed; it exists for internal use by the project to prevent individual .NET assemblies from being listed. It is excluded by default; attempting to include it will cause a build error.

By default, files in your merge modules are installed into the folder locations you specify when you build the .msm file. In some cases, you may want to allow the developer who uses your merge module some flexibility in deciding where files should be installed for their application. For example, if an assembly in a merge module is used by multiple applications, the developer may want to install it in the global assembly cache; otherwise, they would install it in the application directory.

To allow other developers to retarget your files to a different location, you should place them in the Module Retargetable folder in your merge module project. When the resulting merge module is added to another deployment project, the author of that project can choose a location for your files by setting the Module Retargetable Folder property exposed by your built merge module in their installer package.

You can provide a default location for files in the Module Retargetable folder by setting its DefaultLocation property. You can set this to any of the following:

• [CommonFilesFolder]

• [FontsFolder]

• [GAC]

• [ProgramFilesFolder]

• [SystemFolder]

• [WindowsFolder]

• [TargetDir]

The [TargetDir] setting corresponds to the application folder for the solution that is deployed with the installer package that includes your merge module. The other folders in the list should be self-explanatory.

Setting Merge Module Project Properties

In addition to the properties that merge module have in common with installer packages, they also support a ModuleSignature property. This property specifies a unique identifier for the merge module. The ModuleSignature property contains the name of the merge module followed by a globally unique identifier (GUID). Each released version of a merge module must have a unique ModuleSignature property in order to avoid versioning problems. You should never manually edit the GUID portion of this property — you should use the GUID generation facilities in the Module Signature dialog box.

Building a Merge Module

As with project properties, merge module projects support a subset of the build options available for installer packages. These include:

• Output file name

• Compression

• Authenticode signature

For more information about these options, see the Build Your Windows Installer File section later in this chapter.

For step-by-step instructions on how to create and use merge modules, see "Creating or Adding a Merge Module Project" on MSDN.

Managing CAB Files

In some cases you will be provided with existing CAB projects that you need to add to your setup project.

• To add an existing cab project to a solution

  1. On the File menu, point to Add, and then click Existing Project.

  2. In the resulting Add Existing Project dialog box, browse to the location of the CAB project, and click Open.

In other cases you may wish to group existing files and components into a new CAB project.

• To create a new CAB project

  1. On the File menu, point to Add, and then click New Project.

  2. In the resulting Add New Project dialog box, select the Setup and Deployment Projects folder.

  3. Click Cab Project.

  4. Add the files and components you require.

  5. Click OK.

To add a CAB file to a deployment project, you can import the *.cab file as either a single file or as the project output of a CAB project. (See earlier steps for how to add files or project output groups.)

Properties of CAB projects allow you to specify a level of compression and implement Authenticode signing, which allows administrators to grant higher trust to these controls without reducing their security with regard to other intranet/Internet code. You can also set the following properties for your CAB file project:

• FriendlyName. Specifies the public name for the CAB file.

• Version. Specifies the version number of the CAB file. As with the other types of setup projects, the Version property should be changed for each released version of your CAB file.

• WebDependencies. Specifies the URL, friendly name, and version of other CAB files that must be installed in order for the selected CAB project to be successfully installed. If this property is set, all dependencies are automatically downloaded and installed when the CAB file is run. You can specify multiple Web dependencies using the Web Dependencies dialog box, which is accessible from the Properties window.

Note

For more information about managing the security requirements for downloaded CAB files, see "Writing Secure Managed Controls" on MSDN.

Unlike the other deployment project types, there are no editors provided for working with CAB projects. Files and project outputs can be added to a CAB project in Solution Explorer, and properties can be set in the Properties window or in the project property pages.

Adding Dependencies

Deployment projects in Visual Studio .NET automatically detect dependencies and add them whenever a project output group, assembly, or merge module is added to the project. For assemblies, all dependencies on other assemblies are detected. However, if the assembly references an unmanaged component (for example, a COM .dll), any dependencies of the unmanaged component will not be detected. Likewise, COM components added directly to a deployment project may have dependencies that are not detected.

Note

Rather than adding assemblies directly to a deployment project, it is best to add a project output group that contains the assembly. The deployment tools can more reliably detect dependencies for a project output group.

You need to determine all of the possible dependencies for your COM components and include those files in the deployment project. You should check the documentation for the component or contact the component's author to get a list of dependencies. Alternatively, you can obtain a merge module (an .msm file) for the COM component to deploy the component and its dependencies — the developer who created the .msm file should already have defined and included the dependencies for their component and included them in the .msm file.

Adding Launch Conditions

One of the more powerful features of Windows Installer is the ability to set conditions for installation, allowing you to customize installations on a case-by-case basis. The deployment tools in Visual Studio .NET support conditional deployment through launch conditions. Using the Launch Conditions Editor you set the Condition property, which is then compared against the environment on the target computer. For example, you might want to install different files based on operating system version, customize registry settings based on the value of an existing key, or even halt installation if a dependent application is not already installed on the target computer. Launch conditions can be set to check for the operating system version, existence of files, registry values, Windows Installer components, the CLR, and IIS. Launch conditions are specified in the Launch Conditions Editor.

• To add a launch condition

  1. On the View menu, point to Editor, and then click Launch Conditions when a deployment project is selected in Solution Explorer.

  2. Right-click on Requirements on Target Machine and select one of the following choices. For each choice, two entries are created: One entry in the Search Target Machine folder and one in the Launch Conditions folder. The entry in the Search folder specifies where the package should look for a needed entry and the Condition folder specifies what conditions should be found to make the condition true.

     1. Add File Launch Condition. This launch condition allows you to search for a particular file as a condition. In the properties of the search you can input a specific file, including location, date, size and version, or search for a range of values. You can also specify the depth of the search, which determines how many levels of subfolders should be included in the search.

     2. Add Registry Launch Condition. This launch condition will allows you to search for a particular registry entry as a condition. In the properties of the search you can input a specific registry location and key as your value.

     3. Add Windows Installer Launch Condition. This creates a pre-built search function that will check to make sure that the target machine has Windows Installer 2.0 or later. The GUID of the installer package needs to be included in the properties of the search function.

     4. Add .NET Framework Launch Condition. This creates a pre-built search function that will check to make sure that the target machine has a version of the runtime supported by the application. Which versions are supported is determined by the <SupportedRuntimes> property in the application configuration file. Nothing needs to be done to this entry since the information is automatically populated.

     5. Add Internet Information Services Condition. This creates a pre-built search function that will check to make sure that the target machine has IIS 4.0 or greater. Since ASP.NET applications work on IIS 5.0 or later you should modify the Condition property from REGISTRYVALUE >= "#4" to REGISTRYVALUE >= "#5". This ensures that only IIS 5.0 or later is supported.

  3. In the Launch Conditions folder under the InstallUrl property, you can specify the location where the user can download files if a launch condition evaluates to false. If this property contains a value, the user is presented with a dialog box containing Yes and No buttons, plus the message specified in the Message property. If the user selects Yes, they will be redirected to the location specified in the property; in either case the installation will be terminated immediately.

  4. In the Launch Conditions folder under the Message property, you can specify the error message that will be displayed if the launch condition is not met. For the automatically populated conditions (IIS and .NET Framework) a message is provided.

For more information about working with launch conditions, see "Launch Condition Management in Deployment" on MSDN.

For more information about using the Condition property, see "Deployment Conditions" on MSDN.

One commonly used launch condition is for applications that use J#. As mentioned in Chapter 2, "Planning the Deployment of .NET Framework-based Applications," for a J# application to run, you have to deploy the J# redistributable package. For more information on adding a launch condition for the J# redistributable package, see "Distributing the Visual J# .NET Redistributable Package" on MSDN.

Another common launch condition is for applications that require MDAC. As mentioned in Chapter 1, "Introduction", MDAC is prerequisite for many Framework applications. For more information on adding an MDAC launch condition, see "Adding a Launch Condition for Microsoft Data Access Components" on MSDN.

Adding Registry Settings

Registry keys can be added to a deployment project using the Registry Editor in a Visual Studio .NET 2003 deployment project.

• To add a registry entry to the deployment project

  1. In Solution Explorer, select a setup project.

  2. On the View menu, point to Editor, and then click Registry.

  3. Under the list select the path (HKLM for example) and create a new registry key to be added.

If a key doesn't exist in the registry of a target computer, it will be added during installation. Keys can be added beneath any top-level key in the Registry Editor.

Note

For instructions on how to add registry keys to your projects, see "Adding and Deleting Registry Keys in the Registry Editor" on MSDN.

The Registry Editor can be used to specify values for new or existing registry keys in the registry of a target computer. You can add string, binary, and DWORD values. The values are written to the registry during installation. The values you specify overwrite any existing values.

Note

By modifying the registry table directly in the Orca database editor tool you can also add REG_EXPAND_SZ and REG_MULTI_SZ values to the registry. For more information on this see "Registry Table" in MSDN.

Registry keys and values can be added to a deployment project by importing a registry file (.reg) into the Registry Editor. This allows you to save time by copying an entire section of an existing registry in a single step. Registry files can be created using tools such as the Registry Editor (Regedit.exe) included with Windows 2000.

You can also use the Registry Editor to specify a default value for any registry key. For more information on this see "Creating a Default Registry Value in the Registry Editor" on MSDN.

Note

As with managing files and folders, if a user is running the installer package directly, the user must have the appropriate permissions to modify the registry; otherwise, installation fails when the Windows Installer attempts to create, modify, or delete registry keys and values. For example, the user must have local administrative privileges if your installer creates, deletes, or modifies keys and values in the HKEY_LOCAL_MACHINE hive.

COM Calling to .NET

When deploying .NET assemblies that will be used by COM, you must make the .NET assemblies visible to COM by registering the .NET assembly. This is done by creating an entry in the registry that points to Mscoree.dll, which then loads and executes the .NET assembly.

After the .NET assembly is registered, it must be located where it can be found by the .NET runtime. This means it must be placed in one of the following locations:

• The global assembly cache

• The application base directory, which is usually the .exe directory or the bin directory in a Web application

Adding File Associations

If your application includes (or creates) files as part of its normal operation, then you might want those files to be associated with your application. For example, you might want any file that your application creates to open with your executable file if the user attempts to open the file. The File Types Editor is used to establish file associations on the target computer, by associating file extensions with your application and specifying the actions allowed for each file type.

• To add a file association

  1. In Solution Explorer, select a deployment project.

  2. On the View menu, point to Editor, and then click File Types.

  3. Set the file association with the primary output, and click OK.

Note

For more information about editing file associations, see "File Types Management in Deployment" on MSDN.

Setting Project Properties

To have your installer package contain all of the information needed to install correctly, you should manipulate properties that control how your Windows Installer files interact with Windows Installer. While this can be done at any stage of the package creation process, the more property information you can discover and include beforehand, the easier the creation process will be.

Deployment projects have two categories of properties: general project properties and configuration-dependent properties. General properties apply to all project configurations, whereas configuration-dependent properties apply to a specific project configuration.

• To set general project properties

  1. In Solution Explorer, select a deployment project.

  2. Right-click and select Properties.

  3. In the Solution Property Pages dialog box, select the View menu, and click Property Pages.

• To set configuration-dependent project properties

  1. On the View menu, choose Property Pages.

  2. Select a configuration from the Configuration list.

  3. Select a category from the list of categories. The properties for the selected category will be displayed.

Note

If most of your deployment properties are common across all configurations, you can avoid duplicate effort by choosing All Configurations. Once the common properties are set, choose another configuration and set any unique properties.)

These are the Windows Installer file properties you can manipulate with Visual Studio .NET 2003:

• AddRemoveProgramsIcon. Specifies an icon to be displayed in the Add/Remove Programs dialog box on the target computer. This property has no effect when installing on operating systems such as Windows 98 or Windows NT, where icons are not displayed in the Add/Remove Programs dialog box.

• Author. Specifies the name of the author of an application or component. The Author property is displayed on the Summary page of the Properties dialog box when an installer file is selected in Windows Explorer. After the application is installed, the property is also displayed in the Contact field of the Support Info dialog box, which is accessible from the Add/Remove Programs dialog box.

• Description. Specifies a free-form description for an installer file. The Description property is displayed on the Summary page of the Properties dialog box when an installer file is selected in Windows Explorer. After the application is installed, the property is also displayed in the Support Info dialog box, accessible from the Add/Remove Programs dialog box.

• DetectNewerInstalledVersion. Specifies whether to check for later versions of an application during installation. If this property is set to True and a later version is detected at installation time, installation ends. For more information about working with this property, see Chapter 4, "Maintaining .NET Framework-based Applications."

• Keywords. Specifies keywords used to search for an installer. The Keywords property is displayed on the Summary page of the Properties dialog box when an installer file is selected in the Windows Explorer.

• Localization. Specifies the locale for the run-time user interface.

• Manufacturer. Specifies the name of the manufacturer of an application or component. The Manufacturer property is displayed in the Publisher field of the Support Info dialog box, accessible from the Add/Remove Programs dialog box. It is also used as a part of the default installation path (C:\Program File\Manufacturer\Product Name) displayed during installation.

• ManufacturerUrl. Specifies a URL for a Web site containing information about the manufacturer of an application or component. The ManufacturerUrl property is displayed in the Support Info dialog box, accessible from the Add/Remove Programs dialog box.

• ProductCode. Specifies a unique identifier for an application. This identifier must vary for different versions and languages. Windows Installer uses the ProductCode property to identify an application during subsequent installations or upgrades; no two applications can have the same ProductCode property. To ensure a unique ProductCode property, you should never manually edit the GUID; instead, you should use the GUID generation facilities in the Product Code dialog box. For more information about working with this property, see Chapter 4, "Maintaining .NET Framework-based Applications."

• ProductName. Specifies a name that describes an application or component. The ProductName property is displayed as the description of the application or component in the Add/Remove Programs dialog box. It is also used as a part of the default installation path (C:\Program Files\Manufacturer\Product Name) displayed during installation.

• RemovePreviousVersions. Specifies whether an installer removes earlier versions of an application during installation. If this property is set to True and an earlier version is detected at installation time, the earlier version's uninstall function is called. The installer checks UpgradeCode, PackageCode, and ProductCode properties to determine whether the earlier version should be removed. The UpgradeCode property must be the same for both versions, whereas the PackageCode and ProductCode properties must be different. For more information about working with this property, see Chapter 4, "Maintaining .NET Framework-based Applications."

• RestartWWWService. For Web setup projects only, this specifies whether Internet Information Services stop and restart during installation. Restarting may be required when deploying an application that replaces ISAPI DLLs or Active Template Library (ATL) Server components that are loaded into memory. ASP.NET components do not require a restart when replacing components that are loaded into memory. If this property is not set to True and a restart is required, the installation completes only after the World Wide Web Publishing service is restarted.

• SearchPath. Specifies the path that is used to search for assemblies, files, or merge modules on the development computer.

• Subject. Specifies additional information describing an application or component. The Subject property is displayed on the Summary page of the Properties dialog box when an installer file is selected in the Windows Explorer.

• SupportPhone. Specifies a phone number for support information for an application or component. The SupportPhone property is displayed in the Support Information field of the Support Info dialog box, accessible from the Add/ Remove Programs dialog box.

• SupportUrl. Specifies a URL for a Web site containing support information for an application or component. The SupportUrl property is displayed in the Support Information field of the Support Info dialog box, accessible from the Add/ Remove Programs dialog box.

• Title. Specifies the title of an installer. The Title property is displayed on the Summary page of the Properties dialog box when an installer file is selected in the Windows Explorer.

• UpgradeCode. Specifies a shared identifier that represents multiple versions of an application. This property is used by Windows Installer to check for installed versions of the application during installation. The UpgradeCode property should be set for only the first version; it should never be changed for subsequent versions of the application, nor should it be changed for different language versions. Changing this property prevents the DetectNewerInstalledVersion and RemovePreviousVersions properties from working properly. For more information about working with this property, see Chapter 4, "Maintaining .NET Framework-based Applications."

• Version. Specifies the version number of an installer. The Version property should be changed for each released version of your installer. For more information about versioning, see Chapter 4, "Maintaining .NET Framework-based Applications."

Create Localized Installers

The Visual Studio deployment tools include several features that allow you to distribute different versions of your application for different locales. You need to create a separate installer for each localized version of your application.

To create a localized installer file, you set the Localization property of the deployment project to one of the supported languages (listed in the drop-down list in the Properties window). The Localization property setting determines the language for the default text displayed in the installation user interface dialog boxes, such as button captions and instructions for proceeding with the installation. You cannot see the translated text in the Visual Studio .NET 2003 IDE; you can see only the translated text if you build and run the installer.

• To set the localization property

  1. Open the Solution Explorer and select the deployment project.

  2. Right-click and select Properties.

  3. In the Solution Property Pages dialog box, select the View menu and click Property Pages.

  4. In the Localization property, select the language that this project supports.

Text that is provided by properties is not translated. For example, the ProductName property that determines the name displayed in the title bar of the installation dialog boxes is not translated into the chosen locale, so you need to enter the localized ProductName in the Properties window for each localized deployment project. Other deployment project properties that you may need to localize include:

• Author

• Description

• Keywords

• Manufacturer

• ManufacturerUrl

• Subject

• SupportPhone

• SupportUrl

• Title

• AddRemoveProgramsIcon (if the icon contains text)

Additional properties that may need to be localized include the Name and Description properties for shortcuts in the File System Editor, the Name and Description properties for file types and actions in the File Types Editor, and the Message property for conditions in the Launch Conditions Editor.

Note

If the core files for your application are the same for all locales, you should consider putting the core files in a merge module and adding the merge module plus any locale-specific files to the installer for each locale. Registry settings, custom actions, and file types can be set in the merge module project so that you do not need to recreate them for each project. For an example of a localized Installer package, see "Localizing a Windows Installer Package" on MSDN.

IIS Settings

You can use the project properties of a Web setup project to deploy IIS settings along with your solution. You specify these settings by using the Properties window in the Visual Studio .NET Web setup project, when the Web Application folder (or a subfolder) is selected. The following describes properties that control the IIS virtual directory settings:

• AllowDirectoryBrowsing. Sets the IIS Directory browsing property for the selected folder. This setting corresponds to the Directory browsing check box on the Directory page of the Internet Information Services Web Properties dialog box, and can be set to either True or False.

• AllowReadAccess. Sets the IIS Read property for the selected folder. This setting corresponds to the Read check box on the Directory page of the Internet Information Services Web Properties dialog box and can be set to either True or False.

• AllowScriptSourceAccess. Sets the IIS Script source access property for the selected folder. This setting corresponds to the Script source access check box on the Directory page of the Internet Information Services Web Properties dialog box and can be set to either True or False.

• AllowWriteAccess. Sets the IIS Write property for the selected folder. This setting corresponds to the Write check box on the Directory page of the Internet Information Services Web Properties dialog box and can be set to either True or False.

• ApplicationProtection. Sets the IIS Application Protection property for the selected folder. This setting corresponds to the Application Protection selection on the Directory page of the Internet Information Services Web Properties dialog box. It can be set to:

  • vsdapLow. The application runs in the same process as IIS.

  • vsdapMedium. The application runs in an isolated pooled process in which other applications are also run.

  • vsdapHigh. The application runs in an isolated process separate from other processes.

• AppMappings. Sets the IIS Application Mappings property for the selected folder. This setting corresponds to the Application Mappings list on the App Mappings page of the Internet Information Services Application Configuration dialog box.

• DefaultDocument. Specifies the default (startup) document for the selected folder. This setting corresponds to the list of default documents on the Documents page of the Internet Information Services Web Properties dialog box. You can specify a comma-separated list to specify multiple default documents — the order of precedence for the default documents in taken from their relative positions in your comma-separated list.

• ExecutePermissions. Sets the IIS Execute Permissions property for the selected folder. This setting corresponds to the Execute Permissions list on the Directory page of the Internet Information Services Web Properties dialog box. You can set it to:

  • vsdepNone. Only static files, such as HTML or image files, can be accessed.

  • vsdepScriptsOnly. Only scripts, such as Active Server Pages scripts, can be run.

  • vsdepScriptsAndExecutables. All file types can be accessed or executed.

• Ports. Sets the port where a Web service is located on the target computer.

• LogVisits. Sets the IIS Log Visits property for the selected folder. This setting corresponds to the Log visits check box on the Directory page of the Internet Information Services Web Properties dialog box and can be set to either True or False.

• Virtual Directory Name The alias of the virtual directory. This virtual directory will be created if it doesn't already exist.

For more information about programmatically defining these IIS 6.0 Settings, see "Programmatic Administration Guide."

For more information about IIS Security in ASP.NET applications see "Authentication in ASP.NET: .NET Security Guidance" on MSDN.

Adding Custom Actions

Custom actions allow you to perform actions at the end of the installation that cannot be handled by the standard process. The custom action will typically add files, components, or project output groups and you may add scripts to control the nature of the install. For example, you might want to create a local database on the target computer during installation. You could create an executable file that creates and configures the database, and then add that executable file as a custom action in your deployment project.

The Custom Actions Editor in Visual Studio .NET is used to manage custom actions in a deployment project. A deployment project can contain multiple custom actions, and you can control the order of those actions.

• To add a custom action to a deployment project

  1. On the View menu, point to Editor, and click Custom Actions.

  2. Select a folder in the Custom Actions Editor.

  3. On the Action menu, click Add Custom Action.

  4. In the Select item in Project dialog box, select a folder and select the .dll file, .exe file, or project output that contains the custom action.

  5. If the item hasn't previously been added to the deployment project, click the Add File, Add Output, or Component button to add the item as a custom action. This also adds the item to your project.

Note

If you use the Add File, Add Output, or Component button to add an item to the Select item in project dialog box and subsequently cancel the dialog box, the items are still added to the deployment project. If you don't want the items in the deployment project, you can remove them using Solution Explorer.

By default custom actions are run after the actual installation is complete, and those custom actions do not have access to properties used to control installation. However, using the Orca tool, you can cause custom actions to occur during the installation process:

• To have a custom action occur during the installation process

  1. Open the installer package using Orca.exe (provided in the Installer SDK).

  2. Go to the CustomAction table and locate the name of the custom action that you want to occur during the installation (Located under the Action column).

  3. Go to the InstallExecuteSequence table and locate the custom action in the Action column. In the corresponding Sequence column, change the value to a number higher than the event you want the custom action to follow. For example, you would change the custom action to 4010 if you wanted the custom action to occur after the files are installed (which by default is Event number 4000). (It is important to note that the CustomActionData value is not necessary for actions running during the installation process as the condition values are available.)

Conditions can be placed on any custom action using the Condition property. This allows you to run different custom actions based on conditions that exist on a target computer during installation. For example, you might want to run different custom actions, depending on the operating system version on the target computer.

For more information about custom actions, see "Custom Actions" on MSDN.

For more information about working with custom actions, see "Adding and Removing Custom Actions in the Custom Actions Editor" on MSDN.

For more information about passing data from your installer to a custom action, see "Walkthrough: Passing Data to a Custom Action" on MSDN.

There are a number of different elements that would typically be added to your Installer package as custom actions. These include:

• Adding Files

• Modifying IIS Settings

• Adding Pre-defined Installation Components

• Adding Instrumented Assemblies

• Adding Serviced Components

• Pre-compiling ASP.NET applications

We will look at each of these in turn:

Adding Files

In some cases you will want to add files at the end of an installation rather than earlier on. For example, you may create a log file based on information that the user has entered in the user interface and wish to add this to the files deployed on the server. In this case, a custom action would be appropriate.

Modifying IIS Settings

Most IIS settings cannot be set with properties of the Web setup project. These include specifying directory security settings (for anonymous access, basic authentication, or Windows authentication), and specifying custom errors.

You can include custom actions in your Windows Installer file for applying the required settings.

When creating a custom action to set IIS 6.0 settings you have two different methods you can employ. They are:

• Create a script using the IIS ADSI Provider.

• Create a script using the IIS WMI Provider.

The following table compares the architecture and features of the IIS ADSI provider with those of the IIS WMI provider.

Table 3.3: Comparison of IIS ADSI provider with IIS WMI provider

Issue	IIS ADSI provider	IIS WMI provider
Query capabilities	No. ADSI has no provision for queries.	Yes. By querying on metabase key types, the IIS WMI provider returns only the data you need.
Object model and access routes	COM: Scripts and programs.	COM: Scripts, programs, and UI tools; for example, the WMI Object Browser.
Extensible schema	Yes. ADSI provider supports metabase schema extensions.	No. The IIS WMI provider can return existing schema extensions, but cannot extend the metabase schema.
Association or containment of related data	Properties are related to IIS metabase keys by containment. You can use the ADSI container object methods of the IIS Admin Objects to manipulate keys in the IIS metabase. You can create, delete, and move keys by creating, deleting, and moving IIS Admin Objects within container objects. You can also enumerate contained objects, such as virtual directories or servers with container object methods. ADSI supports property inheritance.	Properties are related to IIS metabase keys by containment or by association. Also, in conjunction with other providers, WMI supports associations with managed objects not in the metabase. An association in WMI describes a relationship between classes and is in itself defined by a class. This powerful concept allows management information about an entire system of associated components to be viewed and traversed for tasks such as troubleshooting. Navigating associations to other classes is not limited by containment.

IIS 6.0 provides created scripts which use the WMI provider to perform certain functions, those functions are:

• iisweb.vbs. Script to create and manage Web sites on computers running a member of the Windows Server 2003 family with IIS 6.0.

• iisftp.vbs. Script to create and manage File Transfer Protocol (FTP) sites on computers running a member of the Windows Server 2003 family with IIS 6.0.

• iisvdir.vbs. Script to create, delete, and list Web virtual directories on computers running a member of the Windows Server 2003 family with IIS 6.0.

• iisftpdr.vbs Script to create, delete, and list FTP virtual directories on computers running a member of the Windows Server 2003 family with IIS 6.0.

• iisback.vbs. Script creates and manages backup copies of the IIS configuration (metabase and schema) of a remote or local computer.

• iiscnfg.vbs. Script imports and exports all, or selected, elements of an IIS metabase on a local or remote computer, or it copies the entire IIS configuration (metabase and schema) to another computer.

• iisext.vbs. Script can enable and list applications; add and remove application dependencies; enable, disable, and list Web service extensions; and add, remove, enable, disable, and list individual files.

Adding Pre-defined Installation Components

As mentioned in Chapter 2, installation components are installed using a two step process. First the developer adds the installation component to a project and builds the application. Second you take the project output from the compiled application and add it as a custom action. One important deployment consideration for installation components is that there is a restriction on using custom actions to install assemblies — they cannot run on assemblies that will be installed into the global assembly cache.

This means that all installation components that are added to assemblies should be placed in private assemblies. To achieve this you should create a separate private assembly that contains only installation components. This groups your installation components together and minimizes the number of assemblies that need to be added as custom actions in your setup project. Although this means that an assembly is deployed that is technically not used after installation is complete, it should not cause any problems for your application. In any case, you can then set the assembly to uninstall upon completion.

Another option is to include the installation components into existing assemblies. This is not a recommended method since it leaves unnecessary code in the program (that could be possibly exploited) after installation and may in fact interfere with the existing assembly's functionality.

• To add a pre-defined installation component to a deployment project

  1. Select the setup project in Solution Explorer. On the View menu, point to Editor, and click Custom Actions.

  2. In the Custom Actions Editor, select the Install node. On the Action menu, click Add Custom Action.

  3. In the Select Item in Project dialog box, double-click the Application Folder.

  4. Select the Primary output from project containing the pre-defined installation components, and click OK.

  5. Add any property settings to the custom action as appropriate (for more information see the earlier section on Custom Actions in this chapter).

There are some specific considerations you should bear in mind when adding particular pre-defined installation components.

Adding Event Logging

The EventLog installer deploys the settings you have associated with EventLog components. These settings include:

• Log. The name of the log to read from or write to.

• Source. The name to use when writing to the log.

When you deploy your solution to the production environment, the installer creates the log you specify in the Log property; it also creates the event source that you specify in the Source property. An event source is simply a registry entry that indicates what logs the events. It is often the name of the application or the name of a subcomponent. Because event sources are necessary only when writing to an event log, it is not necessary to use an event log installer when you will be only reading, but not writing, to a log.

When deploying event logs with your application, you should be aware that:

• The EventLog installer can install event logs only on the local computer.

• If you set the Source property for an existing log, but the specified source already exists for that log, the EventLogInstaller deletes the previous source and recreates it. It then assigns the source to the log you are using.

• The name you use as a source for your log cannot be used as a source for other logs on the computer. An attempt to create a duplicated Source value throws an exception. However, a single event log can have many different sources writing to it.

• Event logs are supported only on the following platforms:

  • Windows NT Server 4.0

  • Windows NT Workstation 4.0

  • Windows 2000 family

  • Windows XP Home Edition

  • Windows XP Professional

  • Windows 2003 Server family

• The EventLog installer can only create event sources if it has administrative rights to do so. This should not cause problems if you install event logs and event sources using the EventLogInstaller class with Windows Installer files, because the installation is probably running with the Administrator security account.

For instructions on using the EventLogInstaller class, see "Walkthrough: Installing an Event Log Component" on MSDN.

Adding Message Queues

The MessageQueue installer creates and configures any message queues required by the application, along with settings such as path, journal settings, label, and so on. With message queues an application can send and receive messages, explore existing queues, create and delete queues, and perform a variety of other operations using a simple programming model.

Adding Performance Counter Categories and Counters

The PerformanceCounter installer allows you to install and configure a custom performance counter that your application needs in order to run.

When deploying performance counters with your application, you should be aware that:

• Performance counters are supported only on the following platforms:

  • Windows NT Server 4.0

  • Windows NT Workstation 4.0

  • Windows 2000 family

  • Windows XP Home Edition

  • Windows XP Professional

  • Windows 2003 Server family

• Performance counters need to be created by security accounts with administrative privileges — the easiest way to ensure this is to have your Windows Installer file run by an administrator.

Adding Windows Services

When developers design a project that will install Windows services, they use two types of installation components to install Windows service applications:

• Service Installer. You will use one Service Installer per service contained in your project. You will use this component to specify settings such as start type.

• ServiceProcess Installer. You will use only one ServiceProcess Installer for your Windows service application, regardless of how many services it contains. This component controls installation settings for the executable file itself, such as the security account used to run the service application.

For more information about creating and installing Windows service applications, see "Adding Installers to Your Service Application" on MSDN.

Adding Instrumented Assemblies

As mentioned in Chapter 2, it is the responsibility of the application developer to ensure that instrumented assemblies are installed correctly by using an existing predefined installation class in the application project, or adding an installer class to the project.

Once the application project has been compiled, you can take the appropriate steps to ensure that the instrumented are deployed properly to the target computers:

• To add an instrumented assembly to a deployment project

  1. Select the setup project in Solution Explorer. On the View menu, point to Editor, and select Custom Actions.

  2. In the Custom Actions Editor, select the Install node. On the Action menu, click Add Custom Action.

  3. In the Select Item in Project dialog box, double-click the Application Folder.

  4. Select the Primary output from project containing the appropriate pre-defined installation component or installer class.

  5. Add any property settings to the custom action as appropriate (for more information see the earlier section on Custom Actions in this chapter).

To install successfully, your installer classes must be run by a process with administrative privileges. The easiest way to ensure this happens is to have your installer classes run as custom actions as part of a Windows Installer file — typically, Windows Installer files are run by users who are members of the local administrators group, so required privileges are already in place.

For more information about registering WMI schemas for your instrumented applications with the ManagementInstaller class, see "Registering the Schema for an Instrumented Application" on MSDN.

Adding Serviced Components

Serviced components can be registered dynamically at runtime, but in some cases the process using a serviced component will not have the required privileges for dynamic registration to occur. You can register a serviced component programmatically using an installer class to deploy the serviced component. If you add the installer classes as custom actions to your setup project, then the Windows Installer files for your Web applications are typically run by an administrator, so the required privileges are met.

However, unlike the predefined installation components, you need to write the installation code for your components yourself — for example, you need to override the Install and Uninstall methods for your installer class. With these methods, you use the RegistrationHelper class to register (and unregister) your component. For an example of how to do this, see "Deploying N-Tier Applications with Visual Studio .NET Setup Projects" on GotDotNet.

For an example of how to create and use installer classes, see "Walkthrough: Using a Custom Action to Create a Database During Installation" on MSDN.

For more details about the RegistrationHelper class, see "Understanding Enterprise Services in .NET" on the .NET Framework Community Web site, GotDotNet.

Pre-Compiling ASP.NET Applications

When an ASP.NET application is requested for the first time, two compilations take place:

• Batch compile. When an ASP.NET file (such as .asmx or .aspx) is requested for the first time, ASP.NET performs a "batch compile" on that directory. It compiles all of the code in the ASP.NET files in that directory (but not subdirectories) into MSIL.

• JIT compile. Like any assembly, the first time a method is accessed it is compiled from MSIL to machine code to execute. This occurs on a per method basis.

These two compilations cause a delay in the first request to a Web application. To avoid the delay, you can use a custom action to trigger either or both of these compilations in advance.

For information on how to pre-compile your ASP.NET application during a Windows Installer installation, see "Walkthrough: Using a Custom Action to PreCompile an Assembly During Installation" on MSDN.

Keep in mind that pre-compilation is not just a deployment issue. These compilations occur when the application is first started. This means that whenever the computer is rebooted, IIS is restarted, or the application is unloaded for any reason, both of these compilations occur again the next time the Web application runs. In addition to the Web server being restarted, ASP.NET applications can be unloaded and restarted for a variety of reasons, including:

• ASP.NET can be configured to restart the application periodically by using the restartQueueLimit setting in the processModel section of your configuration files.

• Every time you update any part of your Web application, ASP.NET effectively creates a new application instance for reflecting your changes.

If you choose to pre-compile your application to avoid the initial performance hit for your users, you should create a process (either manually or through script) separately from your deployment steps so that you can execute that process whenever the application is unloaded and needs to be started. For example, you might create a script that is run on a scheduled basis, or you might create a Windows service that monitors the status of your Web server and runs the script in response to your application being unloaded.

Design the User Interface of Windows Installer Files

To define the steps your users must take to install your application, you can specify that a number of predefined user interface dialog boxes be presented during installation to present or gather information. You specify the dialog boxes to be displayed in the User Interface Editor.

• To open the User Interface Editor

  1. In Solution Explorer, select a deployment project.

  2. On the View menu, point to Editor, and click User Interface.

In addition to using the dialog boxes provided with Visual Studio .NET setup and deployment projects "as is," you can customize them. To do this, you need to add a dialog box to your project within Visual Studio .NET 2003, and then modify that dialog box outside of Visual Studio using a tool such as Orca.

This section can be critical as this is where you create the "User Experience." At the same time, it is important when creating these interface dialogs to know what information you need from the user. For example if you need to know a username and password to access a remote server to apply an add-in, or simply want to know what name they want to use for a virtual directory.

As custom actions are run after the actual installation is complete, they do not have access to properties used to control installation. This includes any information you may have gathered from the user. If you need to pass information from the installer to a custom action, you can do so by setting the CustomActionData property for the field that contains the user gathered data.

For more information about each of the dialog boxes you can add to Windows Installer, see "Deployment Dialog Boxes" on MSDN.

For more information about Orca and the other Windows Installer Platform SDK tools, see the Windows Installer Platform SDK section later in this chapter.

Building the Installer File

The Windows Installer file containing your setup logic is created when you build the setup project. The contents of the Windows Installer file, and whether any other files are created, are determined by the settings you choose for the project. You can control these settings in the Property Pages dialog box. (You can view this dialog box by right-clicking your setup project in the Solution Explorer and then clicking Properties).

Choosing How the Files Are Packaged

In most cases, you will choose to package your files in a single setup file (an .msi). This allows you to distribute one file that contains all the files needed for installation. You can specify how files will be packaged within a Windows Installer file. The following options are available:

• In setup file. This allows you to distribute one file that contains all of the files needed for installation. The .msi file also contains the logic needed to complete the installation.

• As loose uncompressed files. All of the files required by your application are placed in the same directory as the .msi file (and subdirectories if your solution includes them). The .msi file itself contains the setup logic necessary to complete the installation and relies on the other files being present at install time. This option can be useful because it allows users to retrieve individual files, perhaps from the installation CD, after installation is complete if those files are damaged or have been deleted from their computers.

• In cabinet file(s). To distribute more manageable file sizes, you should use the cabinet file(s) option. You can choose the maximum file size for your CAB files, which can make distribution of these files easier than for one large installer file. For example, if you plan to distribute files on a series of floppy disks, set the maximum size to 1440 KB (1.44 MB). Your files will be packaged in one or more CAB files in the same directory as the .msi file. Similar to the loose uncompressed files option, the .msi file contains the setup logic necessary to complete the installation and relies on the CAB files being present at install time.

Compressing the Installer File

To manage the size of the installer file, you can set either of two levels of compression:

• Optimized for speed. Files are compressed to install faster, but result in a larger file size.

• Optimize for size. Files are compressed to a smaller size, but may result in a slower build and installation.

These settings apply only to CAB files and to solutions packaged in a single .msi file, and not to loose, uncompressed files. You should consider optimizing for size when users install your solution over a slow dial-up link. For scenarios where size is not an issue, such as when the installer will be distributed on CD or DVD, you might consider optimizing for speed.

Authenticode Signing

The Internet itself cannot provide any guarantee about the identity of the software creator. Nor can it guarantee that any software downloaded was not altered after its creation. Browsers can exhibit a warning message explaining the possible dangers of downloading data of any kind, but they cannot verify that code is what it claims to be. One approach to providing guarantees of the authenticity and integrity of files is attaching digital signatures to those files. A digital signature attached to a file positively identifies the distributor of that file and ensures that the contents of the file were not changed after the signature was created.

Visual Studio .NET deployment tools make it possible for you to sign an installer, a merge module, or a CAB file using Authenticode. You must first obtain a digital certificate in order to use these features of Visual Studio .NET deployment tools. The Signcode.exe utility available in the Microsoft Platform SDK can be used to obtain a digital certificate.

You can set your installer file to be digitally signed by selecting the Authenticode Signature check box in the project properties. You must then provide one of the following:

• Certificate file. Specifies an Authenticode certificate file (.spc) that be used to sign the files.

• Private key file. Specifies a private key file (.pvk) that contains the digital encryption key for the signed files.

• (Optional) Timestamp server URL. Specifies the Web location for a timestamp server used to sign the files.

You can obtain digital certificates from a number of certificate authorities, such as VeriSign or Thawte.

More information about digital certificates is available in the "Platform SDK CryptoAPI Tools Reference."

For more information about using Authenticode signing for your Visual Studio .NET setup projects, see "Deployment and Authenticode Signing" on MSDN.

Other Windows Installer Package Considerations

If you choose to deploy your Framework applications using Windows Installer packages, there are a number of other things to consider before you deploy the application in a production environment.

Documenting Installer Creation

One of the advantages of creating Windows Installer packages is that the uninstall process is generally straightforward - you simply remove the program using Add/ Remove Programs. However in some cases an uninstall will fail using Windows Installer. You should therefore document thoroughly the process used to create your Windows Installer package. This will allow you to create a manual uninstall process that you can test prior to deploying the application.

Administrative Installation

As mentioned in Chapter 2, "Planning the Deployment of .NET Framework-based Applications", you may wish to deploy your application to one or more network servers and have users install the application from that point. Windows Installer can perform an administrative installation of an application to a network installation point. An administrative installation installs a source image of the application onto the network that is similar to a source image on a CD. If the user can choose to run from source when installing over the network, the installer uses most of the application files directly over the network.

Note

For more information on Administrative Installations, see "Administrative Installations" in the Platform SDK.

.NET Framework Bootstrapping

If the Framework is not pre-installed on your target computers, but you are deploying a Framework application, you need to provide a method to install the Framework so that your application can run. One option is to use a launch condition to direct the user to a URL where the Framework can be installed. Another is to bootstrap the Framework to your application. To do this you should:

• Package the redistributable .NET Framework (Dotnetfx.exe) with your application.

• Run a check that determines whether the .NET Framework is installed on the target computer.

• Install the .NET Framework if necessary.

• Install your application.

You cannot include the .NET Framework in your Windows Installer files. Instead, you must develop a separate bootstrapping application that performs the tasks listed above. A sample application (Setup.exe) that performs these tasks can be downloaded from "Microsoft .NET Framework Setup.exe Bootstrapper Sample" on MSDN.

The Setup.exe bootstrapping application sample demonstrates how to create a setup program that verifies whether the .NET Framework is installed. The code checks for a specified version number of the .NET Framework in the HKLM\SOFTWARE \Microsoft\NETFramework\policy\v1 registry key. You can determine which version number should be checked for by examining the properties of the redistributable .NET Framework, Dotnetfx.exe. (For more information about Dotnetfx.exe, see Chapter 2, "Planning the Deployment of .NET Framework-based Applications.") The code performs a comparison between the build number in the registry key and the build number of the .NET Framework being hosted by the application. If there is not a matching build number in the registry key in this location, Setup.exe performs a silent install of the .NET Framework included with your application, and then runs your Windows Installer file.

You can use the sample for your own applications by downloading the precompiled application and simply modifying the Setup.ini file that ships with the sample. Alternatively, you can download the source code for the sample and modify it to meet your specific needs.

For more information about how to work with this sample, see "Redistributing the .NET Framework" on MSDN.

Windows Installer Bootstrapping

If you are not certain whether the target computers have Windows Installer 2.0 available, you should include the Windows Installer bootstrapping application with your .msi file. For your .msi files to install your application successfully, they require that the target computer have the Windows Installer 2.0 service present. A bootstrapping application includes the files needed to install Windows Installer on the target computer, if it is not already installed, before continuing with your application setup. You have two main options for including the bootstrapping application:

• Windows Installer bootstrapping application. A bootstrapping application is included for installation on a Windows-based computer. Your .msi file automatically checks for the Windows Installer service on the target computer and, if it is not present or is an incompatible version, launches the setup of the Windows Installer service prior to installing your application.

  To use this bootstrapper in Visual Studio .NET 2003, go to the deployment project's property page and by default the Windows Installer 2.0 bootstrapper is included

• Web bootstrapping application. A bootstrapping application is included for download over the Web. As in the case of the Windows Installer bootstrapping application, this option launches the setup of the Windows Installer service prior to installing your application, if necessary. The only distinction is that you don't distribute the bootstrapping application with your .msi file, but instead make it available for download from a Web server.

  A Web bootstrapping application has authentication built in, so using this approach rather than CAB files for distributing the bootstrapping application is recommended. If you choose this option, you can use the Settings option to specify the Web location where your application and the Windows Installer executable files are available for download.

  Note

  In some cases, browser content expiration settings can cause the Web bootstrapping application to fail to download. For more information about how to remedy this problem, see Knowledge Base article Q313498, "BUG: Error 1619 When You Install a Package That Uses Web Bootstrapper."

Every installation that attempts to use the Microsoft Windows Installer begins by checking whether the installer is present on the user's computer, and if it is not present, whether the user and computer are ready to install Windows Installer. Two setup applications, InstMsiA.exe and InstMsiW.exe, are available with the Windows Installer SDK that contains all of the logic and functionality to install Windows Installer.

Note

InstMsiA.exe is the American National Standards Institute (ANSI) version of the installer redistributable package, whereas InstMsiW.exe is the Unicode version. The version used by the bootstrapping application depends on the platform to which the Windows Installer service is being installed. InstMsiA.exe is used for Windows 95, Windows 98, and Windows Me, and InstMsiW.exe is used for Windows NT 4.0 and later.

You can include these files with your Windows Installer file to ensure that the correct version of the Windows Installer service is present before your .msi file runs.

However, a bootstrapping application must manage this process. If Windows Installer is not currently installed, the bootstrapping application must query the operating system to determine which version of the InstMsi is required. After the installation of Windows Installer has initiated, the bootstrapping application must handle return codes from the InstMsi application and handle any reboots that are incurred during the Windows Installer installation.

Visual Studio .NET setup projects make this bootstrapping process very simple. All you need to do is set some project properties for your .msi file, and the build process creates the appropriate bootstrapping application. On the property pages for your deployment project, you can specify one of the following bootstrapping application options:

• None. No bootstrapping application will be included.

• Windows Installer Bootstrapper. A bootstrapping application will be included for installation on a Windows-based computer.

• Web Bootstrapper. A bootstrapping application will be included for download over the Web. A bootstrapping application has authentication built in, so using a bootstrapping application rather than .cab files is the preferred method for downloading.

When you build your setup project, the bootstrapping application (Setup.exe and associated .ini file) and the InstMsi file are included in the build output — users need to run Setup.exe rather than the .msi file to install your application.

For more information about the process for installing bootstrapping applications, see "Bootstrapping" in the Platform SDK.

Manipulating Installer Packages

Merge modules (.msm files) and .msi files contain databases that define setup components and logic for your application or component. The Orca database editor is a table-editing tool available in the Windows Installer SDK that you can use to edit your .msi or .msm files. You can use Orca if you need to edit the database tables directly to control setup logic and components for an .msi file or .msm file. Although you can edit any .msi file or .msm file using Orca, you should do so for third-party installers only under instruction from the software vendor.

A more common use for Orca is to create patch creation properties (PCP) files. You can then use MsiMsp.exe to create a Windows Installer patch (MSP) file from your PCP. The MSP patch file can then be applied to your application.

Orca.exe and MsiMsp.exe are both available in the Microsoft Windows Installer SDK. To download the Microsoft Windows Installer SDK, see "Samples, Tools, and Documentation (x86) v1.2 for Windows 2000, Windows 9x, and Windows NT 4.0" on MSDN.

For a complete list of other utilities included in the Windows Installer Platform SDK and for more in-depth information, see the Windows Installer Platform SDK documentation.

Use Orca to Create Nested Installations

In certain circumstances, you might need to launch one .msi file from another. This is known as a nested installation. Windows Installer technology supports nested installs, but the setup and deployment projects do not currently natively support them. However, you can use Orca or another .msi file editing tool to add a nested installation action to the custom action table of your primary .msi file in order to have that .msi file launch another one. Nested installations are performed in the same transactional context as the launching .msi file, so failure in the nested installation rolls back all work carried out by the main .msi file. However, there are some issues with nested installations that make them suitable in certain circumstances only. For example:

• Nested installations cannot share components.

• An administrative installation cannot also contain a nested installation.

• Patching and upgrading may not work with nested installations.

• The installer may not properly calculate the disk space required for the nested installation.

• Integrated progress bars cannot be used with nested installations.

For more information about nested installations, see "Nested Installation Actions" on MSDN.

For step-by-step instructions on creating nested installation, see Knowledge Base article Q306439, "HOWTO: Create a Nested .msi Package."

Automating the Creation of Installers

If you are an ISV, or if you need to deploy a large number of .NET-based applications for your enterprise, you might want to automate the creation of your setup routines. For example, you might want to build your own application for creating setup programs to standardize deployment practices, or you might want to write scripts that create installers for multiple applications. If the other factors described in this chapter bring you to the conclusion that an .msi (or .msm) file is appropriate for your solutions, you can automate the creation of your setups by using the automation interface provided by the Windows Installer, rather than creating your installers using Visual Studio .NET.

For in-depth information about the Windows Installer automation interface, see the "Automation Interface" section of the Platform SDK on MSDN.