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   these papers refer to dotnetfx.exe as the setup file that contains the run time elements for the .net framework. if you download the "microsoft .net redistributable package" from msdn you will receive a file named dotnetredist.exe. this file contains dotnetfx.exe. in order to extract dotnetfx.exe, double-click dotnetredist.exe. you will be prompted to save the extracted files on your computer. the extracted file is dotnetfx.exe. use dotnetfx.exe for deployment purposes.

if you choose to use the 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 the 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 the dotnetfx.exe and your use of the dotnetfx.exe is subject to the terms of the end user license agreement contained in the dotnetredist.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

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 cds 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 runtime 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 applications 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 applications 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.