App Setup and Upgrade

The process of installing or upgrading an app

An app in Bench is installed according to its typ. Default apps are installed by downloading their app resource file/archive extracting or copying it into the apps target directory. Meta apps are installed completely via custom scripts or they just serve as groups for other apps via their dependencies. Package apps are installed via their package manager. Custom scripts can extend or override different steps of the setup process.

Overview

App Lifecycle

The lifecycle of an app generally breaks down into the following steps. Not all app types support or need all steps.

  1. Download app resource (only for default apps)
  2. Extracting the app resource archive (only for default apps with archive resource, can be overridden by a custom extract script)
  3. Setup of the resources by copying to the target directory or installation via package manager (can be followed by a custom setup script)
  4. Setup of the execution adornment proxies and the launchers
  5. Environment setup for configuration depending on the proxy settings, the absolute path of the Bench root directory, or other parameters that may change after setting up the app (this step can be performed multiple times, whenever the environment changes, implemented by a custom environment setup script])
  6. Uninstalling the app (can be preceded by a custom removal script)
  7. Deleting cached resources

Upgrading an app generally means, uninstalling the app, deleting cached resources, and installing it again. Apps which are defined with a fixed version number in their definition can not really be upgraded without changing their definition. But apps without a specific version number or a version range, can be upgraded in that way.

Dependencies and Order

Before an app can be installed, all of its dependencies must be installed. This is necessary to allow custom setup scripts of an app depend on the apps dependencies to be installed. If an app with dependencies is installed in a task, then the task is automatically extended to cover all dependencies not installed yet. The same is true the other way around for the uninstallation of an app. Before an app is uninstalled, all apps that depend on this app are uninstalled before the app is uninstalled.

If multiple apps are installed or uninstalled in one task, the steps, e.g. download, setup, and environment setup, can be performed consolidated. Meaning first all downloads are performed, then all setups are performed, and at last the environment setup for all affected apps is performed. Multiple apps are always installed in the order their ID is first listed in the application libraries – first Bench app library, then user app library.

Custom Scripts and Hooks

Simple default apps with XCOPY deployment or package apps, usually do not need custom scripts. But many Windows programs require some additional setup or configuration steps to work properly. That includes e.g. moving or deleting files extracted from the apps resource archive, writing configuration files, even executing programs for initialization.

For an app included in the Bench system, the custom scripts are stored in the app automation directory. For an app defined in the user app library, the custom scripts are stored in the subfolder apps of the custom configuration directory. Additional automation, not directly associated with a specific app can be implemented in the hooks for setup and environment setup.

Details for Different App Types

In the following sections, specifics of the setup process for the different app types are explained.

Meta Apps

Meta Apps do not have an app resource, which could be downloaded and installed, via the install mechanisms Bench provides. And it can not be installed via a package manager, which is supported by Bench.

Therefore, all setup steps – given that there are some – have to be performed by the custom scripts or hooks, respectively. Because Meta Apps do not have resources, downloaded by Bench, their setup process consists only of the setup step for the app resources and the setup step for the environment. When uninstalling or upgrading Meta Apps, the [uninstall step][custom remove] is used.

Group Apps

Group Apps behave the same way as Meta Apps. They exist to make a better destiction between custom apps, which use scripts to perform all setup steps, and apps which collect a number of other apps as dependencies to form a group for more flexible app activation.

Default Apps

Default Apps are programs, which consist of at least one file, which is executable by Windows. This can be an *.exe, a *.cmd, or a *.bat file. A Default App has a resource file or archive which can be downloaded via a HTTP(S) URL. If the app has resource file, usually the resource file itself is the executable. If the app has a resource archive, the executable can be one of many files.

Installation

A Default App can be installed, if it is not installed already.

The installation of a Default App is performed by the following steps:

  • Download the resource file or archive if not cached
  • If the resource is an archive file:
    • If the ArchiveTyp is auto or custom and a custom extract script <app-id>.extract.ps1 is found: Run the custom script to extract the archive content.
    • Else if the ArchiveTyp is auto: Select an extractor by the filename extension and extract the archive.
    • Else if the ArchiveTyp is msi: Use LessMSI to extract the archive content.
    • Else if the ArchiveTyp is inno: Use InnoUnpacker to extract the archive content.
    • Else if the ArchiveTyp is generic: Use 7-Zip if installed, else use DotNetZip library to extract the archive content.
  • Else Copy the resource file to the apps target directory.
  • Run the custom setup script <app-id>.setup.ps1 if one is found.
  • Run the setup hook script if it exists. If multiple apps are installed in one task, the hook script is only run once at the end.
  • Create execution adornment proxies if needed.
  • Create launcher scripts and shortcuts if the App Launcher property is set.
  • Run the custom environment setup script <app-id>.env.ps1 if one is found.
  • Run the environment setup hook script if it exists. If multiple apps are installed in one task, the hook script is only run once at the end.

To check if a Default App is already installed, the SetupTestFile is checked for existence.

Upgrade

A Default App can be upgraded, if it is installed, and its Version is empty or set to latest.

The upgrade of an Default App is performed by removing the app, deleting its app resource in case it is cached, and installing the app again.

Uninstalling

A Default App can be uninstalled, if it is installed.

The removal of an app is performed by the following steps:

  • Run the custom removal script <app-id>.remove.ps1 if one is found.
  • Delete the apps target directory and all of its content.

Package Apps

Package Apps are apps, which are managed by some kind of package manager. Examples are npm for Node.js or PIP for Python.

Installation

A Package App can be installed, if it is not installed already.

The installation of a Package App is performed by the following steps:

  • Execute the package manager in the installation mode,
    e.g. npm install package-xyz@3.1.2 --global.
  • Run the custom setup script <app-id>.setup.ps1 if one is found.
  • Run the setup hook script if it exists. If multiple apps are installed in one task, the hook script is only run once at the end.
  • Create execution adornment proxies if needed.
  • Create launcher scripts and shortcuts if the App Launcher property is set.
  • Run the custom environment setup script <app-id>.env.ps1 if one is found.
  • Run the environment setup hook script if it exists. If multiple apps are installed in one task, the hook script is only run once at the end.

Upgrade

An Package App can be upgraded, if it is installed.

The upgrade of an app is performed by removing the app, deleting its app resource in case it is cached, and installing the app again.

Uninstallation

A Package App can be uninstalled, if it is installed.

The uninstallation of a Package App is performed by the following steps:

  • Run the custom removal script <app-id>.remove.ps1 if one is found.
  • Remove the installed package
    • If it is a NuGet package: Deleting the app target directory with all its content.
    • Otherwise: Execute the package manager in the uninstallation mode,
      e.g. npm remove package-xyz --global.

Notice: To remove the Launcher for the app, the environment setup must be executed.