wixwindows-installerinstallshieldadvanced-installer

How do I avoid triggering MSI self-repair with my WiX / MSI package?

How do I avoid triggering self-repair from my WiX generated MSI package?

This is a Q/A-style question with an answer that just list a few things not to do in your MSI file to avoid the most common causes of repeating self-repair.

Solution

  • Self-Repair, Simple & Short Explanation: Why does the MSI installer reconfigure if I delete a file?

    General WiX / MSI Advice: This self-repair piece was split from the original answer on general MSI problems: How do I avoid common design flaws in my WiX / MSI deployment solution?

    Short Summary

    I keep trying to write about repeating MSI self-repair for developers, but end up with too much detail. Here is my last attempt: concrete design advice for what not to do in your WiX / MSI file. Other deployment specialists, please extend the "pitfall list" below.

    The earlier answers I wrote turned out to be developer relevant, but not developer friendly:

    I think there is time for yet another perspective on self-repair. Now I can finally write what I intended all along: the developer's view of self-repair - some of the pitfalls to avoid for developers who do their own setup development work - often using the WiX framework. Just a short, concrete list of things not to do in your MSI package.

    MSI / WiX design pitfalls causing self-repair issues

    This is a rough first-draft. These bullet points will be fleshed out when time allows.

    1. You mess up the installation of shared runtimes. You don't use merge modules to deploy globally registered, and/or shared runtime files. Rather you install your own copies of the files and register them system-wide. This is particularly bad for COM files, but applies also to other types of files. Conflicting applications will try to put their state back, and "self-repair fighting" results on every alternate application launch.

    2. You run into the empty folder self-repair peculiarity. You create an empty component with a directory key path without adding a CreateFolder entry. This causes an endless loop where MSI removes the folder and then triggers self-repair to put it back. There might be protection in WiX against this at this point.

    3. Incorrect component reference counting. You create a suite of packages yourself that install a file with the same name to the same location on disk from different MSI setups using different component GUIDs. This will most likely trigger self-repair as the packages "fight" to put its version of the file in place. There are several "fixes" for this such as designing a merge module, using a WiX include file, installing the file without reference counting (blank component guid) - (more details will be added soon).

    4. Erroneous per-user file installation. You install files to the user-profile and set a file key path instead of a registry key path in HKCU (required by MSI design guidelines). This frequently cause regular users to experience repeating self-repair that never succeeds due to missing disk permissions. The key files are not "seen" by the regular user because there is no read permission where the key file resides (another user's user-profile). Here is a color illustration. And in addition to a link, in image form as well:

      Profile Issue

    5. Erroneous disk / registry custom permissioning. This problem is different, but similar to the previous issue. You apply custom file, folder and registry permissions during installation that removes read access to installation locations for regular users. Regular users will see repeating self-repair that never succeeds. This can happen to "per machine" file locations as well, not just user-profile paths (like the previous issue). I hear rumors that some have seen this in particular for write protected ini files as well.

    6. You leave ref-counting enabled for temp files. For some crazy reason you decide to install a file to the tmp folder or another folder that might be cleaned up at any point. Perhaps you intend to run the file from a custom action or something. In either case you install it via a component with a component guid and a key path set, and when the file is "cleaned" from disk, your MSI file will try to put it back. This repeats every time the file is "cleaned". Since the install location is likely a per-user location, other users might not "see" the file from their login, and they experience immediate, repeating self-repair whereas you only see it when the file is "cleaned".

    7. Malware - real and false positives. You install an unusual binary without running it through a basic virus / malware screening. It is as important to check for actual malware as it is to check for false positives (one malware scanning service to use is http://www.virustotal.com - almost 70 different scanners - pay special attention to the major vendors - obviously). So you ignore the malware check, and after deployment your product suffers false positives from several anti-virus vendors and self-repair will run in vain trying to put back the file only to have it "quarantined" again. Your customers blame you (funny how a false positive can be harder to get rid of than real malware?). The result is of course equally bad if you actually install a real virus or malware instead. The result is exactly the same - self-repair keeps running in vain. On the other hand, if the binary was infected after installation, then self-repair should serve its purpose and run once to put the clean file back in place. The major problem is that fixing a false positive is actually harder than dealing with malware (malware is of course worse for the customer if it causes data loss, but it is understood that this is out of your hands as software provider). With malware you simply tell your client to rebuild their PCs and reinstall your software, but with a false-positive you need to do something to whitelist your binary - often with several security software vendors. How do you deal with this process? As malware seems to become worse and worse and security is attempted tightened in any way possible, false positives are likely to become a major deployment problem - even more so than now. A lot of time can be wasted trying to get your binary whitelisted. And the obvious, but let's just say it out loud: don't brave this task on your own as a deployment person - this whitelisting is a huge task that requires management involvement. The problem affects everything for a software vendor: sales, development, marketing and support. As security software become more advanced and "smart" - they may start to quarantine the whole cached MSI on the system that is found in %SystemRoot%\Installer (used for maintenance installs, repair and uninstall). When this happens no self-repair will be possible - and also no uninstall (!) - unless you have access to the exact, original MSI that was used to install with. In these cases I suppose you could try some of the options listed here to get your MSI with malware or false-positives uninstalled: Why does MSI require the original .msi file to proceed with an uninstall? or section 12 here: Uninstalling an MSI file from the command line without using msiexec.

    8. You install desktop files likely to be deleted by the user. This is a "fringe case" requiring that you have also erroneously set the key path for the installing component to a disk key path (rather than the correct HKCU path). Most of the time you put shortcuts on the desktop, and this is fine. However, if you install a data file of some sort that the user then deletes, you could see it put back by self repair when your application is launched via an advertised shortcut, or even if a advertised COM object is instantiated or a particular file type is launched.

    9. You install advertised shortcuts to the "Startup" folder. Don't install advertised shortcuts to the "Startup" folder. It can trigger self-repair to run on every system startup without any user interaction taking place at all. Deleting the shortcut has been reported to also trigger self-repair. This is something I have never actually seen, but it makes sense.

    10. You use a HKCU key path (or HKLM for that matter) that your application changes. Any setting you write from your MSI to the registry should generally not be modified, or worse, deleted by your application's operation. Self-repair will likely result. Only write data that the application just reads. Your application itself should always populate all default settings to HKCU, and your setup should never interfere with them. The same goes for userprofile files. They should be copied for each user from a per-machine template location. The overall moral of the story: deploy only per-machine files and settings (HKLM). Everything else should be initialized by the application: Why is it a good idea to limit deployment of files to the user-profile or HKCU when using MSI?.

    11. Your setup writes to registry keys that are periodically overwritten by group policy. I believe I first saw this problem in relation to some IE proxy settings keys in HKCU being set using an MSI. Using an MSI to just set a few registry keys is always a bad idea for a lot of reasons. Please see this serverfault.com answer for a list of several problems: MSI package for reg deployment (recommended quick read, though it is most relevant for system administrators, but important to know about for developers). I am having trouble reproducing this problem since self-repair is triggered when key paths are missing (generally not just changed or modified). Perhaps group policy actually removed the HKCU values that were added by the MSI? We did see the problem, so this is probably what happened. The overall message: never use an MSI to just set a few registry keys, particularly if they are in HKCU. Use group policy, logon scripts, VB Scripts, PowerShell or other, more reliable measures such as having applications do it on launch (once per user).

    12. You register a particular file / MIME association or command verb in your MSI file. Most self-repair seems to be triggered by COM registry interference between products that triggers self-repair on COM object instantiation, or the invocation of an advertised shortcut. However, you can also trigger self-repair via file / MIME associations and command verbs. In particular file associations could be registered by other applications / MSI files on the system, and this could trigger very persistent self-repair as each application tries to "steal back" the file association. Use these features sparingly in your MSI - and make sure the file associations you register really are unique. Never set a "common" file association in your MSI setup (for example jpg).

    13. The same MSI is installed twice (or more) by mistake. This sounds strange, but it is possible in several ways actually. Self-repair might not be your biggest problem if this happens, you will see other problems too:

      • You forget to generate a new package GUID for your rebuilt MSI. Windows Installer then treats the two different MSI files as the same file "by definition". I believe I have seen self-repair in these cases, but you will be facing a plethora of other problems as well, all equally weird. Always auto-generate the package GUID. There is no reason for any two MSI files to have the same package GUID (unless you are testing something incredibly obscure in the Windows Installer Engine). While fully aware of the problem of duplicate GUIDs, it still happened to me many years ago using Installshield during some very hectic development. I still wonder how it actually happened - but it did. Perhaps it was an unknown bug in the tool?
      • A failed major upgrade can leave two versions of your setup installed at the same time. You see two entries in add/remove programs. Self-repair problems are possible in these cases, but so are a plethora of other problems. In my experience this problem is serious, but not as bad as using the same package GUID for two MSI files (previous bullet point).
      • I am sure there are several other ways the same product can end up being installed multiple times. Perhaps failed multi-instance transforms can cause the problem as well? I dislike that particular concept so I haven't really tried.

    Some general "runner-up" self-repair related issues:

    Self-repair related answers (links for safekeeping):