Troubleshooting Windows Installer Deployments

  • Article

The topics in this section cover various problems that you might encounter when you create deployment projects and deploy applications.

The .NET Framework version required by the Setup project is different than the .NET Framework version targeted by the application

Setup projects have a launch condition that can check for a particular version of the .NET Framework version. However, the version may not be the same as the target .NET Framework that the application uses. For example, your application may target .NET Framework 2.0, but the launch condition in the Setup project may look for and install the .NET Framework 3.5. To change this default behavior, follow these steps:

  1. In Solution Explorer, click the Setup project.

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

  3. Click .NET Framework.

  4. In the Properties window, change the Version property to the version of the .NET Framework that you want the Setup project to check for and install.

Make sure that the Setup.exe program also checks for and installs the correct version of the .NET Framework. For more information, see Prerequisites Dialog Box.

Cannot install .NET Framework 3.5 SP1 language packs for a locale if Visual Studio 2008 is using a different locale

When you select .NET Framework 3.5 SP1 language packs as prerequisites in Setup projects, Visual Studio does not generate a bootstrapper or Setup program to install the language pack for a different locale. For example, if you are using a non-Japanese version of Visual Studio, the Setup project does not include the .NET Framework Japanese language pack.

To work around this error, add a new Command block in the package.xml to call the .NET Framework 3.5 SP1 language packs, and define the appropriate InstallConditions and ExitCodes.

Cannot install language packs if .NET Framework 3.5 SP1 is already installed

If the core .NET Framework 3.5 SP1 is already installed on a computer, the .NET Framework 3.5 SP1 language packs cannot install. For example, if a computer already has .NET Framework 3.5 SP1 installed, you cannot install the .NET Framework 3.5 SP1 Japanese language pack as a prerequisite in a different application installer.

As a workaround, create a bootstrapper package just for the language packs. In the bootstrapper package, add a dependency on .NET Framework 3.5 SP1 so that the language packs install only if the core .NET Framework is already installed. Alternatively, you can install the language packs manually.

Cannot load 64-bit self-registering DLLs  

After you develop and deploy a 64-bit self-registering DLL in Visual Studio 2008, you may see a runtime error when trying to load the DLL. This includes all assemblies created by using the Shared Add-In project template for the 2007 Microsoft Office system. In Microsoft Office InfoPath, the error is "Load Behavior: Not loaded. A runtime error occurred during the loading of the COM Add-in."

As a workaround, do not use the Register property to register the DLL on the end user computer. Instead, manually export the registry keys on the development computer and then include the registry keys in the Setup project.

Note

If your 64-bit DLL is unmanaged code, skip to step 6.

  1. Open a command prompt as administrator.

  2. Browse to a folder that you have write access to.

  3. Run the following command to generate the registry information and replace FilePath with the path of the DLL.

    c:\windows\microsoft.net\framework64\v2.0.50727\regasm.exe /regfile:output.reg /codebase:FilePath

  4. In Solution Explorer, click the Setup project.

  5. On the View menu, point to Editor, and then click Registry.

  6. In the Registry Editor, right-click Registry on Target Machine, and then click Import.

    Note

    If your 64-bit DLL is unmanaged code, you must manually create the registry entries in the registry editor.

  7. Navigate to the folder that contains the output.reg file, and then click Open.

    This step adds all registration information necessary to register this file into the setup project.

  8. In Solution Explorer, click the setup project.

  9. On the View menu, point to Editor, and then click File System.

  10. In the File System Editor, browse to the DLL.

  11. On the View menu, click Properties Window.

  12. Change the Register property to the vsdrpDoNotRegister value.

    This steps disables Visual Studio from gathering self-registration information.

If the registration information for the DLL changes, remove outdated registry keys and repeat this procedure.

Previously excluded files are included again when the solution is re-opened

When you exclude a file from a Setup project, you may see that the file is included again after you close and re-open the solution. This may occur if there are two copies of the same DLL file from two different source locations.

To work around this error, change the Copy Local property on one of the files:

  1. In Solution Explorer, click on the DLL reference that you want to remove.

  2. On the View menu, click Properties Window.

  3. Change the Copy Local property to False.

Setup Projects failed to build with 'Not enough storage is available to complete this operation' error

When you add large files to a Setup project, the following error appears after you try to build the Setup project: "Not enough storage is available to complete this operation" even if the local hard disk has available disk space. There may also be an increase of virtual memory usage during the build process.

To work around this error, add more RAM to the build computer, or try this workaround:

  1. In the project, add a file that has the same name as the large file.

  2. In the project properties page, set to installer to Package as Loose Uncompressed files.

  3. Build.

  4. Copy the full-sized large files to the build location.

Setup project does not update modified files

Even if you configure your Setup project to remove earlier versions of files, Windows Installer does not replace files that have been modified or replaced by the user. For more information, see Neither File Has a Version with File Hash Check.

Cannot install the .NET Framework 3.5 SP1

The prerequisite detection for the .NET Framework 3.5 SP1 is not supported with MSI-only scenarios. Instead, you must configure the Setup.exe bootstrapper to check for and install the .NET Framework 3.5 SP1. For more information, see Prerequisites Dialog Box.

How to create a 64-bit bootstrapper that includes the .NET Framework

Including .NET Framework 3.0 as a prerequisite and installing the Setup.exe bootstrapper on 64-bit computers shows an error message that 64-bit operating systems are not supported.

The .NET Framework 3.5 supports both 32-bit and 64-bit operating systems. If your application targets both 32-bit and 64-bit operating systems, select the .NET Framework 3.5 in the Prerequisites Dialog Box. For more information, see Prerequisites Dialog Box.

How do I install the bootstrapper packages for SQL 2008 and .NET Framework 3.5 SP1?

The bootstrapper packages for SQL 2008 and the .NET Framework 3.5 SP1 can be installer to your development computer by installing the Visual Studio Express Editions. For Visual Studio 2010, the SQL 2008 and the .NET Framework 3.5 SP1 bootstrapper packages are included, and this workaround is not necessary.

Backslash in textbox causes invalid directory or URL exception

If your custom action relies on customers typing a path of an installation folder, you may see a ArgumentException error message. This may be related to an invalid directory or URL.

To prevent this error message, replace the backslash in the Edit1 property and Edit1Value textbox with a space: /name="[TARGETDIR] ". Then, parse the value and create a fully qualified path using the Combine method.

Cannot add a newline (\n) to an error message in a Setup project

If you write an error message in a Setup project, the newline character cannot be added in the Setup project or with Orca.exe. Instead, you can add it by using the Windows Installer API in a post-build action with the following command: "INSERT INTO `Property` (`Property`, `Value`) VALUES 'ERRORMESSAGELINES', 'first\r\nnext\r\nlast')". For more information about using a post-build action, see https://go.microsoft.com/fwlink/?LinkId=150770.

Installer cannot register a .tlb file

If you are using Visual Studio and Windows Vista on your development computer, building a Setup project to register a .tlb file may result in the following error: "Unable to create registration information for file that is named 'filename'. Also, the .tlb file is not registered on the end user computer after you run the .msi installer.

To work around this issue, follow these steps:

  1. Open a Visual Studio Command prompt.

  2. Add the location of regcap.exe to your path. Typically, it is the %PROGRAMFILES%\Microsoft Visual Studio 9.0\Common7\Tools\Deployment folder.

  3. Run the following command: “regcap /I /O filename.reg tlbname.tlb”. Replace filename with the name of a file in a directory where you have write access, and replace tlbname with the name of the .tlb file that you want to register on the end user computer.

  4. In Visual Studio, click the Setup project in Solution Explorer.

  5. On the View menu, point to Editor, and then click Registry.

  6. In Registry Editor, right-click Registry on the Target Machine, and then click Import.

  7. In the Import Registry File dialog box, browse to the filename.reg file and then click Open.

  8. In Solution Explorer, open the Detected Dependencies folder.

  9. In the Properties window, change the Register property to vsdrfDoNotRegister.

Cannot select .NET Framework 2.0 SP1 or .NET Framework 3.0 SP1 in the Prerequisites Dialog Box

The Prerequisites Dialog Box does not show .NET Framework 2.0 SP1 or .NET Framework 3.0 SP1 in the list of applications to install if these are not already installed. These are not available as a stand-alone redistributable file. To install these as prerequisites on end user computers, select .NET Framework 3.5 in the Prerequisites Dialog Box. For more information, see Prerequisites Dialog Box.

Cannot run a 64-bit Setup project with native DLL in a custom action

An x64 Setup project with a native DLL in a custom action may not be able to install your application. To work around this, use Orca.exe to modify the entrypoint for the DLL.

  1. Open your MSI by using Orca.exe.

  2. In the CustomAction table, remove the "@4" characters from the entry in the Target column in the row containing the native DLL.

You can also use a post-build action to make this change. For more information about using a post-build action, see https://go.microsoft.com/fwlink/?LinkId=150770.

Default value in textbox overwrites command-line parameters

If you run the installer by using the \qb flag and pass in command-line parameters to set properties in a user dialog box, these parameters may be overwritten. To prevent the default value of a property from being overwritten by a customer, change the msi file by using Orca.exe.

  1. Set the edit field value on the dialog to its property name. For example, set the Edit1Value property to [EDITB1].

  2. Build the MSI in Visual Studio.

  3. Edit the MSI using ORCA and put the default value of the property in the Property table.

  4. Save the MSI.

You can also use a post-build action to make this change. For more information about using a post-build action, see https://go.microsoft.com/fwlink/?LinkId=150770.

An MFC application is not localized when it is installed on a computer where the locale is not English

When deploying an MFC application by using a Visual Studio deployment project, dependencies for the localized merge modules Mfc_loc_e.msm and Mfc_loc_fe.msm are not detected. The merge modules are included with Visual C++; the default installation location is \Program File\Common\Merge Modules. In order to distribute a localized MFC application, you have to manually add the two merge modules to your deployment project. For more information, see Deployment and Dependencies.

Assembly dependencies were not detected

When a project output group, assembly, or merge module are added to a deployment project, any dependent assemblies are automatically detected and added to the project. If a dependent assembly is loaded at run time by means of code, it cannot be detected by the deployment tools. You should avoid loading assemblies from code, if you can, or manually add the dependent assemblies to your deployment project. For more information, see Deployment and Dependencies.

Cannot find files on a Web server after they are installed

When installing a Web Setup to a Web server, the VirtualDirectory property for the Web Application folder and any Web Custom folders determines where files included in those folders will be installed relative to the Web root. If this property is left blank, the files will be installed in the Web root folder (inetpub\wwwroot). For more information, see VirtualDirectory Property.

How do I install a Web application to the Web server root directory?

By default, when you install a Web application using a Web Setup deployment project, files are installed to a folder that has the same name as the deployment project directly beneath the Web root folder. The VirtualDirectory property of the Web Application folder determines where the files are installed. To install to the Web root directory, change the VirtualDirectory property to null (delete the default value). For more information, see VirtualDirectory Property.

How do I turn off dependency analysis?

Unfortunately, there is no direct way to turn off dependency-analysis searching and resolution. However, there is a work-around: you can clear the Include standard search paths option in the dialog box that comes up when you click the SearchPath property.

There are several additional points to consider:

  • You have to add the files using the Add File command (from the Project menu, select Add, and then File). If you use Add Project Output (from the Project menu, select Add, and then Project Output), dependencies reported from the code project will be included.

  • When you build, you may see one or more Unable to find dependency warnings, but these can be ignored in this case.

  • If you only want to turn off dependency analysis for some files, you can put those files in a merge module project with standard search paths turned off. Then use Add Merge Module (from the Project menu, select Add, and then Add Merge Module) to include the .msm in a regular setup project with standard search paths turned on.

How do I turn off repair for a file that users are expected to modify or delete?

Visual Studio creates advertised shortcuts so that when the program is started it verifies that all of its files exist. To change this behavior and cause it not to repair the file, select the files in the setup project and change the Condition property to NOT REINSTALL so that the file will not get reinstalled on a repair and its Transitive property to TRUE so that the condition is re-evaluated. This will cause the Installer to flash on the screen the first time after the file is deleted, while it verifies that the file should not be reinstalled, but you will not see the installer after that.

How do I debug a custom action/installer class?

You can use one of the following methods:

  • Add a call in your code to System.Diagnostics.Debugger.Launch. This method opens Just-In-Time debugging and enables you to attach a new debugger to your code.

  • Add a call in your code to MessageBox.Show("Debug Me"). When the message box is shown, use Visual Studio to attach to the MessageBox process. Then add breaks (for Visual C# projects) or stops (for Visual Basic projects) in the code.

  • Set your debugging preferences to start %windir%\Microsoft.net\Framework\version\InstallUtil.exe as an external program on the Debug Page of the Project Designer. The name of the custom action assembly is the command line arguments. When you press F5, you hit your breakpoint. InstallUtil.exe will run your custom actions just as MSI does.

Registering assemblies with COM interfaces does not work

This is a known RegAsm bug. If your assembly has a dependency, for example on another class library, RegisterCOM might not work because RegAsm is called to obtain the registration information. Because RegAsm is called in the \obj directory, the dependency is not found, and RegAsm fails without notification. The best workaround is to add the assembly by hand from the \bin directory. Another workaround is to use RegisterSelfReg.

Also, make sure that you manually register using RegAsm/Codebase. If your assembly is not in a shared location, it is not found unless it is in the same directory as the calling code. /Codebase enters the directory into the registry.

How do I troubleshoot Windows Installer installations using log files?

Windows Installer logs its operations while installing programs in a log file. The log file is located in the directory where the .msi file resides.

How do I get a log file for my installation?

There are two ways:

  • Run from the command line with the logging switch.

    misexec /i mysetup.msi /l*v mylog.txt

  • Save the following as a .reg file and load it into your registry.

    REGEDIT4

[HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer]
"Logging"="voicewarmup"
"Debug"=dword:00000007

    Then open your \temp directory and sort on date. The most recent msi*.log file is from the most recent install or uninstall.

How do I install to a subdirectory of a previously installed product?

  1. Assume that the previously installed product, Product 1, is installed and has a file that is named MyFile.txt.

  2. Use ORCA (from the Windows Installer SDK) to view the File table, and find the row that represents MyFile.txt.

  3. Get the value of the Component_ column and then open the Component Table.

  4. In the Component Table, find the row that has the Component_ value in the Component column, and get the ComponentID. Copy this value into the Clipboard. Close ORCA.

  5. In your setup project, open the Launch Conditions Editor and add a Windows Installer Component Search. For the ComponentID property of the new search, paste the ComponentID.

  6. Copy the Property property. It should be something like COMPONENTEXISTS1.

  7. Open the File System Editor and select the Application Folder.

  8. Edit the DefaultLocation property to be something like [COMPONENTEXISTS1]MySubFolder (because the path in COMPONENTEXISTS1 includes a trailing '\').

After step 6 in the previous procedure, you might want to add a Condition to the Launch Conditions Editor to check if the component was found, and to block install and show a message if it was not. The condition would be COMPONENTEXISTS1 (which means it is okay to run the Installer if COMPONENTEXISTS1 is not empty).

How do I install custom Web folders to a non-default port?

To install custom Web folders to a port not designated by default, run your installation from the command line. The command must include the Property property values for each of your Web Custom Folders. Typically, a value would be something like NEWWEBPROPERTY1. You also need to include TARGETPORT for the Web Application Folder.

For example, if your Web server is on Port 20, your command line should look like this:

msiexec /i mywebsetup.msi TARGETPORT=20 NEWWEBPROPERTY1PORT=20

The previous command is for only one Web folder. If you have more than one Web folder, add more PROPERTY=VALUE pairs as specified earlier for each folder to redirect each listed folder's port to the specified port.

You might want to remove the Installation Address dialog box, because if someone changes the port in the user interface during installation, the Custom Web Folders will use the command-line value.

How do I install to the root of a Web site?

To install to the root of a Web site, for example, c:\inetpub\wwwroot, set the VirtualDirectory to an empty string, either in the Web Setup project, or during installation.

How do I install a ServicedComponent into the GAC and configure it in the COM+ catalog?

If you try to install a ServicedComponent into the GAC and configure it in the COM+ catalog, you might receive the following compilation error:

"Unable to build custom action named 'Primary output from RegServer (Active)' because the file's Folder property is set to Global Assembly Cache."

This installation is not supported, because assemblies in the GAC are not always available (committed to the GAC) when the custom actions are run.

The workaround is to put your code into different files and put your custom action code into a file that is not going to the GAC, if you can. Sometimes you cannot distribute the code in this manner.

How do I automatically run my program after installation?

  1. Create a .vbs file containing the following code:

    Set WshShell = CreateObject("WScript.Shell")
WshShell.Run """" & Property("CustomActionData") & """",7,False
Set WshShell = Nothing

  2. Open your setup project and go to the Custom Actions Editor.

  3. Select the Commit node; right-click and add a new Custom Action.

  4. Browse the file system to add the .vbs file that you created in step 1.

  5. Edit the CustomActionData property by adding the following, where YourApp.exe is the name of your startup application file:

    [TARGETDIR]YourApp.exe

  1. In your Setup project's directory, create a new Uninstall.bat file.

  2. In your Setup project, copy the ProductCode property (a value like [12345678-1234-1234-1234-123412341234]).

  3. Edit Uninstall.bat so that it has one line that contains the following, where ProductCode is the value that you copied in step 2:

    Msiexec /x ProductCode

  4. Add Uninstall.bat to your Setup project's application folder.

  5. Right-click Uninstall.bat and select Create Shortcut to create a shortcut.

  6. Put the shortcut in the appropriate Start menu folder in the Setup project.

  7. Rename the shortcut to something like "Uninstall <Application Name>."

Where can I find examples of how to use setup projects?

See Windows Installer Deployment Walkthroughs for examples of how to use setup projects.

How do I plan the deployment of .NET Framework-based applications?

This guide will give you the information that you must have to plan and implement the effective deployment of your .NET Framework-based applications: Deploying .NET Framework-based Applications.

Where can I download the Windows Installer SDK?

You can download the Windows Installer SDK from the Platform SDK Web site:

https://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5&displaylang=en

Where can I get updates and help for Crystal Reports?

Updated software and merge modules can be installed from the "Downloads & Updates" page on the BusinessObjects.com Web site:

https://support.businessobjects.com/fix/downloads_updates.asp

Where can I get a bootstrapper to help install the .NET Framework with my application?

The Microsoft .NET Framework Setup.exe Bootstrapper Sample can be found at this location:

https://www.microsoft.com/downloads/details.aspx?FamilyID=bf253cfd-1efc-4fc5-ba7e-6a6f21403495&displaylang=en

The Visual Studio .NET Framework Bootstrapper Plug-in can be found at this location:

https://workspaces.gotdotnet.com/vsboot

How do I resolve "Unrecoverable Build Error" error messages?

If you are receiving an "Unrecoverable Build Error" error message when you build Setup and Deployment Projects, read this article:

"PRB: 'Unrecoverable Build Error' Error Message When You Build Setup and Deployment Projects" at https://support.microsoft.com/?id=329214.

How do I resolve validation error messages?

If you are receiving error messages such as An error occurred when validating. HRESULT = '80040155' see "PRB: "Unrecoverable Build Error" Error Message When You Build Setup and Deployment Projects" at https://support.microsoft.com/?id=329214 and follow the steps for "Missing Registrations."

How to modify IIS during deployment with custom actions

The article "Modifying Internet Information Services During Deployment with Custom Actions" at https://msdn.microsoft.com/library/default.asp?url=/library/en-us/dv_vstechart/html/vbtchUsingCustomActionsToModifyInternetInformationServerDuringDeployment.asp?frame=true. explains how to fix several problems. This includes the following:

  • How to modify settings for an IIS folder that are not available on a Web Folder in the File System Editor

  • How to deploy a hybrid application that uses both Visual Basic 6 and Visual Basic .NET (or later versions).

  • Changes in deploying Visual Studio .NET (or later) applications compared to Visual Basic 6 applications.

Where can I find information about "No Touch Deployment?"

See "No-Touch Deployment in the .NET Framework" at https://msdn.microsoft.com/library/en-us/dv_vstechart/html/vbtchno-touchdeploymentinnetframework.asp.

How do I deploy ASP.NET applications?

For information about deploying an ASP.NET application using Visual Studio .NET, see Deploying an ASP.NET App Using Visual Studio .NET.

After installation on Windows 2000, the application fails with a warning that MDAC 2.8 is required

Any application that references the System.Data namespace has a dependency on Microsoft Data Access Components (MDAC) version 2.8 or later. In most cases the file is already installed as part of the operating system. On Windows 2000 Service Pack3 and earlier, it may be necessary to install the component with your application. You can do so by adding it to the bootstrapper package and downloading the file from Microsoft during installation. For more information, see Deploying Prerequisites (Visual Studio).

How do I change the permission level for the custom actions?

By default, custom actions run with SYSTEM privileges, but you may find that the custom action requires more privileges in order to complete the task. To change this default behavior, disable the "noimpersonate" flag in the custom action. For more information, see Custom Action In-Script Execution Options.

The following Knowledge Base Articles provide information about Windows Installer Deployment issues:

See Also

Concepts

Deployment and Dependencies

Deployment Alternatives

Reference

VirtualDirectory Property

Other Resources

Deploying Applications and Components

Windows Installer Deployment Walkthroughs