Skip to content

The data context

The data context represents the outside world to your scripts and apps. It exposes tables, variables, and events.

In scripts, user code gets direct accesses to the tables and variables exposed by the data context.

object explorer

Apps, on the other hand, usually interact with the data context via bindings. Component properties can bind to tables and variables, while methods can handle events coming from the data context.

data binding

Each project can define one or more data contexts.

Kinds of data contexts

Currently, QueryStorm supports two types of data context: WorkbookDataContext and CSVDataContext. Support for a GoogleSheetsDataContext is planned in the near future.

A WorkbookDataContext exposes tables, variables and events from the containing workbook. This type of data context can only be used inside a workbook app. In fact, workbook apps use a WorkbookDataContext by default, which is pre-configured in the project.config file in the DataContextTypes field of every new workbook project.

data context config setting

Extension apps, do not define a data context initially, but users are free to define one or more data contexts themselves.

When more than one data context is defined, a MergedDataContext instance will be used to combine them into a single data context. Scripts and apps will then be able to use the tables and variables from all of the defined contexts.

Defining a custom data context

Custom data contexts can be defined by creating a data context script inside your project.

creating data context

Inside the script you should define a class that implements IDataContext. The script is self-contained and cannot reference other code inside the project. This makes the script independent of the containing project, allowing it to be executed even if the rest of the code in the project does not compile. You can think of this script as a separate single-file project (which the containing project references).

When you run a data context script, instead of getting some value as a result, you will instead get a .dll file which will be placed in the lib\ folder of your project. This dll file contains your compiled data context class.

creating data context

Aside from producing that dll, the script also registers the data context in the DataContextTypes field of the project.config file.

creating data context

The reason for making this file a script rather than a regular .cs file is to allow you to define your data context independently of the rest of your project. This is important since the data context is used by three different parties:

  • scripts
  • app code
  • the strong-type dll generator

Scripts and the strong-type generator should not depend on the project, which is why the file is an independent script, rather than being a class that's part of the project.

Strongly-typed access to the data context (ORM)

Tables in the data context are exposed as implementations of the abstract base class Tabular. A Tabular is similar to an ADO.NET DataTable or a 2D object array. It provides access to tabular data, but it is not strongly typed access.

If you're only using SQL capabilities of QueryStorm, this is not a problem. SQL scripts internally use Tabular objects directly. However, if you are accessing tables from C# or VB.NET code, strongly typed access is much more convenient.

That's why QueryStorm projects automatically generate an additional .dll file that contains classes for strongly typed access to the data context. Each time the data context is changed such that e.g. a table or a column is added or removed, the dll is automatically recreated. The dll is placed inside the lib\ folder and has the following name structure: context_types.{hash}.dll.

This .dll is what enables C# scripts and app classes to have strongly typed access to data exposed by the data context.

The strongly typed wrappers are generated based on information that is present in the data context. Since Excel does not provide a mechanism for specifying column types or table relations, the default WorkbookDataContext has to guess the column types and does not set up any relations out of the box. However, users can use the data context script to specify exact column types as well as to define navigation properties based on table relations.

creating data context