WiX Burn Command Line and Custom Bootstrapper Event Sequence

When a bootstrapper created with the WiX burn program executes, there are six possible Actions that it can handle: Install, Uninstall, Layout, Modify, Repair, and Help. (There are three more listed in the enum, but I don't know how they get triggered as they are not supported on the command line: Cache, UpdateReplace, and UpdateReplaceEmbedded.) The actions can be triggered by a switch on the bootstrapper application's command line:

setup [/install|/uninstall|/layout [path]|/modify|/repair|/help|/?] [/full|/none|/passive|/embedded] [other parameters]

The default is /install /full. The /help and /? options both cause the Help action. You can detect which Action was passed by checking this.Command.Action and comparing the values to the enum LaunchAction. You can detect which Display option was passed by checking this.Command.Display against the enum Display. If you are constructing your own interface, you can interpret the Action and Display switches as you see fit. If you don't want to support one, you should return an error. The /layout option may have an optional path, which can be retrieved from this.Command.LayoutDirectory.

Other information can be passed on the command line, which can be read from this.Command.GetCommandLineArgs(), which returns a string array. The string array will have the Action or Display options stripped.

The actual parsing of the command line is found in this C++ code in the ParseCommandLine() method.

When a WiX custom bootstrapper executes, there are a series of events that occur. Although you can add your own event handlers, there is no need. Instead, when you inherit from BootstrapperApplication, you can then override methods whose names all begin with On. If you override one of these method, you should call the base method at the end. For example:

protected override void OnStartup(Microsoft.Tools.WindowsInstallerXml.Bootstrapper.StartupEventArgs args)
{
    this.Engine.Log(LogLevel.Standard, "OnStartup");
    base.OnStartup(args);
}

Below is the sequence of events as they occur, and which Action causes them to execute. It is helpful to have these as comments in the Custom Bootstrapper file, so I've formatted them to be copied and pasted.

// I=Install U=Uninstall L=Layout M=Modify R=Repair
//// OnStartup (IULMR)
////  OnDetectBegin (IULMR)
////   // For each package
////   OnDetectPackageBegin (IULMR)
////   OnDetectPackageComplete (IULMR)
////  OnDetectComplete (IULMR)
////  OnPlanBegin (IULMR)
////   // For each package
////   OnPlanPackageBegin (IULMR)
////   OnPlanPackageComplete (IULMR)
////  OnPlanComplete (IULMR)
////  OnApplyPhaseCount (IULMR)
////  OnApplyBegin (IULMR)
////   OnCacheBegin (LR)
////    OnProgress (L)
////    OnCachePackageBegin (LR)
////     OnResolveSource (L)
////     OnCacheAquireBegin (LR)
////      OnCacheAcquireProgress (repeats) (LR)
////     OnCacheAquireComplete (LR)
////     OnCacheVerifyBegin (LR)
////      OnCacheAcquireProgress (repeats) (LR)
////     OnCacheVerifyComplete (LR)
////     OnProgress (LR)
////    OnCachePackageComplete (LR)
////   OnCacheComplete (LR)
////   OnElevate (IUM)
////   OnRegisterBegin (IUM)
////   OnRegisterComplete (IUM)
////   OnExecuteBegin (IULMR)
////    OnExecutePackageBegin (IUR)
////     OnExecuteProgress / OnExecuteMsiMessage (repeats) (IUR)
////     OnProgress (IUR)
////    OnExecutePackageComplete (IUR)
////   OnExecuteComplete (IULMR)
////   OnUnregisterBegin (IUMR)
////   OnUnregisterComplete (IUMR)
////  OnApplyComplete (IULMR)
//// OnShutdown (IULMR)

// Other events that may occur:
// OnDetectCompatiblePackage
// OnDetectForwardCompatibleBundle
// OnDetectMsiFeature
// OnDetectPriorBundle
// OnDetectRelatedBundle
// OnDetectRelatedMsiPackage
// OnDetectTargetMsiPackage
// OnDetectUpdate
// OnDetectUpdateBegin
// OnDetectUpdateComplete
// OnError
// OnExecuteFilesInUse
// OnExecutePatchTarget
// OnLaunchApprovedExeBegin
// OnLaunchApprovedExeComplete
// OnPlanCompatiblePackage
// OnPlanMsiFeature
// OnPlanRelatedBundle
// OnPlanTargetMsiPackage
// OnRestartRequired
// OnSystemShutdown