QueryStorm Runtime Overview

The QueryStorm runtime is an add-in for Excel (separate from the IDE) designed to be used on end user machines. It is an execution platform on top of which QueryStorm apps are shared and executed. This page gives an overview of the responsibilities and features of the runtime.

Running Workbook apps

When a workbook is open in Excel, the runtime checks to see if it contains an app by looking for a manifest file in the bin folder. If it finds one, it performs a security check and, if the app is untrusted, prompts the user for permission to run the app. If permission is granted, the runtime will load the app and run it. When the workbook is closed, the app is also stopped and unloaded.

Managing and running Extension apps

Aside from running workbook apps, the runtime also includes an Extensions Manager that allows browsing and installing extension apps published by the QueryStorm team as well as apps published by other QueryStorm users.

Installed extension apps are loaded during Excel startup. During startup, apps register any functions, ribbons, context commands, and keyboard shortcuts they contain. Apps are installed into the %appdata%\QueryStorm2\Extensions folder. Each extension is installed into its own subfolder, and a record is added to the dependencies.cat json file.

Isolation

The runtime executes each app in its own .NET AppDomain. This ensures a degree of separation between apps, so that one app does not interfere with another. Additionally, since stopping an app involves unloading its AppDomain, the app is guaranteed to be cleaned up fully and none of its objects or event handlers can linger on after the app is stopped.

Communication with the IDE

When the IDE builds an app (workbook or extension), it sends a message to the runtime (via named pipe) with the location of the new app. The runtime then loads the app and starts it. For workbook apps, before sending the message, the IDE adds the app to the list of trusted workbook apps, in order to skip the permission prompt.

In the other direction, the runtime also sends messages to the IDE. Whenever a log message is generated by the runtime or by an app running on top of the runtime, the entry is collected for displaying in the runtime's log viewer, but it is also relayed to the IDE via a named pipe. The IDE will then also display the message and, if source location information is available, link it to a line of source code.

Installation

For developer machines, the runtime is installed together with the IDE as part of the full installer. For end user machines, the runtime is also available as a separate smaller installer (~4MB).

The runtime installer only supports per-user installation, so even if it is installed together with the IDE in a per-machine installation, the runtime will only be installed for the current user.

The installer unpacks the files of the runtime into the following folder: %appdata%\Windy Range Software d.o.o\QueryStorm runtime. In addition to unpacking the files, a new OPEN entry is added to the Computer\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Excel\Options key in the registry in order to instruct Excel to load the runtime add-in.

If the installation is successful, the runtime (QueryStorm.XLL Add-in) will appear in Excel addins, and the "Runtime" group will be visible in the QueryStorm tab in the ribbon.

Version (in)dependence

The runtime is designed to expose a minimal surface area to apps. Aside from a single dll that describes the contract between the runtime and apps (QueryStorm.Apps.Contract.dll), apps do not rely on the runtime for any other dll.

This minimal surface area ensures that apps built by one version of the IDE can be executed on almost any other version of the runtime.

The downside of this is that apps must carry all of the dlls they depend on and cannot rely on the runtime to supply any of them. This can result in workbooks that are up to a few MB larger than they otherwise would be, but the advantage is they will work on almost any version of the runtime.

Only on rare occasions when a type member in the contract dll is changed or removed will old apps need to be recompiled in order to work on a new version of the runtime. We do our best to ensure this happens very rarely.

Free to use

The runtime is completely free. It may be freely downloaded and distributed, though modification of the runtime is not allowed.