Update Instance Mode

When you install a package into an instance that already exists, Install-UscPackage needs to know how to reconcile the new package with what is already installed. The -UpdateInstanceMode parameter controls this behavior and is only used together with the -UpdateInstance switch.

UpdateInstanceMode accepts two values:

  • Merge (default) — adds the new package to the instance without removing anything.
  • Replace — removes any packages that are not part of the new package (or its dependencies).

Merge (default)

Install-UscPackage -Id 'package-a' -InstanceName 'MyInstance'
Install-UscPackage -Id 'package-b' -InstanceName 'MyInstance' -UpdateInstance -UpdateInstanceMode Merge

Package A is installed first. Package B is then added to the same instance. Because the mode is Merge, package A is left in place.

Resulting instance: package-a, package-b

Replace

Install-UscPackage -Id 'package-a' -InstanceName 'MyInstance'
Install-UscPackage -Id 'package-b' -InstanceName 'MyInstance' -UpdateInstance -UpdateInstanceMode Replace

Package A is installed first. Package B is then installed with Replace, which removes any package that is not part of package B. Since package A is unrelated to package B, it is removed.

Resulting instance: package-b

Replace with dependencies

Dependencies are preserved during a replace. Consider a bundle with the following dependency tree:

bundle/pos
    package-a
    package-b

$packages = @(
    @{ Id = 'package-a'; Version = '' },
    @{ Id = 'package-c'; Version = '' },
)
$packages | Install-UscPackage -InstanceName 'MyInstance'
Install-UscPackage -Id 'bundle/pos' -InstanceName 'MyInstance' -UpdateInstance -UpdateInstanceMode Replace

The first command pipes an array of package definitions into Install-UscPackage, installing package-a and package-c into the instance in a single call. When bundle/pos is then installed with Replace:

  • package-a — kept, because bundle/pos depends on it.
  • package-b — installed, because bundle/pos depends on it.
  • package-c — removed, because it is not part of bundle/pos or its dependencies.

Resulting instance: bundle/pos, package-a, package-b

Previewing changes

If you are uncertain what a Merge or Replace will do to an existing instance, use Get-UscUpdates to preview the result without applying it. It accepts the same parameters as Install-UscPackage (except -UpdateInstance) and returns the operation, Install, Update or Remove, that would be performed on each package.

Get-UscUpdates -Id 'bundle/pos' -InstanceName 'MyInstance' -UpdateInstanceMode Replace