Using Visual Studio .NET to Redistribute the .NET Framework

Microsoft Corporation

January 2002

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

Note If you choose to use Dotnetfx.exe for distribution with an application created by you, you must have a validly licensed copy of the Microsoft .NET Framework SDK and you agree that any use or distribution of Dotnetfx.exe associated with your Licensed Product as "Licensed Product" is defined in the Microsoft .NET Framework SDK end user license agreement (the "EULA"), is subject to the terms of the EULA. If you do not have a validly licensed copy of the Microsoft .NET Framework SDK or you do not agree to these terms and conditions, you are not authorized to distribute Dotnetfx.exe.

Contents

Introduction
Where to Obtain the .NET Framework Redistributable
Visual Studio .NET Deployment Scenarios
Installing Localized Versions of Dotnetfx.exe
Minimum Configuration Requirements

Introduction

The version 1.0 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, Microsoft® Visual Studio® .NET, 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 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

Download Dotnetfx.exe 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 Windows Component Update 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. Because Dotnetfx.exe is a significant run-time component, you must have administrator privileges in order to install it on a computer. In addition, when you redistribute the .NET Framework using Dotnetfx.exe, we recommend that you perform a silent installation.

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 cannot be included in a Windows Installer setup package created using Visual Studio .NET deployment tools; it must be installed separately.

There are three alternatives when deploying a .NET Framework 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.

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.

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 NetInstall directory on this CD, and then run this setup again."

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.

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. If you want Setup.exe to check for a build number and language version of the .NET Framework, you must specify the language to check for in the settings.ini file. If you do not specify a language for the LanguageDirectory variable, Setup.exe checks for the English language version by default.

The following table lists the available language versions and the culture name to specify in the settings.ini file.

To edit the settings file to check for a language version

1. Open the file settings.ini in a text editor such as Notepad.
2. Find the 'LanguageDirectory= entry. Uncomment the entry and specify the correct language version to check for. For example, if you want Setup.exe to check for the French language version of the .NET Framework, specify LanguageDirectory=fr.
3. Save the settings.ini file.

Installing Localized Versions of Dotnetfx.exe

Dotnetfx.exe has been localized into eight languages. For a complete list of available languages, see the table in the previous section. Download the localized versions of Dotnetfx.exe or the Microsoft Windows Update Web site.

When installing the .NET Framework redistributable package, Dotnetfx.exe, on a computer running the Windows® 98 operating system, you must install the localized version of Dotnetfx.exe that corresponds to the localized version of Windows 98 running on the computer. For example, you must install the German version of Dotnetfx.exe on a computer running the German version of Windows 98. This limitation only applies to Windows 98. You can install any language version of Dotnetfx.exe on any language version of Windows ME, Windows 2000, Windows NT® 4.0, Windows XP, or the Windows Server 2003 family.

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

Caution   If you install Dotnefx.exe on Windows .NET Server Beta 3, you will break the version of the .NET Framework that is installed with the operating system. Windows .NET Server Beta 3 installs version 1.0.3215 of the .NET Framework. If you install a later version of the .NET Framework, version 1.0.3215 will be broken. If you install a later version, you can run and use the later version. However, you will not be able to use version 1.0.3215, even after uninstalling the later version.

Recommended software

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

• MDAC 2.6 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.

Recommended server software

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

• MDAC 2.7 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

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

Recommended hardware