Using the Setup.exe Bootstrapper Sample with an Application

  • Article

The operations performed by the Setup.exe Bootstrapper sample are automatic. However, to enable Setup.exe to use your application, you must create a custom Settings.ini file that includes the required information about your application. In addition, it is recommended that you deploy your setup program with a readme file that provides users with the minimum configuration requirements for installing your application and Dotnetfx.exe. The following sections provide detailed information about creating the Settings.ini and readme files:

  • Creating a Settings.ini File

  • Creating a Readme File for the Setup Program

Creating a Settings.ini File

The Setup.exe Bootstrapper sample uses the external file, Settings.ini, to determine the following:

  • The location of Dotnetfx.exe and the host application.

  • The language version of the .NET Framework to check for.

  • The custom strings to use for Setup.exe dialog boxes.

The default location for Settings.ini is in the same folder as Setup.exe. You are responsible for creating a Settings.ini file that enables the Setup.exe Bootstrapper sample to work with your application. You can copy the Settings.ini file provided with the Setup.exe Bootstrapper sample and then edit the file as necessary to specify the correct values for your application.

Specify the Location of Dotnetfx.exe and the Host Application

The Setup.exe Bootstrapper sample requires Dotnetfx.exe and the host .NET Framework application to be in a known location relative to Setup.exe. The Setup.exe Bootstrapper sample uses the external file, Settings.ini, to determine the location of Dotnetfx.exe and the host application. You can copy the Settings.ini file that is provided with the sample and then edit the file to point to the locations of your .NET Framework host application and Dotnetfx.exe.

The following examples of Settings.ini files illustrate how to point to a Windows Installer package for a host .NET Framework application (mySetup.msi) and Dotnetfx.exe in various locations relative to the location of Setup.exe.

In the following example Settings.ini file, mySetup.msi and Dotnetfx.exe are located in the same folder as Setup.exe. An apostrophe " ' " is used to comment out lines that are not customized.

[Bootstrap]
Msi=mySetup.msi
'LanguageDirectory=
ProductName= My Application 
'DialogText=
CaptionText=My Application
ErrorCaptionText= My Application Error
FxInstallerPath=c:\myProjectFolder\

In the following example Settings.ini file, mySetup.msi and Dotnetfx.exe are located on a network share, separate from Setup.exe.

[Bootstrap]
Msi=\\myNetworkShare\myProjectFolder\mySetup.msi
'LanguageDirectory=
ProductName=My Application
'DialogText=
CaptionText=My Application
ErrorCaptionText= My Application Error
FxInstallerPath=\\myNetworkShare\myProjectFolder\

In the following example Settings.ini file, mySetup.msi and Dotnetfx.exe are located on the same computer as Setup.exe, but in different folders.

[Bootstrap]
Msi=c:\myInstallerFiles\mySetup.msi
'LanguageDirectory=
ProductName= My Application
'DialogText=
CaptionText=My Application
ErrorCaptionText= My Application Error
FxInstallerPath=c:\myExecutables\

In the following example Settings.ini file, mySetup.msi and Dotnetfx.exe are located on the same CD as Setup.exe, but in different folders.

[Bootstrap]
Msi=myInstallerFiles/mySetup.msi
'LanguageDirectory=
ProductName= My Application
'DialogText=
CaptionText=My Application
ErrorCaptionText= My Application Error
FxInstallerPath=myExecutables/

Specify the Language Version

If you want Setup.exe to check for a build number and a language version of the .NET Framework, you must specify the culture name of the language to check for in the Settings.ini file. If you do not specify a culture name, Setup.exe checks for the English language version by default.

The following table lists the available language versions and corresponding culture names to specify in the Settings.ini file. Culture names are case-insensitive.

Language

Culture name

Chinese (Simplified)

chs

Chinese (Traditional)

cht

French

fr

German

de

Italian

it

Japanese

ja

Korean

ko

Spanish

es

The following example Settings.ini file instructs Setup.exe to check for the French language version of Dotnetfx.exe.

[Bootstrap]
Msi=mySetup.msi
LanguageDirectory=fr
ProductName= My Application 
'DialogText=
CaptionText=My Application
ErrorCaptionText= My Application Error
FxInstallerPath=c:\myProjectFolder\

Customize Strings for Setup.exe Dialog Boxes

You can edit the following variables in the Settings.ini file to customize strings displayed in Setup.exe dialog boxes.

  • ProductName specifies the name of the .NET Framework application that Setup.exe will install. The product name that you specify is used to customize the text in the dialog box that appears after launching Setup.exe. For example, if you specify My Application as ProductName, the dialog box text reads, "To start My Application Setup, click OK. To quit without installing, click Cancel."

    If you do not customize the CaptionText variable, ProductName is also used to customize the title bar for the dialog box that appears after launching Setup.exe. For example, if you specify My Application as the ProductName, the title bar displays "My Application Setup". If you customize both ProductName and CaptionText, CaptionText is used to customize the title bar text in this dialog box.

    ProductName is also used to customize the title bar text in the success dialog box displayed when the application is finished installing. If you do not customize ProductName, the default text "Application Setup" is displayed.

  • DialogText specifies the custom text to display in the dialog box that is displayed after launching Setup.exe. If you do not customize DialogText, the default text "To start Application Setup, click OK. To quit without installing, click Cancel." is displayed.

  • CaptionText specifies the custom text to display in the title bar of the dialog box that appears after launching Setup.exe. If you do not customize CaptionText, ProductName is displayed. If ProductName is not customized, the default text, "Application Setup", is displayed.

  • ErrorCaptionText specifies the custom text to display in the title bar of Setup.exe error dialog boxes. If you do not customize ErrorCaptionText, the default text "Application Setup Error" is displayed.

Creating a Readme File for the Setup Program

We recommend that you distribute your setup program with a readme file that lists the minimum configuration requirements for the computer on which the setup program can successfully run. At a minimum, list Microsoft Windows 98 or later with Internet Explorer 5.01 or later installed as a requirement prior to installation. You should also list Microsoft Data Access Components (MDAC) version 2.6 or later, noting that it is not required for installation, but is required for .NET Framework applications that include data access. For more information on the minimum configuration requirements for installing Dotnetfx.exe, see Minimum Configuration Requirements.

See Also

Concepts

Creating a Single Setup Project to Install a .NET Framework Application and Dotnetfx.exe

Setup.exe Bootstrapper Sample Operations

Minimum Configuration Requirements for Dotnetfx.exe

Other Resources

Redistributing the .NET Framework