Skip to main content

App Hooks

Applies to
Windows
MacOS
Linux

Hooks allow your application to run logic at various stages of the install/update/uninstall process.

In general, handling hooks manually is not recommended - instead, prefer the available VelopackApp options.

If you wish to handle these yourself, an SDK doesn't exist for your language, or you just want to learn more about it, read on.

The command-line argument and environment-variable mechanisms described below are cross-platform. The C# VelopackApp builder also offers convenience "FastCallback" methods (OnAfterInstallFastCallback, OnAfterUpdateFastCallback, OnBeforeUpdateFastCallback, OnBeforeUninstallFastCallback) which wrap these hooks — but those are Windows-only and are no-ops on macOS and Linux.

Command line hooks​

At various stages of the install/update/uninstall process, Velopack will execute your main executable (the one specified when packaging with --mainExe {exeName}) with certain cli arguments and expect your app to exit as quickly as possible.

  • --veloapp-install {version} Occurs after the program has been extracted, but before the install has finished. App must handle and exit within 30 seconds.
  • --veloapp-obsolete {version} Runs on the old version of the app, before an update is applied. App must handle and exit within 15 seconds.
  • --veloapp-updated {version} Runs on the new version of the app, after an update is applied. App must handle and exit within 15 seconds.
  • --veloapp-uninstall {version} Runs before an uninstall takes place. App must handle and exit within 30 seconds.

At this time, there is no way to provide feedback during the hooks that you would like to cancel the install/uninstall/update etc, and you may not show any UI to the user.

warning

If your application receives one of these arguments and does not exit within the alloted time, it will be killed.

Environment variable hooks​

There are also two environment variables that get set, if these are detected your app does not need to exit.

  • VELOPACK_FIRSTRUN is true if this is the first run after the app was installed.
  • VELOPACK_RESTART is true if the application was restarted by Velopack (usually because an update was applied.)

In C#, you don't need to read these variables directly. VelopackApp.Build().OnFirstRun(...) fires when VELOPACK_FIRSTRUN is set, and VelopackApp.Build().OnRestarted(...) fires when VELOPACK_RESTART is set. Unlike the FastCallback hooks above, these run during a normal launch and your app continues running afterwards.

For the full set of Velopack environment variables, see Debugging.