Package Reference
A package is an archive of the following files:
- Manifest file describing the package.
- PowerShell scripts to automate the process of installation, upgrading, configuring and removing the software component.
- Files for the software component, such as setup files.
See How to create a package or use the cmdlet New-UssPackage to create a package.
Manifest
A manifest file contains metadata for the package, describing it's identity, version and other functionality.
Manifest file can be generated with New-UssManifest or create a new package with New-UssPackage.
| Property | Description |
|---|---|
| Id | Unique identifier for the package. |
| Version | Version of the package. |
| Name | Name for the package, independent of the version. |
| DisplayName | Name for this version of the package. |
| Description | Package description, visible to users. |
| Instance | true or false, indicating if this is an instance package (see Instance Packages for further details). |
| Commands | Table of commands this package implements (see Commands section below). |
| Dependencies | List of other packages this package depends on (see Dependencies for further details). |
| Parameters | List of parameters this package accepts (see Parameters for further details). |
| FillParameters | Parameters this package fills for another package if installed together (see Fill Parameters for further details). |
Instance Packages
You can install multiple instances of instance packages on a computer. When an instance of a package is installed, it is assigned an arbitrary directory where you can place the install files and it's assigned an instance name which it can be referenced by.
The same instance can also contain multiple instance packages which can complement each other, i.e. installing bc-server and ls-central-objects together for the same instance will first install the Business Central service tier and then import the LS Central objects to the service tier.
During the package commands execution, the package script can access or reference the instance directory through $Context.InstanceDirectory and the instance name via $Context.InstanceName.
Commands
Packages usually implement Commands that are executed during install, update or removal of a package. The commands of packages are executed in the same order as package dependencies are resolved.
The commands available are as follows:
| Command | Description |
|---|---|
| PreInstall | Executed the first time a package is installed, before any Install, Update or Remove commands. |
| PreUpdate | Executed when a package is being updated, before any Install, Update or Remove commands. |
| PreRemove | Executed when a package is being removed, before any Install, Update or Remove commands. |
| Install | Executed the first time a package is installed. |
| Update | Executed when a package is being updated. |
| Remove | Executed when a package is being removed. |
| Rollback | Executed if Install or Update commands fail during execution. If the execution of Install/Update command fails for an instance package, the Rollback command is executed for each already executed package of the same instance. |
| PostInstall | Executed the first time a package is installed, after all Install, Update or Remove commands. |
| PostUpdate | Executed the first time a package is installed, after all Install, Update or Remove commands. |
Commands implemented by a package are defined in the manifest file, they are listed with a reference to a function in the PowerShell file also included in the package.
See also Package Execution.
Dependencies
Packages can have dependencies on other packages, which are installed or updated prior to the package.
In the manifest file you can define a list of one or more packages to depend on, the dependencies are resolved (or executed) in the order given, but other dependencies can affect how the package list is resolved.
Dependency is defined by referencing the package with package id and version query.
For further information see New-UssDependency.
Parameters
A package can have parameters to configure the installation, these parameters are prompted to the user when running the install wizard and can be passed to Install-UscPackage when scripting as well.
For further information see New-UssParameter.
Fill Parameters
A package can fill or set parameters for other packages if they are being at the same time or already installed.
Package Execution
Packages are executed by resolving selected packages in the dependency order, the first package(s) executed has no dependencies, ending with a package that is not being depended on. I.e. if we have packages with the dependency order:
A -> B -> C
the packages will be executed in the following order: C, B, A.
Package execution is also split into three phases, pre, regular and post phase. Each resolved package that implements a Pre* command gets executed in the pre-phase, packages implementing Install, Update or Remove commands are executed in the regular phase and likewise, packages implementing Post* commands get executed in the post-phase.
The $Context Variable
The PowerShell function invoked during a package execution is passed a context variable as an argument, simply called $Context, that can be used while executing a package command.
The variable contains the following properties:
| Property | Description |
|---|---|
| Id | Current package id, such as example-app. |
| Version | Package version being installed. |
| PreviousVersion | Version being upgraded from, empty if first install. |
| Command | Value can be Install, Update or Remove, depending on the execution. |
| InstanceCommand | Is Install if the instance is created, Update if the instance already exists or Remove if the whole instance is being removed. |
| InstanceName | If an instance of a package is being installed, the instance name is available through this property. |
| InstanceDirectory | If an instance package, a unique instance directory is given to the instance. |
| TemporaryDirectory | A temporary directory containing the package's files, the directory and it's content is delete after execution. |
| Arguments | Dictionary containing arguments set by the user (or other packages) passed to the package. |
| InstallationGuid | A unique identifier for this installation. |
| PackageOnError | Package ID of the failed package. |
| UpdateStrategy | Automatic or Manual. |
| Environment.ServiceUser | A windows user who runs, or is set to run the Update Service client service, on the form domain\username. |
| Environment.ServiceUserName | The username part of the ServiceUser, without the domain\. |
| Environment.ServiceUserDomain | The domain part of the ServiceUser, without the \username. |
| Environment.IsContainer | True, if executed inside a Docker container. |
Execution Failure and Rollbacks
The Rollback command of a package is executed if any of the following commands fail during installation: Install, Update, PostInstall or PostUpdate and should take care of reverting any possible changes during the installation. Any other packages successfully installed will not be rolled back or execute the Rollback command, with the exception of instance packages. If an instance package fails to install, A Rollback for all other already executed instance packages in the same installation will be executed.