Wix Bootstrapper: Sequence of Bootstrapper events

Question

I've started playing with Managed Boostrapper Classes and events. Making story short, I've added BoostrapperCore.dll and it would give you the namespace

Microsoft.Tools.WindowsInstallerXml.Bootstrapper

I was able to get some info from some examples present in different blogs. For instance, the Entry point is BootstrapperApplication.Run(), is called when bootstrapper application is ready to run.

Then there are events like:

BoostrapperApplication.DetectBegin
BoostrapperApplication.DetectPackageBegin
BoostrapperApplication.DetectForward

etc, etc...

Question: Is there any precise documentation/online help which provide the details and sequence of Events and Methods present in Microsoft.Tools.WindowsInstallerXml.Bootstrapper namespace?

That would definitely save a lot of time...

Regards

Answer 1

While the source code is on git, I'm yet to find a significant amount of documentation for these events.

As far as order goes, a the WiX bootstrapper has 3 main phases (all of which happen asynchronously)

Detect

This is when the Burn engine tries to figure out what (if anything) is already installed. The bootstrapper application starts this process by calling Engine.Detect, which you will probably want to do as soon as the bootstrapper starts, as you need the outcome of this in order to decide whether to show install, uninstall or upgrade UI.

During this phase the engine will raise the OnDetect... events to tell the bootstrapper application about what it finds.

Plan

This is when the Burn engine figures out what its going to do. The bootstrapper application starts this process by calling Engine.Plan, specifying the desired operation (e.g. Install, Uninstall, Upgrade etc...). This is normally done right before the Apply phase, e.g. after the user clicks on the "Go" button). The OnPlan... events are raised in this phase.

Apply

This is when the Burn engine actually installs or uninstalls packages in the bundle, and starts when the bootstrapper application calls Engine.Apply. The vast majority of the remaining messages are raised during this phase for a combination of progress & error reporting, or to allow the bootstrapper application to handle certain things (e.g. OnResolveSource, which can be used to prompt the user to find file that the engine cannot locate)

Apply has two sub-phases, Cache and Execute.

---

There are only 3 events that I can see that are not raised during one of these 3 phases:

• OnStartup, which is raised when the bootstrapper first starts (the base bootstrapper application calls the Run entry point as part of handling this event)
• OnShutdown, raised when the bootstrapper is exiting
• OnSystemShutdown, raised when the WM_QUERYENDSESSION window message is received

The events you absolutely need to handle are OnDetectComplete, OnPlanComplete, OnApplyComplete, which will happen in that order.