Inside Microsoft® Visual Studio® .NET 2003 [Electronic resources] نسخه متنی

Setup for .NET Programs

Suppose you're taking the setup-building capabilities of Visual Studio .NET out for a spin, trying out the various features. You've built a .NET application, added the project output to a setup project, built the solution, and tested the .msi file by installing the project. Everything has installed perfectly, and you were able to run your application. Being the good developer you are, and because you want to be sure your program works in all scenarios, you try installing the same .msi file on a clean computera computer with nothing more than the base operating system installed. When you run the setup project on the clean computer, you're presented with the dialog box shown in Figure 13-9. What went wrong, and why did it work fine on the development computer but not the clean computer? Visual Studio .NET cannot run without the .NET Framework installed, and the clean computer, with only the operating system installed, doesn't have the .NET Framework.

When you add output from a C# or Visual Basic .NET project to the File System editor, Visual Studio .NET automatically adds a condition to the Launch Conditions editor that verifies that the .NET Framework is installed. Because the clean computer doesn't have the .NET Framework installed, the launch condition was not satisfied and an error was displayed to the user to that effect.

To run an .msi file that contains components that use the .NET Framework, you have two options. The option you choose will depend on how you plan on distributing your software. The first option is to let the user click the Yes button in the dialog box shown in Figure 13-9 and then install the .NET Framework manually. This option is best if you're distributing your software on the Internet or using a limited-size medium such as a floppy disk that doesn't have enough room to hold the .NET Framework redistributable files.

If you're shipping your program on a large media format such as a CD, another option is better. You store the .NET Framework redistributable files on the CD, and use a bootstrapping program to install the .NET Framework and then your .msi file. A bootstrap program is a small bit of code that takes care of getting the installation up and running. The bootstrap program makes sure the .NET Framework is installed and then starts installing the .msi file. To install a program, you should run the bootstrap program but not run the .msi file. By default, when you build a setup project, a bootstrap program named Setup.exe is generated and placed in the output folder for your setup project. This bootstrap program only makes sure that the Windows Installer program is installed, and not the .NET Framework. You don't need to redistribute this bootstrap program if you're trying to install the .NET Framework because the setup program for the .NET Framework installs the .msi installer if it isn't on the user's computer, and you can turn off generating this bootstrap file in the setup project Properties dialog box.

When you first add a .NET component to a setup project, a dependency to the merge module dotnetfxredist_x86.msm is added to your project and is marked to be excluded. You might assume that you can include this merge module in your setup project (instead of exclude it) to set up the .NET Framework if needed, but this is not what this merge module does. This merge module contains assemblies that are part of the .NET Frameworksuch as System.XML, System.Web, and so forthand should be on the user's computer if the use has the .NET Framework installed. This merge module doesn't contain files that make up the common language runtime (CLR), so if you were to include this merge module in your setup project, you'd be including many assemblies that the user should already have installed but not everything the user needs to run a .NET program.

To make installing the .NET Framework with your program easier, you can use the Bootstrapper sample, which is included with the samples for this book. This sample, written using Visual C++, performs a couple of steps when it first runs. First, it checks to make sure another instance of the bootstrapping program isn't running because if one is already running, errors can arise if the other instance is started. To ensure that another instance is not running, the bootstrap program creates a mutex; mutexes are shared across process boundaries, so an error is generated if the mutex has already been created by another instance of the bootstrap program. This error condition signals that another instance is running; a message is displayed to the user and then the bootstrap program exits. The second step the bootstrap program performs is to read a file called Setup.ini, which needs to be located in the same folder as the bootstrap executable. This file describes to setup where it can find, among other things, the .NET Framework redistributable file. An example Setup.ini file is shown here:

[Setup]
InstallName=Setup
FrameworkVersionRequired=v1.1
UseLocaleForFindingRedist=1
FrameworkRedistName=DotNetfx
FrameworkInstallPath=FrameworkRedist
MSIFilePath=Setup.msi

All the values in this INI file are optional; if a particular key and value aren't found, the value as shown in this example is used. The meanings of these values are:

InstallName

The name of the product being installed. The value defaults to Setup if a name is not supplied. This string is used to display the name of your program in the user interface of the bootstrap program.

FrameworkVersionRequired

The version of the .NET Framework in use by the program being installed. If a currently installed .NET Framework with the version that matches this string is found, installation of the .NET Framework is skipped. This value can be v1.0 (the letter v must precede the version number, and the trailing 0 is required) or v1.1. v1.0 is the version of the .NET Framework installed with Visual Studio .NET 2002, and v1.1 is the version of the .NET Framework installed with Visual Studio .NET 2003.

FrameworkRedistName

The name of the executable file (without the .exe filename extension) that holds the .NET Framework redistributable file. The name of this executable is always DotNetfx, so in most situations you don't need to specify this value.

UseLocaleForFindingRedist

If this value is 1, the bootstrap program attempts to find and install a localized version of the .NET Framework redistributable from the CD. Up to this point, the .NET Framework has been localized into nine languages: English, French, German, Italian, Japanese, Spanish, Chinese Traditional, Chinese Simplified, and Korean. If a localized version needs to be installed, the bootstrap program retrieves the language used by the operating system and uses this language, or locale, when searching for the redistributable. If this value is 0, the bootstrap program doesn't use the operating system language when searching for the redistributable file. If your program is not localized into different languages, you should distribute the localized version of the .NET Framework that your user customer would use and set this value to 0.

FrameworkInstallPath

The path relative to the bootstrap program where the .NET Framework redistributable file can be found. Suppose you have the bootstrap code in the folder D:\MyProgramSetup and the FrameworkInstallPath value is set to its default value, FrameworkRedist. The bootstrap program will look for the .NET Framework redistributable file in the path C:\MyProgramSetup\ FrameworkRedist\DotNetfx.exe. If the value of UseLocaleForFinding­Redist is set to 1, the language identifier is inserted into this path between the value for FrameworkInstallPath and the FrameworkRedistName value. Table 13-3 shows the language identifiers for the various languages used; if the language is English, for example, the redistributable is searched for at D:\MyProgramSetup\FrameworkRedist\9\DotNetfx.exe. If the redistributable is not found in the path with the language identifier or if a language being used by the operating system is not supported, the path without the language identifier is searched. If all the search options have been exhausted and the redistributable hasn't been found, an error is given and setup exits.

MSIFilePath

The path relative to the bootstrap program where the setup .msi file can be found. If the bootstrap program is in the folder D:\MyProgramSetup and the default value of Setup.msi is used for this key, the path searched is D:\MyProgramSetup\Setup.msi.

Note

Installing the proper language version of the .NET Framework is important because although it might seem that only the program being installed will be affected, your users have to live with the language of the .NET Framework you install unless they uninstall and then install a new version of the language they want to use.

Creating a Setup CD

Today, most computers have a CD burner installed, and you can find blank CDs at your local discount store for well under 50 cents each. The availability of CD burners, cheap media, and the setup development tools available with Visual Studio .NET make distributing your software programs easy. To create a CD with your .msi file on it, you must combine the bootstrap program, the .msi file to install your program, and a few other files to make installation as seamless as possible for your users.

Note

If you intend to place the .NET Framework redistributable on the CD for your program or make it available for download from a non-Microsoft Web site, you must read and agree to the Microsoft .NET Framework SDK end user license agreement (EULA) before redistributing the .NET Framework.

The Windows operating system simplifies installing software on a CD with AutoPlay. When a CD is inserted into the computer's CD drive, Windows examines the root folder of the CD, and if it finds a file called autorun.inf, it reads, parses, and then does the work as described in that file. Here's an example autorun.inf file that you can place in the root folder of a CD to automatically start running the bootstrap program when the CD is inserted into the drive:

[autorun]
open=setup.exe
icon=setup.ico
label=My Setup
shell\launch\command=Setup.exe
shell\launch=&Install this program

The meanings of each entry in this file are:

open

When the CD is inserted into the CD drive, this is the path to a file (without the drive letter) that will be run. If you're using the bootstrap program to install the .NET Framework and your program, you should give the path to the bootstrap program; otherwise, you can specify the relative path to the .msi file.

icon

The path to an icon on the disk (without the drive letter) that's displayed in Windows Explorer for the CD. The path can point to an .ico file or to an executable or DLL file. If the path is to an executable or DLL file, the path should be followed by a comma and then the zero-based index of an icon within the resources of that file.

label

The text to display as a label next to the CD drive in Windows Explorer.

shell\verbname

If the user right-clicks on the CD drive in Windows Explorer, the text following this entry is shown on the shortcut menu. The text verbname is arbitrary and can be any string, as long as it contains only alphanumeric characters. The text following this key name can contain any character, and if the ampersand character is used, the accelerator key follows; use a double ampersand if you want the string to contain the ampersand character.

shell\verbname\command

If the user right-clicks on the CD drive in Windows Explorer and chooses the command specified in the shell\verbname line, the program pointed to by the path specified is run. The verbname string here is also arbitrary, but it should match the name used in the previous line. The autorun.inf file can contain any number of these shell\verbname pairs (including 0 entries), with each item appearing on the CD drive shortcut menu, but each pair of items should use a matching but unique pair.

Once you create your autorun.inf file, you must gather all the files that will be placed on the CD; this requires you to download the .NET redistributable files from Microsoft's Web site. Because the redistributable file is over 20 MB in size, this file (or files, if you intend to offer your users localized versions of the redistributable files) is not included with the samples for this book. Figure 13-10 shows the layout of the CD with the typical components necessary to install your program. This layout (without the .NET Framework redistributable files) can be found among the samples for this book in the folder SetupCD. To build a setup CD, you simply copy your .msi file into this folder, burn its contents to a writable CD, and you're done! You've just created a professional setup for your software.