Risks in Solution Upgrades

When you import a managed solution, the platform offers two ways: upgrade and update. They differ in one word and in one decisive behavior. Upgrade is the default, and Microsoft explicitly recommends it (Microsoft Learn: Upgrade or update a solution).

An update lays the new version over the old one. It adds and overwrites, but it removes nothing. An upgrade, by contrast, reconciles. Components that are missing from the new version are deleted in the target environment. This is the only built-in way to clean up through the delivery process. It is also the point where it gets dangerous. Because upgrade is the default, things often get deleted without anyone having decided it consciously.

Where the risk lies

What is missing gets deleted. That sounds like intent, but it also covers the slip. A field was removed from the solution in development, perhaps while restructuring into a segmented solution. During the upgrade it then disappears from the target environment. With a field, its data disappears too. There is no undo function for this, only the backup of the environment.

The same applies to tables, relationships and choice lists. For forms or views the loss is annoying. For data fields it is final.

One step, and the special case with an intermediate stage

Today an upgrade runs in one step. The new version is imported, replaces the old one, merges existing patches and carries out the deletions.

There is also the option "Stage for Upgrade". The new version is first imported as a holding solution, recognizable by the name suffix "_Upgrade". Only a second, separate step applies the upgrade. This makes sense when data has to be moved between the steps, for example out of a field that disappears afterwards. The catch lies exactly there. If the second step aborts, the environment stays in the intermediate state with both versions. This happens, for example, when another solution depends on a component that is to be deleted. It can be repaired, but it is not intuitive. And it tends to happen in the evening, during the maintenance window.

What you can read from the exports beforehand

The nice thing about this risk is that it is fully predictable. Comparing the component lists of the old and the new version shows exactly what an upgrade will delete. In both exports, the components are in the solution.xml under "RootComponents". For tables that sit in the solution completely and not segmented, however, the fields are not listed there individually. For them, the customizations.xml has to be part of the comparison. Mechanically, it remains the same task.

Before every upgrade, this difference list belongs on the table. Make one conscious decision per entry: should this really go? For fields, also ask whether data sits in them. If the answer is unclear, the safe way is an update instead of an upgrade. And the cleanup waits until the answer is clear.

A related stumbling block belongs in the same preparation: dependencies of other solutions on the components to be deleted. If a form or a flow of a neighboring solution hangs on the field that is about to disappear, it blocks the upgrade step. This can also be checked in advance through the dependency view of the affected components. It belongs on the difference list as well. The export itself is the basis for all of this.

The rule of thumb

Upgrade is the normal case and Microsoft's recommendation. That is exactly why the deletion list belongs before every import. Update is the tool for the case where a deletion has not been decided yet. Whoever runs an upgrade without having seen the deletion list delegates an irreversible decision to chance.