Creating an Installation Package for the Simple Editor

In this section, you will use the Simple Editor solution from Chapter 16 to create a Windows Installer Package using Visual Studio 2005. Of course, you can use any other Windows Forms application you have developed while you follow the steps; you just have to change some of the names used.

Planning the Installation

Before you can start building the installation program, you have to plan what you are going to put in it. There are some questions to be considered first:

• What files are needed for the application? Of course the executable and probably some component assemblies are required. It won't be necessary for you to identify all dependencies of these items because the dependencies will automatically be included. Maybe some other files are needed, too. What about a documentation file, a readme.txt file, a license file, a document template, pictures, and configuration files, among others? You have to know all required files.

  For the Simple Editor that was developed in Chapter 16 an executable is needed, and you will also include the files readme.rtf and license.rtf, and a bitmap from Wrox Press to show in the installation dialogs.

• What directories should be used? Application files should be installed in Program Files\Application name. The Program Files directory is named differently for each language variant of the operating system. Also, the administrator can choose different paths for this application. It is not necessary to know where this directory really is, because there's an API function call to get this directory. With the installer, you can use a special predefined folder to put files in the Program Files directory.

  Important

  It's worth making this point again — under no circumstances should the directories be hard-coded. With international versions these directories are named differently! Even if your application supports just English versions of Windows (which you really shouldn't do), the system administrator could have moved these directories to different drives.

  The Simple Editor will have the executable in the default application directory unless the installing user selects a different path.

• How should the user access the application? You can put a shortcut to the executable in the Start menu, or place an icon on the desktop, for example. If you want to place an icon on the desktop, you should check whether the user is happy with that. With Windows XP, the guideline is to have the desktop as clean as possible.

  The Simple Editor should be accessible from the Start menu.

• What is the distribution media? Do you want to put the installation packages on a CD, floppy disks, or a network share?

• What questions should the user answer? Should he or she accept license information, display a ReadMe file, or enter the path to install? Are some other options required for the installation?

  The default dialogs supplied with the Visual Studio 2005 Installer are ample for the Windows Installer project you create over the remainder of the chapter. You will ask for the directory where the program should be installed (the user may choose a path that is different from the default), show a ReadMe file, and ask the user to accept the license agreement.

Create the Project

Now that you know what should be in the installation package, you can use the Visual Studio 2005 installer to create an installer project and add all files that should be installed. In the following Try It Out, you use the Project Wizard and configure the project.

Try It Out – Creating a Windows Installer Project

1. Open the solution file of the Simple Editor project you created in Chapter 16. You will add the installation project to the existing solution. If you didn't create the solution in Chapter 16 yourself (shame on you!), you'll find it in the downloadable code.

2. Add a Setup Project called SimpleEditorSetup to the solution with the File Add Project New Project menu, as shown in Figure 17-18, and click the OK button.

   
   Figure 17-18

Project Properties

Up to this point, you have only a project file for the setup solution. The files to be installed must be defined. But you also have to configure the project properties. To do this, you have to know what the Packaging and Bootstrapper options mean.

Packaging

MSI is where the installation is started, but you can define how the files that are to be installed are packaged with three options in the dialog shown in Figure 17-19. This dialog opens if you right-click on the SimpleEditorSetup project and select Properties.

Figure 17-19

Look at options in the Package files drop-down list:

• The As loose uncompressed files option stores all program and data files as they are. No compressing takes place.

• The In setup file option merges and compresses all the files into the MSI file. This option can be overridden for single components in the package. If you put all your files into a single MSI file, you have to pay attention that the size of the installation program fits in the target you want to use, for example, CDs or floppy disks. If you have so many files to install that they exceed the capacity of a single floppy, you can try to change the compression option by selecting the Optimized for size option from the Compression drop-down list. If the files still don't fit you can choose the next option for packaging.

• The third way to package files is In cabinet file(s). With this method, the MSI file is used just to load and install the CAB files. With CAB files, it is possible to set file sizes that enable installations on CDs or floppy disks (you can set sizes of 1440 KB for installations from floppy disks).

Prerequisites

You can configure in the same dialog the prerequisites that must be installed before the application can be installed. When you click the Settings button near the Prerequisites URL text box, the Prerequisites dialog pops up, as shown in Figure 17-20. As you can see, the .NET Framework 2.0 is selected by default as a prerequisite. If the client system doesn't have the .NET Framework installed, it will be from the setup program. You can also select other prerequisite options, as shown in the following list:

Figure 17-20

• Windows Installer 2.0: Windows Installer 2.0 is required for installer packages created with Visual Studio 2005. If the target system is Windows XP or Windows Server 2003, the installer is already on the system. With older systems the correct version of the Windows Installer might not be there, so you can select this option to include Windows Installer 2.0 with the installation program.

• Microsoft Visual J# .NET Redistributable Package: If Visual J# assemblies are required for the application, you might select the Microsoft Visual J# .NET Redistributable Package to include with your setup program. Usually, this package is only needed if you develop Visual J# applications. However, it is also possible to use J# assemblies with other programming languages.

• SQL Server 2005 Express Edition: If you need a database on the client system, you can include the SQL Server 2005 Express edition with the setup program. Accessing SQL Server with ADO.NET is covered in Chapter 24.

• Crystal Reports for .NET: Crystal Reports allows you to create graphical reports. You can read more about Crystal Reports in the book Professional Crystal Reports for Visual Studio .NET, second edition by David McAmis (Wiley Publishing, Inc., April 2004).

• Microsoft Data Access Components 2.8: Microsoft Data Access Components (MDAC) includes the OLE DB provider, ODBC drivers, and the Microsoft SQL Server Network Libraries that are used to access databases. MDAC version 8.0 is part of Windows Server 2003. With .NET 2.0, MDAC is no longer needed; if you are using the .NET Data Provider for SQL Server, only the OLEDB and ODBC data providers require MDAC to be installed.

Try It Out – Configuring the Project

1. Change the Prerequisites option in the Property page that you just saw to include Windows Installer 2.0 so that the application can be installed on systems where the Windows Installer 2.0 is not available. Also change the output filename to WroxSimpleEditor.msi, as shown in Figure 17-21. Then click the OK button.

   
   Figure 17-21

2. Set the project properties to the values in the following table.

   Property	Value
   Author	Wrox Press
   Description	Simple Editor to print and edit text files.
   Keywords	Installer, Wrox Press, Simple Editor
   Manufacturer	Wrox Press
   ManufacturerUrl	http://www.wrox.com
   Product Name	Simple Editor
   SupportUrl	http://p2p.wrox.com
   Title	Installation Demo for Simple Editor
   Version	1.0.0

Setup Editors

With a Visual Studio 2005 Setup Project you have six editors available. You can select the editor by opening a deployment project, and selecting the menu View Editor, as shown in Figure 17-22.

Figure 17-22

• The File System Editor is used to add files to the installation package.

• With the Registry Editor, you can create Registry keys for the application.

• The File Types Editor allows you to register specific file extensions for an application.

• With the User Interface Editor you can add and configure dialogs that are shown during installation of the product.

• The Custom Actions Editor allows you to start custom programs during installation and uninstallation.

• With the Launch Conditions Editor, you can specify requirements for your application, for example, that the .NET runtime already has to be in place.

File System Editor

With the File System Editor, you can add files to the installation package and configure the locations where they should be installed. This editor is opened with the menu options View Editor File System. Some of the predefined special folders are automatically opened, as shown in Figure 17-23.

Figure 17-23

• The Application Folder is used to store the executables and libraries. The location is defined as [ProgramFilesFolder]\[Manufacturer]\[ProductName]. On English language systems, [ProgramFilesFolder] is resolved to C:\Program Files. The directories for [Manufacturer] and [ProductName] are defined with the Manufacturer and ProductName project properties.

• If you want to place an icon on the desktop the User's Desktop folder can be used. The default path to this folder is C:\Documents and Settings\username\Desktop or C:\Documents and Settings\All Users\Desktop, depending on whether the installation is done for a single user or for all users.

• The user will usually start a program by starting it from the All Programs menu. The default path is C:\Documents and Settings\username\Start Menu\Programs. You can put a shortcut to the application in this menu. The shortcut should have a name that includes the company and the application name, so that the user can easily identify the application, for example, Microsoft Excel.

Some applications create a submenu where more than one application can be started, for example, Microsoft Visual Studio 2005. According to the Windows Guidelines, many programs do this for the wrong reason, listing programs which are not necessary: you shouldn't put an uninstall program in these menus, because this feature is available from Add/Remove Programs in the Control Panel and should be used from there. A help file should also not be placed in this menu because this should be available directly from the application. Thus, for many applications, it will be enough to place a shortcut to the application directly in the All Programs menu. The goal of these restrictions is to ensure that the Start menu doesn't get cluttered with too many items in it.

A great reference to this information can be found in "Application Specification for Microsoft Windows 2000." You can download this paper at http://msdn.microsoft.com, by following the Partners & Certification Certified for Windows Program links.

There are other folders that you can add by right-clicking and selecting Add Special Folder. Some of these folders include:

• Global Assembly Cache Folder refers to the folder where you can install shared assemblies. The Global Assembly Cache is used for assemblies that should be shared between multiple applications. You can read more about sharing assemblies in Chapter 26.

• User's Personal Data Folder refers to the user's default folder where documents should be stored. C:\Documents and Settings\username\My Documents is the default path. This path is the default directory used by Visual Studio to store projects.

• The shortcuts placed in the User's Send To Menu extend the Send To context menu when a file is selected. With this context menu the user can typically send a file to the target location such as the floppy drive, a mail recipient, or the My Documents folder.

Adding Items to Special Folders

You can choose from a list to add items to a special folder by selecting a folder and choosing the menu Action Add Special Folder, as shown in Figure 17-24.

Figure 17-24

You can select Project Output, Folder, File, or Assembly. Adding the output of a project to a folder automatically adds the generated output files and a .dll or .exe, depending on whether the added project is a component library or an application. Selecting either Project Output or Assembly automatically adds all dependencies (all referenced assemblies) to the folder.

File Properties

If you select the properties of a file in a folder, you can set the following properties. Depending on the file types, some of these properties don't apply, and there are additional properties not listed in the following table.

Property	Description
Condition	A condition can be defined with this property to determine if the selected file should be installed. This can be useful if you want to add this file only for specific operating system versions or if the user must chose some selection in a dialog.
Exclude	Can be set to True if this file should not be installed. This way the file can stay in the project but doesn't install. You can exclude a file if you are sure that it's not a dependency or that it already exists on every system where the application is deployed.
PackageAs	With PackageAs, you can override the default way the file is added to the installer package. For example, if the project configuration says In Setup File, you can change the package configuration with this option to Loosefor a specific file so that this file will not be added to the MSI database file. This is useful, for example, if you want to add a ReadMe file, which the user should read before starting the installation. Obviously, you would not compress this file even if all the others were compressed.
Permanent	Setting this property to True means that the file will stay on the target computer after uninstallation of the product. This can be used for configuration files. You might have already seen this when installing a new version of Microsoft Outlook: if you configure Microsoft Outlook, then uninstall the product and install it again, it's not necessary to configure it again because the configuration from the last install is not deleted.
ReadOnly	This property sets the read only file attribute at installation.
Vital	This property means that this file is essential for the installation of this product. If installation of this file fails, the complete installation is aborted and a rollback occurs.

In the next Try It Out you add files to the installer package.

Try It Out – Add Files to the Installer Package

1. Add the primary output of the Simple Editor project to the installer project using the Project Add Project Output menu options. In the Add Project Output Group dialog, select the Primary Output, as shown in Figure 17-25.

   
   Figure 17-25

   Press the OK button to add the primary output of the SimpleEditor project to the Application folder in the automatically opened File System Editor. In this case, the primary output is SimpleEditor.exe.

2. Additional files to add are a logo, a license, and a ReadMe file. In the File System Editor create a subdirectory named Setup in the Application folder. You can do this by selecting the Application folder, and choosing the menu options Action Add Folder.

   Important

   The Action menu in Visual Studio is available only if you select items in the setup editors. If an item in the Solution Explorer or Class View is selected, the Action menu is not available.

3. Add the files wroxlogo.bmp, wroxsetuplogo.bmp, readme.rtf, and license.rtf to the folder setup by right-clicking on the Setup folder and selecting Add File. These files are available with the code download for this chapter, but you can easily create these files yourself. You can fill the text files with license and ReadMe information. It is not necessary to change the properties of these files. These files will be used in the dialogs of the installation program.

   The bitmap wroxsetuplogo.bmp should have a size of 500 pixels wide and 70 pixels high. The left 420 pixels of the bitmap should only have a background graphic because the text of the installation dialogs will cover this range.

4. Add the file readme.txt to the Application folder. You want this file to be available for the user to read before the installation is started. Set the property PackageAs to vsdpaLoose so that this file will not be compressed into the Installer package. Also set the ReadOnly property to true so that this file cannot be changed.

   The project now includes two readme files, readme.txt and readme.rtf. The file readme.txt can be read by the user installing the application before the installation is started. The file readme.rtf is used to show some information in the installation dialogs.

5. Drag and drop the file demo.wroxtext to the User's Desktop folder. This file should only be installed after asking the user whether he or she really wants to install it. Therefore, set the Condition property of this file to CHECKBOXDEMO. CHECKBOXDEMO is the condition that can be set by the user. The value must be written in uppercase. The file will only be installed if the CHECKBOXDEMO condition is set to true. Later you define a dialog where this property will be set.

   To make the program available from the Start Programs menu, you need a shortcut to the SimpleEditor program.

6. Select the Primary output from SimpleEditor item in the Application folder and open the menu Action Create Shortcut to Primary output from SimpleEditor. Set the Name property of the generated shortcut to Wrox Simple Editor, and drag and drop this shortcut to the User's Programs Menu.

File Types Editor

If your application uses custom file types and you want to register file extensions for files that should start your application when a user double-clicks them, you can use the File Types Editor. This editor can be started with View Editor>File Types. Figure 17-26 shows the File Types Editor with a custom file extension added.

Figure 17-26

With the File Types Editor, you can configure a file extension that should be handled from your application. The file extension has the properties shown in the following table.

Property	Description
Name	Here, you should add a useful name describing the file type. This name is displayed in the File Types Editor and is also written to the Registry. The name should be unique. An example for .doc file types is Word.Document.8. It's not necessary to use a ProgID as in the Word example; simple text like wordhtmlfile as used for the .dochtml file extension can also be used.
Command	With the Command property you can specify the executable that should be started when the user opens a file with this type.
Description	Here you can add a description.
Extensions	This property is for the file extension where your application should be registered. The file extension will be registered in a section of the Registry.
Icon	Specify an icon to display for the file extension.

Create Actions

After creating the file types in the File Types Editor, you can add actions. The default action that is automatically added is Open. You can add additional actions like New and Print or whatever actions your program can do with files. Together with the actions, the Arguments and Verb properties must be defined. the Arguments property specifies the argument that is passed to the program, which is registered for the file extension. For example, %1 means that the filename is passed to the application. the Verb property specifies the action that should occur. With a print action a /print can be added if supported by the application.

In the next Try It Out, you add an action to the Simple Editor installation program. You want to register a file extension so that the Simple Editor application can be used from Windows Explorer to open files with the extension .wroxtext. After this registration you can double-click these files to open them, and the Simple Editor application will start automatically.

Try It Out – Set the File Extension

1. Start the File Types Editor with View Editor File Types. Add a new file type using the menu Action Add File Type with the properties set as shown in the following table. Because you don't want to change the ownership for Notepad of the .txt file extension, use the .wroxtext file extension.

   Property	Value
   (Name)	Wrox.SimpleEditor.Text
   Command	Primary output from SimpleEditor
   Description	Wrox Text Documents
   Extensions	Wroxtext

   You can also set the Icon property to define an icon for the opening of files.

   Leave the properties of the Open action with the default values so that the filename is passed as an application argument.

Launch Condition Editor

With the Launch Condition Editor you can specify some requirements that the target system must have before the installation can take place. You can start the Launch Condition Editor by selecting the menu View Editor Launch Conditions, as shown in Figure 17-27.

Figure 17-27

The editor has two sections to specify the requirements: Search Target Machine and Launch Conditions. In the first section, you can specify what specific file or Registry key to search for, and the second section defines the error message if the search is not successful.

Let's look into some of the launch conditions that you can define using the Action menu:

• The File Launch Condition searches the target system for a file you define before the installation starts.

• The Registry Launch Condition allows you to require a check of Registry keys before the installation starts.

• The Windows Installer Launch Condition makes it possible to search for Windows Installer components that must be present.

• the .NET Framework Launch Condition checks if the .NET Framework is already installed on the target system.

• The Internet Information Services Launch Condition checks for installed Internet Information Services. Adding this launch condition adds a Registry search for a specific Registry key that is defined when Internet Information Services is installed, and adds a condition to check for a specific version.

By default, a .NET Framework Launch Condition is included, and its properties have been set to predefined values: the Message property is set to [VSDNETMSG], which is a predefined error message. If the .NET Framework is not installed, a message informing the user to install the .NET Framework pops up. InstallUrl, by default, is set to http://go.microsoft.com/fwlink/?linkid=9832, so the user can easily start the installation of the .NET Framework.

User Interface Editor

With the User Interface Editor, you can define the dialogs the user sees when configuring the installation. Here, you can inform the user about license agreements and ask for installation paths and other information to configure the application.

In the next Try It Out, you start the User Interface Editor, which will be used to configure the dialogs that are shown when the application is installed.

Try It Out – Start the User Interface Editor

1. Start the User Interface Editor by selecting View Editor User Interface. You use the User Interface Editor to set properties for predefined dialog boxes. Figure 17-28 shows the automatically generated dialogs and two installation modes that you should see.

   
   Figure 17-28

Install and Administrative Install

As you can see in Figure 17-28, there are two installation modes: Install and Administrative Install. The Install mode is typically used to install the application on a target system. With an Administrative Install you can install an image of the application on a network share. Afterward a user can install the application from the network.

Default Dialogs

Both installation modes have three sequences where dialogs can be shown: Start, Progress, and End. Let's look at the default dialogs:

• The Welcome dialog displays a welcome message to the user. You can replace the default welcome text with your own message. The user can only cancel the installation or press the next button.

• With the second dialog, Installation Folder, the user can choose the folder where the application should be installed. If you add custom dialogs (you look at this in a moment), you have to add them before this one.

• The Confirm Installation dialog is the last dialog before the installation starts.

• The Progress dialog displays a progress control so that the user can see the progress of the installation.

• When installation is finished, the Finished dialog shows up.

The default dialogs will show up automatically at installation time, even if you never opened the User Interface Editor in the solution. But you should configure these dialogs so that useful messages for your application are displayed.

In the next Try It Out, you configure the default dialogs that are shown when the application is installed. Here, the Administrative Install path will be ignored; only the typical installation path is configured.

Try It Out – Configuring the Default Dialogs

1. Select the Welcome dialog. In the Properties window, you can see three properties that can be changed for this dialog: BannerBitmap, CopyrightWarning, and WelcomeText. Select the BannerBitmap property by pressing (Browse...) in the combo box, and select the wroxsetuplogo.bmp file in the folder Application Folder\Setup. The bitmap stored in this file will show up on top of this dialog.

   The default text for the property CopyrightWarning says:

   WARNING: This computer program is protected by copyright law and international treaties. Unauthorized duplication or distribution of this program, or any portion of it, may result in severe civil or criminal penalties, and will be prosecuted to the maximum extent possible under the law.

   This text will show up in the Welcome dialog, too. Change this text if you want a stronger warning. the WelcomeText property defines more text that is displayed in the dialog. Its default value is:

   The installer will guide you through the steps required to install [ProductName] on your computer.

   You can change this text, too. The string [ProductName] will be automatically replaced with the property ProductName that you defined in the properties of the project.

2. Select the Installation Folder dialog. This dialog has just two properties: BannerBitmap and InstallAllUsersVisible. The property InstallAllUsersVisible has a default value of true. If this value is set to false, the application can only be installed for the user that is logged on while the installation is running. Change the value of BannerBitmap to the wroxsetuplogo.bmp file as you did with the Welcome dialog. As each dialog can display a bitmap with this property, change the BannerBitmap property with all the other dialogs too.

Additional Dialogs

You cannot design a custom dialog and add it to the installation sequence with the Visual Studio installer. A more sophisticated tool such as InstallShield or Wise for Windows is required to do this — but with the Visual Studio installer, you can add and customize many of the predefined dialogs in the Add Dialog screen.

Selecting the Start sequence in the User Interface Editor and choosing the menu options Action Add Dialog, causes the Add Dialog dialog to be displayed (see Figure 17-29). All these dialogs are configurable.

Figure 17-29

There are dialogs in which two, three, or four radio buttons appear, check box dialogs that show up to four check boxes, and text box dialogs that show up to four text boxes. You can configure these dialogs by setting their properties.

Here's a quick overview of some of the dialogs:

• The Customer Information dialog asks users for their name and company, and the product's serial number. If you don't provide a serial number with the product, you can hide the serial number text box by setting the ShowSerialNumber property to false.

• With the License Agreement dialog, users can accept a license before the installation starts. A license file is defined with the LicenseFile property.

• In the Register User dialog, users can press a Register Now button to launch a program defined with the Executable property. The custom program can send the data to an FTP server, or it can transfer the data by e-mail.

• The Splash dialog just displays a splash screen before the installation starts with a bitmap specified by the SplashBitmap property.

With the next Try It Out, you add some additional dialogs such as Read Me, License Agreement, and a Checkboxes dialog.

Try It Out – Adding Other Dialogs

1. Add a Read Me, a License Agreement, and a Checkboxes (A) dialog to the Start sequence with the menu options Action Add Dialog. Define the order in the start sequence by dragging and dropping in this way:

   Welcome – Read Me – License Agreement – Checkboxes (A) – Installation Folder – Confirm Installation.

2. Configure the BannerBitmap property for all these dialogs as you did earlier. For the Read Me dialog, set the ReadmeFile property to readme.rtf, the file you added earlier to Application Folder\Setup.

3. For the License Agreement dialog, set the LicenseFile property to license.rtf.

4. The Checkboxes (A) dialog should be used to ask users if the file demo.wroxtext (which you have put into the user's Desktop folder) should be installed or not. Change the properties of this dialog according to the following table.

   Property	Values
   BannerText	Optional Files
   BodyText	Installation of optional files
   Checkbox1Label	Do you want a demo file put on to the desktop?
   Checkbox1Property	CHECKBOXDEMO
   Checkbox2Visible	False
   Checkbox3Visible	False
   Checkbox4Visible	False

The Checkbox1Property property is set to the same value as the Condition property of the file demo. wroxtext — you set this Condition value earlier when you added the file to the package using the File System Editor. If the user checks this check box, the value of CHECKBOXDEMO will be true, and the file will be installed; if the check box is not checked, the value will be false, and the file will not be installed.

The CheckboxXVisible property of the other check boxes is set to false, because you need only a single check box.