Using Visual Studio .NET 2003 to Redistribute the .NET Framework

  • Article

 

Microsoft Corporation

Updated January 2003

Summary: This article describes how to use Microsoft Visual Studio .NET 2003 to deploy Microsoft .NET Framework applications with Dotnetfx.exe, the .NET Framework redistributable package. (8 printed pages)

Note   If you choose to use the Dotnetfx.exe or redistribute it with an application created by you, you must have a validly licensed copy of the Microsoft .NET Framework SDK version 1.1 (or Visual Studio .NET 2003) and any use or distribution of Dotnetfx.exe is subject to the terms of the end user license agreement you received with the Microsoft .NET Framework SDK version 1.1 (or Visual Studio .NET 2003). If you do not have a validly licensed copy of the Microsoft .NET Framework SDK version 1.1 (or Visual Studio .NET 2003), you are not authorized to use or distribute Dotnetfx.exe.

Contents

Introduction
Where to Obtain the .NET Framework Redistributable Package
Redistributing the .NET Framework Using Visual Studio .NET Deployment
Installing Localized Applications
Minimum Configuration Requirements

Introduction

The version 1.1 release of the Microsoft® .NET Framework provides one redistributable installer that contains the common language runtime and .NET Framework components that are necessary to run .NET Framework applications. The .NET Framework redistributable is available as a stand-alone executable file, Dotnetfx.exe. The .NET Framework requires a license agreement that gives you specific rights to redistribute Dotnetfx.exe. If you have previously installed the Microsoft .NET Framework SDK version 1.1, Microsoft® Visual Studio® .NET 2003, or downloaded Dotnetfx.exe from the Web, you have accepted the license agreement for Dotnetfx.exe. For the terms of the license agreement, see .NET Framework Redistributable EULA.

You can manually launch and install Dotnetfx.exe on a computer, or it can be launched and installed as part of the setup program for a .NET Framework application. Note that administrator privileges are required to install Dotnetfx.exe. If you have previously installed the .NET Framework SDK or Microsoft Visual Studio .NET, you do not need to install Dotnetfx.exe.

This article covers deployment scenarios for Visual Studio .NET 2003 users. For more information about deploying Dotnetfx.exe, see the .NET Framework Deployment Guide. This Web site provides detailed deployment information including a white paper that addresses specific deployment scenarios for .NET Framework SDK users.

There are minimum configuration requirements that must be met in order to install Dotnetfx.exe. For more information about software and hardware requirements and recommendations, see Minimum Configuration Requirements.

Where to Obtain the .NET Framework Redistributable Package

You can download Dotnetfx.exe from the Download Center or from the Microsoft Windows Update Web site.

Alternately, you can get the redistributable package on a product CD or DVD. Dotnetfx.exe is available on the .NET Framework SDK CD in the dotNETRedist directory in the CD's root directory. It is available on the Microsoft Visual Studio .NET Prerequisites CD in the dotNetFramework directory, and on the Microsoft Visual Studio .NET DVD in the \wcu\dotNetFramework directory.

If you need to have users install the .NET Framework from the Internet, do not post the .NET Framework Redistributable Package. Instead, direct users to the Microsoft Windows Update Web Site.

Redistributing the .NET Framework Using Visual Studio .NET Deployment

This section describes some possible scenarios for distributing the .NET Framework redistributable, Dotnetfx.exe, using Visual Studio .NET 2003. Because Dotnetfx.exe is a significant run-time component, you must have administrator privileges in order to install it on a computer.

When you deploy applications created with Visual Studio .NET that depend on the .NET Framework, the .NET Framework must already be present on the target computer. The .NET Framework can be included in a setup executable file created using Visual Studio .NET deployment tools only if you have installed the Visual Studio .NET Framework Bootstrapper Plug-in; otherwise it must be installed separately.

Caution   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.

There are four alternatives when deploying a .NET Framework application:

  • Install the Visual Studio .NET Framework Bootstrapper Plug-in on your development computer and use a Setup project to install the .NET Framework executable file along with your application.
  • Instruct the user to manually install the .NET Framework executable.
  • Use the Setup.exe Bootstrapper sample to install the .NET Framework redistributable package (Dotnetfx.exe) and then launch the Windows Installer package for your application.
  • Network administrators can redistribute Dotnetfx.exe using an electronic software distribution tool. For details, see Distributing Dotnetfx.exe Using an Electronic Software Distribution Tool in the white paper Redistributing the .NET Framework.

Installing the .NET Framework with a Setup Project

Setup projects in Visual Studio .NET 2003 can be used to install the .NET Framework with your application, but only if you have installed the optional Visual Studio .NET Framework Bootstrapper Plug-in on your development computer.

Note   The Visual Studio .NET Framework Bootstrapper Plug-in is available for download from the Download Center.

The Visual Studio .NET Framework Bootstrapper Plug-in modifies the behavior of the Setup project's Bootstrapper property to include the .NET Framework bootstrapper as well as the Windows Installer bootstrapper. The .NET Framework redistributable and the appropriate Language pack are then packaged with your application; a launch condition checks for the correct version of the .NET Framework at install time and if necessary, installs it before installing your application.

Note   The Visual Studio .NET Framework Bootstrapper Plug-in doesn't modify the Web bootstrapper. Setting the Bootstrapper property to Web Bootstrapper will only install the Windows Installer Bootstrapper.

In addition, if your application requires data access, you can install the Microsoft Data Access Components (MDAC) with your setup.

The Visual Studio .NET Framework Bootstrapper Plug-in also supports installing localized versions of the .NET Framework for each of the eight languages supported by Visual Studio .NET. You must install a separate version of the plug-in for each language that you wish to support; these can be downloaded from the same location as the English version. The Localization property of the Setup project determines which version of the framework will be bootstrapped. For more information, see Installing Localized Applications.

To make sure that the plug-in is installed

  1. From the Control Panel, click on Add or Remove Programs.
  2. In the Add or Remove Programs dialog box, check the Currently installed programs list for Microsoft Visual Studio .NET 2003 Bootstrapper Plug-in.

If Microsoft Visual Studio .NET 2003 Bootstrapper Plug-in is not listed, you will need to download and install the Visual Studio .NET Framework Bootstrapper Plug-in from the Download Center.

Note   You can also uninstall the Visual Studio .NET Framework Bootstrapper Plug-in by selecting it from the list and clicking Remove.

To install the .NET Framework with a Setup project

  1. Make sure that the Visual Studio .NET Framework Bootstrapper Plug-in is installed.

  2. Select the Setup project in Solution Explorer. On the Project menu, choose Properties.

  3. Set the Bootstrapper property to Windows Installer Bootstrapper.

    The .NET Framework redistributable will be packaged with the Setup.exe for the Setup project when it is built.

    Note   The .NET Framework launch condition must also be enabled; it is enabled by default for any project that references the .NET Framework. To check for the launch condition, from the View menu, point to Editor and choose Launch Conditions, then look for a launch condition named .Net Framework.

To install MDAC with a Setup project

  1. Make sure that the Visual Studio .NET Framework Bootstrapper Plug-in is installed.

  2. Select the Setup project in Solution Explorer. From the View menu, point to Editor and choose Launch Conditions.

  3. Select the Requirements on Target Machine node. From the Action menu, choose Add Registry Launch Condition.

  4. Select the Search for RegistryEntry1 node. In the Properties window, select the RegKey property and type Software\Microsoft\DataAccess.

  5. Select the Root property and select vsdrrHKLM.

  6. Select the Value property and type FullInstallVer.

  7. Select the Property property and type MDACSEARCH.

  8. In the Launch Conditions Editor, select the Condition1 node. In the Properties window, select the Condition property and select MDACSEARCH>="2.6".

  9. Select the Setup project in Solution Explorer. On the Project menu, choose Properties.

  10. Set the Bootstrapper property to Windows Installer Bootstrapper.

    Both the .NET Framework redistributable and MDAC will be packaged with the Setup.exe for the Setup project when it is built.

Installing the .NET Framework Manually

The .NET Framework redistributable package, Dotnetfx.exe, is a stand-alone executable file that can be run to install the .NET Framework. The redistributable is available from several sources (for details, see Where to Obtain the .NET Framework Redistributable); however, you should not assume that users of your application know where to get it or how to install it. For this reason, you should modify your deployment project to provide instructions to the user.

Installers created using Visual Studio .NET deployment tools include a default launch condition (MsiNetAssemblySupport) that checks for the .NET Framework on the target computer. If it is not found, installation is halted and a dialog box displays the following default message to the user: "This setup requires the .NET Framework. Please install the .NET Framework and run this setup again." You should replace this message with a message that is customized for your application's users.

For example, if your application is being distributed by CD-ROM, your message might read: "This setup requires the .NET Framework. Please install the .NET Framework by running the file Dotnetfx.exe, which can be found in the link below, and then run this setup again."

In addition, the dialog displays a link to the Microsoft Support Web site that contains a downloadable copy of the .NET Framework redistributable file. The link is determined by the InstallUrl property; in many cases you will want to modify the InstallUrl property to point to your own location for the redistributable file. For example, if you are distributing your application on CD-ROM, you should include the redistributable file on the CD and change the InstallUrl property to a relative path.

To customize the launch condition message

  1. In Solution Explorer, select the deployment project.

  2. On the View menu, click Editor, and then click Launch Conditions.

  3. In the Launch Conditions Editor, select the MsiNetAssemblySupport node.

  4. In the Properties window, select Message and replace with your custom message text.

    Note   The default message is automatically translated for localized versions of the installer. If you customize the text, you will need to translate it yourself for any localized versions.

  5. In the Properties window, select InstallUrl and enter the HTTP path, network path, or relative path to the location for the redistributable file.

The .NET Framework requires that MDAC 2.6 or later be installed for any application that includes data access. Like the .NET Framework, MDAC cannot be installed as a part of a deployment project. Microsoft provides MDAC_typ.exe, a stand-alone executable file that can be run to install MDAC. The MDAC redistributable is available from the Universal Data Access Web site, however you should not assume that your application's users know where to get it or how to install it. For this reason, you should modify your deployment project to provide instructions to the user. You can download a sample executable file that encapsulates the MDAC installation with a Windows Installer (MSI) package from Install DCOM and MDAC Through a Windows Installer Package on the Microsoft Product Support Services Web site.

If your application includes data access, you should also add a launch condition to check for MDAC 2.6 or later.

To add a launch condition for MDAC

  1. Select the deployment project in Solution Explorer. From the View menu, point to Editor and choose Launch Conditions.

  2. Select the Requirements on Target Machine node. From the Action menu, choose Add Registry Launch Condition.

  3. Select the Search for RegistryEntry1 node. In the Properties window, select the RegKey property and type Software\Microsoft\DataAccess.

  4. Select the Root property and select vsdrrHKLM.

  5. Select the Value property and type FullInstallVer.

  6. Select the Property property and type MDACSEARCH.

  7. In the Launch Conditions Editor, select the Condition1 node. In the Properties window, select the Condition property and select MDACSEARCH>="2.6".

  8. Select the Message property and type MDAC version 2.6 or later must be installed prior to installing this application. MDAC is available for download from the Universal Data Access Web site.

    Note   You can modify the message text for your particular situation. For example, you could point to a network share where MDAC is located.

Installing the .NET Framework with the Setup.exe Bootstrapper Sample

The Setup.exe Bootstrapper sample is an application that installs the .NET Framework redistributable package and then launches a Windows Installer package (.msi file) for a .NET Framework application. An editable settings file, settings.ini, specifies the locations of the redistributable package and your installer.

For your convenience, you can download a precompiled version of the Setup.exe Bootstrapper sample It is freely redistributable.

When using the Setup.exe Bootstrapper sample with an installer created using Visual Studio .NET deployment tools, you first need to modify the deployment project. A deployment project includes a Windows Installer bootstrapper by default. You can remove this default installer because the .NET Framework redistributable also includes a Windows Installer bootstrapper.

For .NET Framework applications that include data access, you can extend the Setup.exe Bootstrapper sample to silently install the MDAC redistributable, MDAC_typ.exe. You will need to add code that checks for the registry key HKLM\SOFTWARE\Microsoft\DataAccess where the value of FullInstallVer is 2.6 or later. You can download a sample executable file that encapsulates the MDAC installation with a Microsoft Installer (MSI) package from Install DCOM and MDAC Through a Windows Installer Package.

To modify a deployment project for use with the Setup.exe Bootstrapper sample

  1. In Solution Explorer, select the deployment project.
  2. On the Project menu, click Properties.
  3. In the Property Pages dialog box, select the Bootstrapper property and set it to None.

The next step is to build the deployment project and copy the resulting .msi file to a deployment location—for example, a directory on a CD-ROM or a network share. The Setup.exe Bootstrapper sample and the settings file also need to be copied to a deployment location, and the settings file must be modified to reflect the deployment locations.

To edit the settings file to reflect deployment locations

  1. Open the file settings.ini in a text editor such as Notepad.

  2. Find the Msi=mySetup.msi entry and replace the default path with the path to your .msi file. For example, if mySetup.msi is located on the local computer in the same folder as Setup.exe, the path will be Msi=mySetup.msi. If mySetup.msi is located on a network share in a folder named myProjectFolder, an example of the path is Msi=\\myNetworkShare\myProjectFolder\mySetup.msi. If mySetup.msi is located in a folder named myInstallerFiles, on the same CD as Setup.exe, an example path is Msi=myInstallerFiles/mySetup.msi.

  3. Find the FxInstallerPath=c: entry and replace the default path with the correct path to the .NET Framework redistributable package, Dotnetfx.exe. For example, if Dotnetfx.exe is located on the local computer in a folder named myProjectFolder, the path will be FxInstallerPath=c:\myProjectFolder\. If Dotnetfx.exe is located on a network share in a folder named myProjectFolder, an example of the path might be FxInstallerPath=\\myNetworkShare\myProjectFolder\. If Dotnetfx.exe is located in a folder named myExecutables, on the same CD as Setup.exe, an example path is FxInstallerPath=myExecutables/.

  4. Save the settings.ini file.

    The Setup.exe Bootstrapper sample performs a comparison between the build number of the .NET Framework installed on the target computer and the build number of the .NET Framework being hosted by the application to install. If there is not a matching build number, Setup.exe installs the version of the .NET Framework being hosted by the application.

Installing Localized Applications

The .NET Framework redistributable (Dotnetfx.exe) is available in 22 language versions. All versions of dotnetfx.exe are the same programmatically, the only difference between each of the 22 versions is the user interface displayed during installation. For example, when installing a Japanese language version of dotnefx.exe on an English language machine all of the installation dialogs and the end user license agreement (EULA) will be in Japanese, but the code itself isn't localized and all dialogs displayed by the .NET Framework will be in English. Therefore if you wish to see installation dialogs in a specific language, you should install the corresponding version of dotnetfx.exe.

In order to have Japanese dialogs displayed by the .NET Framework version 1.1 you will also have to install a corresponding language pack. A .NET Framework version 1.1 language pack only contains localized resources (such as error messages) but changes nothing programmatically in the .NET Framework version 1.1.

There are 21 language packs available for the .NET Framework version 1.1 and all 21 can be installed on the same machine. However, there isn't an English Language pack due to the fact that dotnetfx.exe already has all error codes and messages in English by default.

In every case possible the localized version of dotnetfx.exe and the matching language pack should be installed on localized machines. This means that you should install the dotnetfx.exe that has been localized into Japanese as well as the Japanese language pack when installing onto a Japanese machine.

Note   When installing a .NET Framework language pack on a computer running the Windows 98 or Windows Me operating system, the system code page and font must support the language pack being installed. There are several options:

  • Install the same language pack as the language of Windows. For example, install the Japanese Language Pack on the Japanese version of Windows 98.

  • Install a localized version of the language pack on a localized version of Windows, in which the system code page is the same for both languages. For example, install the French Language Pack on the German version of Windows98.

  • Install the .NET Framework version 1.1 on any localized version of Windows. If the system code page and font do not support the language of the .NET Framework language pack being installed, dialogs will not display correctly. For example, when installing the Japanese Language Pack on the English version of Windows 98, setup dialogs will not display text correctly.

    This limitation applies only to Windows 98 and Windows Me systems. You can install any .NET Framework language pack on any language version of Windows 2000, Windows NT 4.0, Windows XP, or the Windows Server 2003 family.

To install a Language Pack with a Visual Studio .NET Setup project

  1. Make sure that the correct version of the Visual Studio .NET Framework Bootstrapper Plug-in is installed. For example, if you wish to install a German Language Pack, you must first download and install the German version of the Visual Studio .NET Framework Bootstrapper Plug-in on your development computer.

  2. Select the Setup project in Solution Explorer. On the Project menu, choose Properties.

  3. Set the Localization property to the language version that you wish to install.

  4. Set the Bootstrapper property to Windows Installer Bootstrapper.

    The .NET Framework redistributable and the Language Pack will be packaged with the Setup.exe for the Setup project when it is built.

    Note   The .NET Framework launch condition must also be enabled; it is enabled by default for any project that references the .NET Framework. To check for the launch condition, from the View menu, point to Editor and choose Launch Conditions, then look for a launch condition named .Net Framework.

To include a Language Pack in the bootstrapper sample

  1. Open the file settings.ini in a text editor such as Notepad.
  2. Find the 'LanguagePack= entry. Uncomment the entry that corresponds with Language version to install. For example, if you want to install the French Language Pack, uncomment the line LanguagePack=1036 'French.

Minimum Configuration Requirements

This section describes the minimum configuration requirements for a computer where the .NET Framework redistributable package is to be installed. If the minimum operating system and software requirements are not met, Dotnetfx.exe setup will block the installation of the redistributable package. Specifically, note that you cannot install the .NET Framework redistributable package on a computer running the Microsoft Windows 95 operating system.

Platform and Software Requirements

Minimum requirements

To install Dotnetfx.exe, you must have one of the following operating systems with Microsoft Internet Explorer 5.01 or later installed on your computer:

  • Microsoft Windows 98
  • Microsoft Windows 98 Second Edition
  • Microsoft Windows Millennium Edition (Windows Me)
  • Microsoft Windows NT 4 (Workstation or Server) with Service Pack 6a
  • Microsoft Windows 2000 (Professional, Server, or Advanced Server) with the latest Windows service pack and critical updates available from the Microsoft Security Web site.
  • Microsoft Windows XP (Home or Professional)
  • Microsoft Windows Server 2003 family

Depending on your application requirements, you might also need to install one or more of the following:

  • MDAC 2.7 with Service Pack 1 or later for data access, available from the Universal Data Access Web site.

  • Core WMI for Windows instrumentation, available from the Download Center.

    Note   If the recommended software requirements are not met, setup will not block installation or warn you of their absence.

Depending on your application requirements, you might also need the following server software:

  • MDAC 2.7 with Service Pack 1 for data on the server, available at the Universal Data Access Web site.
  • Internet Information Services (IIS) on the server for Windows 2000, Windows XP (Professional), and Windows Server 2003. This is required for using ASP.NET applications.

Hardware Requirements

Minimum hardware requirements

Scenario CPU Required RAM Required
Client Pentium 90 MHz* 32 MB**
Server Pentium 133 MHz* 128 MB**

* Or the minimum CPU required to run the operating system, whichever is higher.

** Or the minimum RAM required to run the operating system, whichever is higher.

Scenario CPU Recommended RAM Recommended
Client Pentium 90 MHz or faster 96 MB or higher
Server Pentium 133 MHz or faster 256 MB or higher