Let\'s discuss following topic. There is application which currently is being deployed with good to know xcopy method.This approach makes difficult to manage dependencies, f
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?
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.
- Wix Toolset Download (
1)
Main WiX setup,2)
Votive - Visual Studio integration setup- WiX Documentation
- After WiX installation locate
WiX.chm
andmsi.chm
help files in installation folder "%ProgramFiles(x86)%\WiX Toolset v3.11\doc
" for quick access to documentation.- Online: WiX Reference Manual v3, Official WiX Tutorial.
- Github, Bug Tracker, Mailing List, FireGiant WiX KDB (FireGiant is WiX's commercial branch).
- To get your head around Wix, you might want to read a quick, unofficial summary of the history behind it.
- MSBuild - using Visual Studio, Votive and MSBuild
- Harvesting (1): WiX has its own tool for generating WiX markup based on an input folder.
- The tool is called heat.exe. WiX's commercial branch FireGiant has a tool called HeatWave with more features.
- Largely untested by me is the tool
WixHeatATLHarvesterExtension
: https://github.com/nirbar/WixHeatATLHarvesterExtension (a WiX Heat extension to harvest registry information from x64 modules)
Other Tools:
- Then you might want to check other ways to deliver an installer, besides Wix by reading:
- What installation product to use? InstallShield, WiX, Wise, Advanced Installer, etc
- One more quick-list of tools
- Major Tools: Advanced Installer, - InstallShield, - PACE Suite
Hello World & Hello WiX:
- Finally view a complete example of how a Wix source file and its components look like on Codeproject. This is the "Hello World" of Wix.
- "Hello WiX - step-by-step in Visual Studio".
Video Samples:
- How To Create Windows Installer MSI - .Net Core WiX
More Sample Code:
WiX Quick Start: Here are some of the best sample code links that I have found:
- Helge Klein's real-world WiX sample - do check this out (Wayback - Archived Version).
- Rainer Stropek's WiX Samples on Github - can be very helpful.
- From MSI to WiX by Alex Schevchuk - aging content, but excellent.
- Chris Painter's IsWiX Tutorials - excellent WiX samples.
And finally:
- Phil Wilson's Github repository for MSI samples: https://github.com/Apress/def-guide-to-win-installer. The best content, but aging. General MSI samples, not WiX as such.
- My experimental site: installdude.com.
- How-to-create-a-Windows-Service-MSI-Installer-Using-WiX.
- WiX Extension: https://github.com/nirbar/PanelSwWixExtension (
Dism.exe
,etc...
)
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:
- Common Causes for Custom Action runtime failures
- Debugging Custom Actions
- For native code / C++ just attach debugger to
msiexec.exe
- Advanced Installer's Debug C# Custom Actions video tutorial
MSI logging:
- Overview and summary (how to log, interpreting log file, etc...)
- Installsite: MSI log "how-to"
- More MSI logging information
Event Viewer:
- Hold down Windows Key, tap R, type
eventvwr.msc
and press Enter.- Go to
Windows Logs => Applications
. Look forMsiInstaller events
.- Check the other logs too (
Security
,System
,Configuration
).General Debugging:
"Debugging Light"
Application Launch Problem: Debugging Ideas (torpedoes full spread)
ProcMon.exe: The tool of the trade. The one-size-fits-all tool. The bee's knees, the topper-most, the quantum leap, the cat's pajamas. It can be a challenge to use it effectively, but it is the best general-purpose debugging tool that is free (comment link for safekeeping).
- Quick, Rudimentary Sample
- Hanselman's longer video sample (from about 3:50 onwards)
Debugging Tools:
- Tools to debug dependency issues -
ProcMon.exe
,VS
,Dependency Walker
,etc...
- COM dependency errors
- Fuslogvw.exe (Assembly Binding Log Viewer)
- Essential service debugging tools:
Event Viewer
,Task Manager
,Services.msc
- Process Explorer, NET command, SC.exe
- Windows Services Frequently Asked Questions (FAQ)
Error Code: Looking up error codes and exception messages.
- "The Magic Number Database" - online lookup.
- Checking Error Codes - several tools and approaches.
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)
Checkdependencies 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) Orsecondary computer?
Also8)
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 formalware
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 needlicense
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). Youranti-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 beenquarantined
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.
- 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!
- Ways to clear out disk space. Long version.
- Just run
cleanmgr.exe
first.- 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:
virtuals
, compatibility mode
, repackaging
, etc...
)Repackaging, Application Launch Debugging:
Upgrades:
Some Other WiX Links:
Procedures:
%TEMP%
=> Press: Enter.Apps & Features
. Select entry and uninstall.Some good starting links to learn Wix:
Extract Files from Setup.exe
WiX Bundle or from an MSI file itself:
dark.exe
toolAs 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: