# Volumes & Variables

> Scoped file storage and key/value settings available to every module.

URL: https://www.trakhound.com/docs/trakhound-framework/volumes-and-variables

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.

Diagram: Two modules each have their own Variables. The Reports Function and Reports API share the reports Volume because their configurations use the same volumeId, while the Machines Worker has its own Volume. Configuration Variables are separate: they are set by an administrator and shared by every configuration.

## 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](https://www.trakhound.com/docs/trakhound-framework/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

| Method | Description |
| --- | --- |
| `ListDirectories(path, includeSubdirectories)` | List directories. |
| `ListFiles(path, includeSubdirectories)` | List files. |
| `CreateFile(path)` | Create an empty file. |
| `ReadString`, `ReadJson<T>`, `ReadBytes`, `ReadStream` | Read a file. |
| `WriteString`, `WriteJson`, `WriteBytes`, `WriteStream` | Write 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](https://www.trakhound.com/docs/trakhound-framework/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");
```

| Method | Description |
| --- | --- |
| `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](https://www.trakhound.com/docs/trakhound-framework/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](https://www.trakhound.com/docs/trakhound-framework/configuration#package-data), for settings a Package keeps there.
