Ad-Hoc: How do I avoid common design flaws in my WiX / MSI deployment solution?
- a very messy and less-than-ideal ad-hoc summary of common problems found in MSI files. Not great. Better than nothing? The stuff that is not in the books (too messy).
Important Topic: How do I avoid distributing sensitive information in my MSI by accident?
Need For Speed: WiX Quick Start Short Version
WiX & MSI:
MSI is the accepted corporate application standard. It has some major corporate benefits (and the short, concise version
) compared to legacy deployment
techniques. WiX is the new open source way to create MSI files.
Other Tools:
Hello World & Hello WiX:
Video Samples:
More Sample Code:
WiX Quick Start: Here are some of the best sample code links that I have found:
And finally:
Debugging: Always check all event logs, application logs and MSI logs - if available. Just to mention it. And use any debugging tool available and google the exact error message before doing anything else.
And check for any obviously missing runtimes. For example: .Net
, .Net Core
, Java
, Silverlight
, Direct X
, VC++ Runtime
, MS-XML
(legacy), etc...
.
Custom Action Debugging:
MSI logging:
Event Viewer:
- Hold down Windows Key, tap R, type
eventvwr.msc
and press Enter.
- Go to
Windows Logs => Applications
. Look for MsiInstaller events
.
- Check the other logs too (
Security
, System
, Configuration
).
General Debugging:
Debugging Tools:
Error Code: Looking up error codes and exception messages.
A Deployment Mnemonic: A general mnemonic to think about deployment problems: What is locking
(in use, malware), what is blocking
(permissions, anti-virus, security tools), what is corrupt
(disk, malware, configs, encryption) what are unexpected system states
(disk space, time & date settings, language, licensing, windows patch state, path too long, PendingFileRenames, etc...), what are incompatible products
(things that can't co-exist), what is unreachable or misconfigured
(what points to erroneous locations and resources: network server names, disk paths, URLs, databases, services, UAT environments, PROD environments, etc...) and last but not least: what is missing
(runtime, resource image, settings file, etc...)?
NOTE: Always first (step 8 below): Google exact error message
.
Express Failure to Launch Debugging: 1)
Reboot
, 2)
disable anti-virus
, 3)
launch as admin
and check, 4)
Check dependencies and runtimes
(Java, VC++ Runtime, .NET, etc...). Then, if need be: 5)
verbose log
, 6)
event logs
, 7)
Try on a virtual
if you still can't get it working? (many virtuals lack essential runtimes - check) Or secondary computer?
Also 8)
google exact error messages
and check user comments, 9)
Run update for the application in question?
(new installer could eliminate the error situation). 10)
Run a full check for malware
too? It is all over the place these days. 11)
Some software (often server software) may need configuration settings sorted out (misconfiguration
). Desktop applications may need license
to launch at all.
Locks?: With permission and locks you can try to run the tool with elevated rights
? You could have disk corruption - disk errors
? Faulty ACL permissions
? (possible). Your anti-virus suite
has locked some file that MSI is trying to put back in place. You can try to disable it temporarily to see. Note that the file can have been quarantined
as well (moved somewhere else).
For setups that won't install properly. A few generic tricks below - in addition to checking event logs
and installation-
and application logs
and googling any error messages
(always do that too - perhaps first - but maybe just do a reboot first - before facing all the complexity):
- Reboot: Reboot first after a failed install to see if that solves locks and pending renames.
- Other Computer: Try installing on another physical machine instead?
- Important smoke test of the installation media!
- Virtual: Try installing on a Virtual machine instead?
- Often outdated, check runtimes, check Windows Update.
- Runtimes: Ensure required runtimes of various types are on there in the required version:
- Common:
VCRedist
, .NET
, .NET Core
, Java
, Direct X
, etc...
- Specific:
Python
, DBMS systems
(PostgreSQL
, MSSQL
, etc...
)
- Windows Components:
IIS
, MSMQ - Message Queue
, Powershell
, etc...
- Secondary Account: Try installing on main box using a different admin account. This can sort out problems caused by errors in the user profile (not at all that uncommon).
- Local Installation Files: Copy installation files locally if they are on the network when invoked (to eliminate network error sources).
- Localization Issues: It is not uncommon for setups delivered in other languages to contain brand new bugs not seen in the original installer (usually English).
- "Murphy Field":
"We have managed to add additional bugs to the internationalized setups beyond the English version"
. Oh the humanity say! Bummer.
- Try to download an English setup version and test install?
- Try the localized setup on an English machine or virtual?
- Also investigate running with another user account with different language settings.
Setup.exe - again - the common "blockers":
- Corrupt Setup File: Corrupt setup file. Re-download to be sure? Get this done as one of the first steps before wasting a whole day? Correct platform bitness? Right CPU-architecture?
- Malware: Malware can cause just about "anything" in terms of problems.
- Security Software:
Anti-virus
, firewalls
, scanners
, etc...
can interfere with installation. Disable temporarily if possible when required.
- Disk Space: Ensure enough disk space!
- Proxy: If there is a network requirement, is there a proxy server that blocks things?
- Policies: There can be policies in effect on managed networks to block certain features making the install impossible. Try on virtual? Usually less restricted.
- Disk Errors: Scan disk to see if it is OK. If not, fix it first. Modern NVMe disks can lose a lot of data with power outages for desktops without UPS.
- Disk Security ACL: Custom security ACL (NTFS access configuration) configuration that leads to runtime errors for Windows components and software alike. Never use custom ACL for Windows directories unless you know what you are doing. Errors are CERTAIN.
Some Links:
Easy Access:
Repackaging, Application Launch Debugging:
Upgrades:
Some Other WiX Links:
Procedures:
- Open Temp folder: Windows Key => Tap R => Type:
%TEMP%
=> Press: Enter.
- ARP: Go start → run → appwiz.cpl → ENTER in order to open the add/remove programs applet (or click add/ remove programs in the control panel).
- Settings GUI Win8/10: Windows Key + Tap I =>
Apps & Features
. Select entry and uninstall.
- Quick start of Powershell: hold Windows key, tap R, type in "powershell" and press Enter.
- Restart Graphics Driver: Windows key + Ctrl + Shift and tap B.
Some good starting links to learn Wix:
Extract Files from Setup.exe
WiX Bundle or from an MSI file itself:
As I wrote in my suggested "Wix quick start" post above: Wix is hands-on. Just focus on simple, but complete real-world samples like the one from Codeproject - reading the documentation alone is likely to be merely confusing.
Focus on splitting your application into components and set up a major upgrade. Use one file per component as a rule of thumb, and read this answer for a better understanding of component creation: Change my component GUID in wix?
A major upgrade is the most commonly used upgrade mechanism for deployed software (the other common upgrade type is minor upgrade). It is obviously crucial that you can upgrade what you have deployed already. Get upgrade scenarios working before you deploy your first software version so you have confidence in your deployment solution.
Once you got your components set up and your upgrade solution is working, the rest of the pieces fall into place as you work your way through your application's deployment requirements and check for samples on the Wix tutorial site: https://www.firegiant.com/wix/tutorial/.
For those writing Wix code directly (without a GUI editor), I suggest you check this answer for a way to keep your source files terse: Syntax for guids in WIX?
Further read: