UpgradeAddOn includes two properties that identify the AddOn objects to upgrade from and the AddOn objects to upgrade to. The FromVersions property specifies one or more installed AddOn objects to be upgraded. The ToVersions property specifies one or more new AddOn objects with the data to upgrade to. When the UpgradeAddOn object is installed on an object store, the add-ons listed in the FromVersions property are replaced with the add-ons listed in the ToVersions property. In effect, UpgradeAddOn serves as a migration path: it upgrades an existing object store to the equivalent state of a new object store created with the AddOn objects that are listed in the UpgradeAddOn.ToVersions property.
An UpgradeAddOn object has an import dataset, a pre-import script, and a post-import script. An UpgradeAddOn object is installed using the same API method, ObjectStore.installAddOn, as an AddOn object.
The following steps summarize the actions you would take to upgrade an object store from "v1.0Addon" to "v2.0Addon" using the "v1.0to2.0UpgradeAddon".
If the installation is successful, the AddOnInstallationRecord for v1.0Addon is replaced by an AddOnInstallationRecord for v2.0Addon, and the AddOnInstallationRecord for v1.0to2.0UpgradeAddon is removed.
If the installation fails, the AddOnInstallationRecord for v1.0to2.0UpgradeAddon remains, with a report of the failure set on the object's InstallationReport property.
Note that once the v1.0to2.0UpgradeAddon has been applied to all the object stores having the v1.0Addon installed, both the v1.0Addon and the v1.0to2.0UpgradeAddon can be deleted from the GCD, since neither will be referenced by any object store's AddOnInstallationRecordList.