Virtual Symbols

[robmen]

User story

• As a setup developer, I can make any symbol "overridable", not just specific symbol types like actions, bind variables and directories.
• As a WiX Developer, I can create the WiX Standard Library without adding additional special case overrides.

Proposal

The WiX toolset supports "overriding" a few symbol types to support some common but narrow scenarios. For example, WixAction symbols can be defined Overridable, which allows the standard Windows Installer actions to be statically defined in the WiX code but still allows setup developers to customize the sequence or condition of a standard action. Similarly, WixVariable can be defined Overridable to allow late bind time customization of libraries. Finally, the linker and Windows Installer backend have special handling to include the standard directories when needed.

With the exploration of more default symbols (such as default MajorUpgrade and default Feature) it is clear that the concept of allowing a symbol to be "overridden" is generally useful.

To support overridable generically, we'll borrow the concept of virtual methods from object-oriented programming languages and add a new virtual and override access modifiers to WiX. Symbols with identifiers marked virtual are considered global and can be optionally overridden by a single symbol with an identifier marked override. It is a linker error if the same identifier is found to be virtual by more than one symbol or override by more than one symbol.

The following is a trivial example where a Property symbol is defined and overridden in the same section. This is not practically useful.

<Fragment>
  <Property Id="virtual MyProp" Value="This value will not be used if MyProp is overridden." />
  <Property Id="override MyProp" Value="This value will be in the build output." />
</Fragment>

Considerations

• Virtual symbols are an advanced feature that requires sections to be carefully organized to prevent undesirable side effects. Thus, it is recommended that virtual symbols are generally placed in very small sections with no other global symbols.

• In WiX v5, virtual symbols will be allowed anywhere but we may need to limit their applicablity in future releases. For example, virtual Component symbols could easily create Component Rule violations but it is not clear that virtual makes this any more likely than cut-n-paste does already.