.NET Framework deployment guide for developers

This article provides information for developers who want to install any version of .NET Framework from .NET Framework 4.5 to .NET Framework 4.8 with their apps.

You can download the redistributable packages and language packs for .NET Framework from the download pages:

• .NET Framework 4.8.1
• .NET Framework 4.8
• .NET Framework 4.7.2
• .NET Framework 4.7.1
• .NET Framework 4.7
• .NET Framework 4.6.2
• .NET Framework 4.6.1
• .NET Framework 4.6
• .NET Framework 4.5.2
• .NET Framework 4.5.1
• .NET Framework 4.5

Important notes:

• Versions of .NET Framework from .NET Framework 4.5.1 through .NET Framework 4.8 are in-place updates to .NET Framework 4.5, which means they use the same runtime version, but the assembly versions are updated and include new types and members.

• .NET Framework 4.5 and later versions are built incrementally on .NET Framework 4. When you install .NET Framework 4.5 or later versions on a system that has .NET Framework 4 installed, the version 4 assemblies are replaced with newer versions.

• If you are referencing a Microsoft out-of-band package in your app, the assembly will be included in the app package.

• You must have administrator privileges to install .NET Framework 4.5 or later versions.

• .NET Framework 4.5 is included in Windows 8 and Windows Server 2012, so you don't have to deploy it with your app on those operating systems. Similarly, .NET Framework 4.5.1 is included in Windows 8.1 and Windows Server 2012 R2. .NET Framework 4.5.2 isn't included in any operating systems. .NET Framework 4.6 is included in Windows 10, .NET Framework 4.6.1 is included in Windows 10 November Update, and .NET Framework 4.6.2 is included in Windows 10 Anniversary Update. .NET Framework 4.7 is included in Windows 10 Creators Update, .NET Framework 4.7.1 is included in Windows 10 Fall Creators Update, and .NET Framework 4.7.2 is included in Windows 10 October 2018 Update and Windows 10 April 2018 Update. .NET Framework 4.8 is included in Windows 10 May 2019 Update and all later Windows 10 updates. For a full list of hardware and software requirements, see System Requirements.

• Starting with .NET Framework 4.5, your users can view a list of running .NET Framework apps during setup and close them easily. This may help avoid system restarts caused by .NET Framework installations. See Reducing System Restarts.

• Uninstalling .NET Framework 4.5 or later versions also removes pre-existing .NET Framework 4 files. If you want to go back to .NET Framework 4, you must reinstall it and any updates to it. See Installing the .NET Framework 4.

• The .NET Framework 4.5 redistributable was updated on October 9, 2012 to correct an issue related to an improper timestamp on a digital certificate, which caused the digital signature on files produced and signed by Microsoft to expire prematurely. If you previously installed the .NET Framework 4.5 redistributable package dated August 16, 2012, we recommend that you update your copy with the latest redistributable from the .NET Framework download page. For more information about this issue, see Microsoft Security Advisory 2749655.

For information about how a system administrator can deploy the .NET Framework and its system dependencies across a network, see Deployment Guide for Administrators.

Deployment options for your app

When you're ready to publish your app to a web server or other centralized location so that users can install it, you can choose from several deployment methods. Some of these are provided with Visual Studio. The following table lists the deployment options for your app and specifies the .NET Framework redistributable package that supports each option. In addition to these, you can write a custom setup program for your app; for more information, see the section Chaining the .NET Framework Installation to Your App's Setup.

Redistributable packages

.NET Framework is available in two redistributable packages: web installer (bootstrapper) and offline installer (stand-alone redistributable). All .NET Framework downloads are hosted on the Download .NET Framework page. The following table compares the two packages:

* The offline installer is larger because it contains the components for all the target platforms. When you finish running setup, the Windows operating system caches only the installer that was used. If the offline installer is deleted after the installation, the disk space used is the same as that used by the web installer. If the tool you use (for example, InstallAware or InstallShield) to create your app's setup program provides a setup file folder that is removed after installation, the offline installer can be automatically deleted by placing it into the setup folder.

** If you're using the web installer with custom setup, you can use default language settings based on the user's Multilingual User Interface (MUI) setting, or specify another language pack by using the /LCID option on the command line. See the section Chaining by Using the Default .NET Framework UI for examples.

Deployment methods

Four deployment methods are available:

• You can set a dependency on .NET Framework. You can specify .NET Framework as a prerequisite in your app's installation, using one of these methods:

  • Use ClickOnce deployment (available with Visual Studio)

  • Create an InstallAware project (free edition available for Visual Studio users)

  • Create an InstallShield project (available with Visual Studio)

  • Use the Windows Installer XML (WiX) toolset

• You can ask your users to install .NET Framework manually.

• You can chain (include) the .NET Framework setup process in your app's setup, and decide how you want to handle the .NET Framework installation experience:

  • Use the default UI. Let the .NET Framework installer provide the installation experience.

  • Customize the UI to present a unified installation experience and to monitor the .NET Framework installation progress.

These deployment methods are discussed in detail in the following sections.

Set a dependency on .NET Framework

If you use ClickOnce, InstallAware, InstallShield, or WiX to deploy your app, you can add a dependency on .NET Framework so it can be installed as part of your app.

ClickOnce deployment

ClickOnce deployment is available for projects that are created with Visual Basic and Visual C#, but it is not available for Visual C++.

In Visual Studio, to choose ClickOnce deployment and add a dependency on .NET Framework:

1. Open the app project you want to publish.

2. In Solution Explorer, open the shortcut menu for your project, and then choose Properties.

3. Choose the Publish pane.

4. Choose the Prerequisites button.

5. In the Prerequisites dialog box, make sure that the Create setup program to install prerequisite components check box is selected.

6. In the prerequisites list, locate and select the version of .NET Framework that you've used to build your project.

7. Choose an option to specify the source location for the prerequisites, and then choose OK.

   If you supply a URL for the .NET Framework download location, you can specify either the .NET Framework download page or a site of your own. If you are placing the redistributable package on your own server, it must be the offline installer and not the web installer. You can only link to the web installer on the .NET Framework download page. The URL can also specify a disc on which your own app is being distributed.

8. In the Property Pages dialog box, choose OK.

InstallAware deployment

InstallAware builds Windows app (APPX), Windows Installer (MSI), Native Code (EXE), and App-V (Application Virtualization) packages from a single source. Easily include any version of the .NET Framework in your setup, optionally customizing the installation by editing the default scripts. For example, InstallAware pre-installs certificates on Windows 7, without which .NET Framework 4.7 setup fails. For more information on InstallAware, see the InstallAware for Windows Installer website.

InstallShield deployment

InstallShield builds Windows app packages (MSIX, APPX), Windows Installer packages (MSI), and Native Code (EXE) installers. InstallShield also provides Visual Studio integration. For more information, see the InstallShield website.

Windows Installer XML (WiX) deployment

The Windows Installer XML (WiX) toolset builds Windows installation packages from XML source code. WiX supports a command-line environment that can be integrated into your build processes to build MSI and MSM setup packages. By using WiX, you can specify the .NET Framework as a prerequisite, or create a chainer to fully control the .NET Framework deployment experience. For more information about WiX, see the Windows Installer XML (WiX) toolset website.

Install .NET Framework manually

In some situations, it might be impractical to automatically install .NET Framework with your app. In that case, you can have users install .NET Framework themselves. The redistributable package is available in two packages. In your setup process, provide instructions for how users should locate and install .NET Framework.

Chain the .NET Framework installation to your app's setup

If you're creating a custom setup program for your app, you can chain (include) the .NET Framework setup process in your app's setup process. Chaining provides two UI options for the .NET Framework installation:

• Use the default UI provided by the .NET Framework installer.

• Create a custom UI for the .NET Framework installation for consistency with your app's setup program.

Both methods allow you to use either the web installer or the offline installer. Each package has its advantages:

• If you use the web installer, the .NET Framework setup process will decide which installation package is required, and download and install only that package from the web.

• If you use the offline installer, you can include the complete set of .NET Framework installation packages with your redistribution media so that your users don't have to download any additional files from the web during setup.

Chaining by using the default .NET Framework UI

To silently chain the .NET Framework installation process and let the .NET Framework installer provide the UI, add the following command to your setup program:

<.NET Framework redistributable> /q /norestart /ChainingPackage <PackageName>

For example, if your executable program is Contoso.exe and you want to silently install the .NET Framework 4.5 offline redistributable package, use the command:

dotNetFx45_Full_x86_x64.exe /q /norestart /ChainingPackage Contoso

You can use additional command-line options to customize the installation. For example:

• To provide a way for users to close running .NET Framework apps to minimize system restarts, set passive mode and use the /showrmui option as follows:

  dotNetFx45_Full_x86_x64.exe /norestart /passive /showrmui /ChainingPackage Contoso

  This command allows Restart Manager to display a message box that gives users the opportunity to close .NET Framework apps before installing the .NET Framework.

• If you're using the web installer, you can use the /LCID option to specify a language pack. For example, to chain the .NET Framework 4.5 web installer to your Contoso setup program and install the Japanese language pack, add the following command to your app's setup process:

  dotNetFx45_Full_setup.exe /q /norestart /ChainingPackage Contoso /LCID 1041

  If you omit the /LCID option, setup will install the language pack that matches the user's MUI setting.

  Note

  Different language packs may have different release dates. If the language pack you specify is not available at the download center, setup will install the .NET Framework without the language pack. If the .NET Framework is already installed on the user’s computer, the setup will install only the language pack.

For a complete list of options, see the Command-Line Options section.

For common return codes, see the Return Codes section.

Chaining by using a Custom UI

If you have a custom setup package, you may want to silently launch and track the .NET Framework setup while showing your own view of the setup progress. If this is the case, make sure that your code covers the following:

• Check for .NET Framework hardware and software requirements.

• Detect whether the correct version of the .NET Framework is already installed on the user’s computer.

  Important

  In determining whether the correct version of the .NET Framework is already installed, you should check whether your target version or a later version is installed, not whether your target version is installed. In other words, you should evaluate whether the release key you retrieve from the registry is greater than or equal to the release key of your target version, not whether it equals the release key of your target version.

• Detect whether the language packs are already installed on the user’s computer.

• If you want to control the deployment, silently launch and track the .NET Framework setup process (see How to: Get Progress from the .NET Framework 4.5 Installer).

• If you’re deploying the offline installer, chain the language packs separately.

• Customize deployment by using command-line options. For example, if you’re chaining the .NET Framework web installer, but you want to override the default language pack, use the /LCID option, as described in the previous section.

• Troubleshoot.

Detect .NET Framework

The .NET Framework installer writes registry keys when installation is successful. You can test whether .NET Framework 4.5 or later is installed by checking the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full folder in the registry for a DWORD value named Release. (Note that "NET Framework Setup" doesn't begin with a period.) The existence of this key indicates that .NET Framework 4.5 or a later version has been installed on that computer. The value of Release indicates which version of .NET Framework is installed.

Detect language packs

You can test whether a specific language pack is installed by checking the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full\LCID folder in the registry for a DWORD value named Release. (Note that "NET Framework Setup" doesn't begin with a period.) LCID specifies a locale identifier; see supported languages for a list of these.

For example, to detect whether the full Japanese language pack (LCID=1041) is installed, retrieve the following named value from the registry:

To determine whether the final release version of a language pack is installed for a particular version of .NET Framework from 4.5 through 4.7.2, check the value of the RELEASE key DWORD value described in the previous section, Detecting .NET Framework.

Chaining the language packs to your app setup

.NET Framework provides a set of stand-alone language pack executable files that contain localized resources for specific cultures. The language packs are available from the .NET Framework download pages:

• .NET Framework 4.8.1
• .NET Framework 4.8
• .NET Framework 4.7.2
• .NET Framework 4.7.1
• .NET Framework 4.7
• .NET Framework 4.6.2
• .NET Framework 4.6.1
• .NET Framework 4.6
• .NET Framework 4.5.2
• .NET Framework 4.5.1
• .NET Framework 4.5

Starting with .NET Framework 4.5.1, the package names take the form NDP<version>-KB<number>-x86-x64-AllOS-<culture>.exe, where version is the version number of the .NET Framework, number is a Microsoft Knowledge Base article number, and culture specifies a country/region. An example of one of these packages is NDP452-KB2901907-x86-x64-AllOS-JPN.exe. Package names are listed in the Redistributable Packages section earlier in this article.

To install a language pack with the .NET Framework offline installer, you must chain it to your app's setup. For example, to deploy .NET Framework 4.5.1 offline installer with the Japanese language pack, use the following command:

NDP451-KB2858728-x86-x64-AllOS-JPN.exe /q /norestart /ChainingPackage <ProductName>

You do not have to chain the language packs if you use the web installer; setup will install the language pack that matches the user's MUI setting. If you want to install a different language, you can use the /LCID option to specify a language pack.

For a complete list of command-line options, see the Command-Line Options section.

Troubleshooting

Return codes

The following table lists the most common return codes for the .NET Framework redistributable installer. The return codes are the same for all versions of the installer. For links to detailed information, see the next section.

Download error codes

See the following content:

• Background Intelligent Transfer Service (BITS) error codes

• URL moniker error codes

• WinHttp error codes

Other error codes

See the following content:

• Windows Installer error codes

• Windows Update Agent result codes

Uninstall .NET Framework

Starting with Windows 8, you can uninstall .NET Framework 4.5 or later versions by using Turn Windows features on and off in Control Panel. In older versions of Windows, you can uninstall .NET Framework 4.5 or later versions by using Add or Remove Programs in Control Panel.

Appendix

Command-line options

The following table lists options that you can include when you chain the .NET Framework 4.5 redistributable to your app's setup.

Supported languages

The following table lists .NET Framework language packs that are available for .NET Framework 4.5 and later versions.

See also

• Deployment Guide for Administrators
• System Requirements
• Install the .NET Framework for developers
• Troubleshoot blocked .NET Framework installations and uninstallations
• Reducing System Restarts During .NET Framework 4.5 Installations
• How to: Get Progress from the .NET Framework 4.5 Installer