Troubleshooting Windows MSI Installers
UPDATE: I updated this post slightly to address some good criticsm from
by removing the MsiZap section. Note that this post does not blame the
Windows Installer for the few problems we have with ASP.NET MVC
installations. The major culprit tends to be either
devenv /setup or
The point in this post is to provide tools for those who are very careful, know what they are doing, and really want to take a peek at how the installer works. These tools can help provide insight to whether the two culprits I just mentioned really are the issue causing the installation to fail in your particular case. Everything I point out here IS AT YOUR OWN RISK! :)
For the most part, the installations for ASP.NET MVC have been quite stable and we’ve tested the installer at every release and 99% of the problems we’ve run into fall into those two buckets. I did not intend to give the impression that we saved installation testing for the last moment, because that’s just not true. We merely had a last minute requirement change for our installer. RC 2 was a response to that change, not to a bug found. Now back to the post. :)
Having an installer crap out on you when you’re excited to try out a new piece of software is an incredibly frustrating experience. Frustrating both for the user as well as for the product team. Every time I read on Twitter that someone is having trouble installing ASP.NET MVC, a new ulcer throbs in my side.
A big part of the frustration is the lack of control and insight into what’s going wrong. Jacques (no blog), a developer on the ASP.NET team has put together a troubleshooting guide based on his research into what makes installers tick to help alleviate some of this lack of control. While his focus was primarily on the ASP.NET MVC installer, much of this information is useful for all MSI installers.
Windows Installer Log Files
Log files are not automatically generated by an MSI. To generate a log
file, you will need to use
msiexec from a command prompt to install
the MSI, for example
msiexec /i AspNetMVC1-RC2.msi /l*v .\install.log
Alternatively you can enable logging by default by configuring a registry key for this. See this article on enabling Windows Installer Logging or if you are using Windows XP, take a look at this article on the same topic specific to Windows XP. Please note that enabling this feature can have an impact on system performance.
The MSI logs are probably the best place to start when trying to figure out why an installation failed. At the very least you will be able to identify the step in the installer that caused the problem.
For example, one common source of trouble is when a required service is not started such as:
- .NET Optimization Service
- ASP.Net State Service
Visual Studio Log Files
The ASP.NET MVC specific context menus in Visual Studio are installed by
devenv.exe with the
/setup switch. When the installer
executes this command it automatically generates a log file at the
The log file can be consulted for more details in case this step of the installation failed.
Orca is an editor for Windows install packages (MSI files) and is part of the Windows Installer SDK (the Orca MSI is located at %Program Files%\Microsoft SDKs\Windows\v6.0A\bin). While we don’t generally encourage people to edit the ASP.NET MVC installer, for those willing to take matters into their own hands (at your own risk!) Orca can be used to disable some of the steps executed by the installer. When you open the MSI you will see all the tables used by the installer. The feature table is probably the most interesting since it shows everything that will be installed.
Notice that by default, the Level attribute of all the features are set to 1. This means that the feature is enabled to be installed. We have some logic that will disable some of the features based on the information that we gather about the system on which were are installing. For example, the VWDExpress_Feature will be disabled if a user does not have Visual Web Developer installed. Similarly we will disable one of the MvcGacNgenXX_Features depending on whether the underlying OS is a 64-bit or 32-bit version.
Let’s say that you’ve tried to install MVC, but for some reason the
installer fails to create a native image for
NGEN. Using Orca you can disable the MvcGACNgen32_Feature and
MvcGACNgenAll_Feature by deleting these two rows from the MSI and
saving it under a different name. Of course the best thing to do is to
investigate why NGEN is failing in the first place.
Editing the MSI is not really encouraged since it may cause other problems such as failing to uninstall properly.
We automatically GAC and NGEN
System.Web.Mvc.dll during the setup
process. Installing into the GAC (Global Assembly Cache) is a
relatively painless operation. NGEN on the other hand is more prone to
causing the installer to fail.
When installing via double clicknig the MSI, you will see an error message before the installation is rolled back if NGEN fails. The error message itself is not that useful as it will most likely just show a cryptic message and an HRESULT value (You can do a web search for the HRESULT and see whether there are workarounds available). To investigate the failure, take a look at the log generated by the MSI (assuming you had logging turned on when you made the install). Open the log file and search for ExecNetFx (this is the name of the WiX component the installer uses to run NGEN).
ExecNetFx: Microsoft (R) CLR Native Image Generator - Version 2.0.50727.3053 ExecNetFx: Copyright (c) Microsoft Corporation. All rights reserved. ExecNetFx: Installing assembly System.Web.Mvc, Version=126.96.36.199, Culture=neutral, PublicKeyToken=31BF3856AD364E35 ExecNetFx: Catastrophic failure (Exception from HRESULT: 0x8000FFFF (E_UNEXPECTED)) ExecNetFx: Error 0x8007006d: failed to allocate output string ExecNetFx: Error 0xffffffff: Command line returned an error. ExecNetFx: Error 0xffffffff: failed to execute Ngen command: C:\Windows\Microsoft.NET\Framework\v2.0.50727\ngen.exe install "System.Web.Mvc, Version=188.8.131.52, Culture=neutral, PublicKeyToken=31BF3856AD364E35"
The example above is a very difficult problem to troubleshoot, but there are a few things you can try:
Open a command prompt, go to
%WINDIR%\Microsoft.NET\Framework\v2.0.50727and execute the following commands and then try to install MVC again
- ngen ExecuteQueuedItems
- ngen Update
Examine the NGEN log files located in
%WINDIR%\Microsoft.NET\Framework\v2.0.50727. There are two files, ngen.log and ngen_service.log. The logs may contain information about other problems in the system that caused the failure, for example a missing DLL that may cause an update operation to fail when NGEN attempts to update invalid native images.
Make sure that the .NET Runtime Optimization service is running
Windows Event Viewer
The installer executes a number of external tasks during the installation process.
- devenv.exe /installvstemplates: This step is used to register the MVC project templates in Visual Studio. (For Visual Web Developer the executable is called VWDExpress.exe).
- devenv.exe /setup: This step is executed to merge all the metadata in Visual Studio and is used by the MVC packages to register the context menus.
- ngen.exe install: Used to generate native images of the System.Web.Mvc assembly. See this article for more details.
- ngen.exe update: Updates any native images that have become invalid.
You will most likely see multiple warning events such as the example below. Visual Studio will log warning events for unknown attributes it encounters in templates and usually just moves past them. These warnings can be safely ignored.
But you may see other events that may cause the install to fail such as the example below:
Solving this problem is easy enough; restart the Cryptographic Service and run the installer again.
Visual Web Developer Express
A few users have reported that after installing MVC, they don’t see an option to create an MVC Web Application Project in Visual Web Developer. If you run into this problem, try the following:
- Open VWD.
- Go to Tools and select Import and Export Settings.
- Select Reset all settings and click Next to complete the wizard.
Third Party Utilities
A number of users have reported problems during the installation of MVC or when trying to use some of the shortcuts inside Visual Studio. In many cases this was resolved by removing certain add-ins:
- Clone Detective
- Spec# and F#
If you review the MSI logs you will most likely see something like the following:
MSI (s) (5C:70) [13:27:26:106]: Executing op: CustomActionSchedule(Action=VisualStudio_VSSetup_Command,ActionType=3122,Source=C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\devenv.exe,Target=/setup,) MSI (s) (5C:70) [13:28:41:075]: Note: 1: 1722 2: VisualStudio_VSSetup_Command 3: C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\devenv.exe 4: /setup Error 1722. There is a problem with this Windows Installer package. A program run as part of the setup did not finish as expected. Contact your support personnel or package vendor. Action VisualStudio_VSSetup_Command, location: C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\devenv.exe, command: /setup MSI (s) (5C:70) [13:28:42:716]: Product: Microsoft ASP.NET MVC RC 2 -- Error 1722. There is a problem with this Windows Installer package. A program run as part of the setup did not finish as expected. Contact your support personnel or package vendor. Action VisualStudio_VSSetup_Command, location: C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\devenv.exe, command: /setup
If installing MVC fails in this manner, try the following:
- Create a log file, for example, devenv.log.
- Open a Visual Studio command prompt and execute devenv /setup /log devenv.log. Make sure that you have administrator rights since that’s required by the /setup switch.
- Scan the log file and look for any <description> elements that contain errors. This may point to problematic packages that are causing devenv.exe to fail when MVC is trying to configure its context menus.
Another option to try is the following:
- Open a Visual Studio command prompt.
- Start Visual Studio by executing the command devenv /ResetSkipPkgs.
- Close Visual Studio.
- Execute devenv /setup.