TrakHound Docs TrakHound Framework Volumes & Variables

Volumes & Variables

Scoped file storage and key/value settings available to every module.
Framework Docs Menu

Every module is given a Volume for files and a collection of Variables for simple settings. Both are available as properties (Volume and Variables) on API controllers, Functions, Workers, App components, and Identity providers.

Reports Function & Reports API
Volume reportsShared, because both configurations set volumeId: reports
VariablesEach module's own small values, ex. lastRun
Machines Worker
Volume machinesIts own files, ex. settings it watches with CreateListener
VariablesKept across restarts
Not the same as Configuration Variables Set by an administrator under Config > Variables and shared by every configuration as ${name} (see Configuration & Deployments)
Volumes hold files; Variables hold small values a module remembers. For data other modules use, write to a Service instead.

Volumes

A Volume is a scoped storage area. Each module configuration chooses its Volume with volumeId, so modules can keep their files separate or share a Volume when they need to work with the same files. Volumes are stored in the Instance's volume directory (see Instances).

// Write and read a JSON file
await Volume.WriteJson("settings/options.json", options);
var saved = await Volume.ReadJson<MyOptions>("settings/options.json");

// List files
var files = await Volume.ListFiles("reports", includeSubdirectories: true);

Volume Methods

MethodDescription
ListDirectories(path, includeSubdirectories)List directories.
ListFiles(path, includeSubdirectories)List files.
CreateFile(path)Create an empty file.
ReadString, ReadJson<T>, ReadBytes, ReadStreamRead a file.
WriteString, WriteJson, WriteBytes, WriteStreamWrite a file.
DeleteFile(path), DeleteDirectory(path)Delete a file or directory.
CreateListener(path, filter)Create a listener that raises notifications when files in the Volume are created, modified, or deleted.

Variables

Variables are a simple key/value collection for settings that a module needs to remember, stored as a JSON file on the Instance. They belong to one module, and are different from Configuration Variables, which are values set by an administrator and shared by every configuration in a profile.

await Variables.Set("lastRun", DateTime.UtcNow);

var lastRun = await Variables.ReadString("lastRun");
MethodDescription
Set(key, value)Set the value of a Variable.
Read(key)Read the value of a Variable as an object.
ReadString(key)Read the value of a Variable as a string.
Use Variables for small settings and state. For shared or larger data, use Services such as Key-Values, Blobs, or Tables.

Both a module's Volume and its Variables can be copied to other Instances in a Deployment, for settings a Package keeps there.