How to work with local storage

In this article and its corresponding video, we will explain what local storage is and how it can be used in your cTrader algos. We will also provide useful examples and explain how local storage scope works.

Why use local storage

There are many cases when you want your algo to save something to or access something from the local file system. For example, you may want to save a log of all cBot operations. However, this usually requires the algo to have elevated access rights (AccessRights.FullAccess), which is less than ideal for users. If an algo requests a user to provide elevated permissions, the user is much less likely to trust the algo, especially if it is distributed without its source code. Local storage is a convenient way to safely access the local file system without introducing any security concerns. Using local storage allows developers to keep the access rights of their algos set to AccessRights.None.

Saving strings in local storage

Every type of cTrader algo has a LocalStorage property that allows for executing read and write operations. To demonstrate how local storage works, we will create a new cBot. In its OnStart handler, we will use the LocalStorage.SetString(string key, string value) method. As you can see, it takes two arguments, namely a key under which information should be saved and the value to be saved.

LocalStorage.SetString("Message", Message);

To retrieve the value, we will use the GetString(string key) method in the OnTick handler of the cBot.

Print(LocalStorage.GetString("Message"));

As long as Message is not null, we can build the cBot and see the retrieved value being correctly printed in the log.

Saving objects in local storage

Beyond string, you can use local storage to save any kind of object. Behind the scenes, cTrader serialises and deserialises objects in local storage which allows for sharing any kind of data. To demonstrate this, we can create a new class to store information, save it and later retrieve it. We will name this class Signal.

class Signal
{
    public TradeType TradeType { get; set; }
    public double SL { get; set; }
    public double TP { get; set; }
}

In the OnStart() method, we will create a new instance of this class and initialise its properties.

var signal = new Signal{
    TradeType = TradeType.Sell,
    SL = 50,
    TP = 50,
};

We will use the SetObject(string key, Object object) method to save and retrieve the account balance.

protected override void OnStart()
{
    var signal = new Signal{
    TradeType = TradeType.Sell,
    SL = 50,
    TP = 50,
    };        

    LocalStorage.SetString("Message",Message);
    LocalStorage.SetObject("Signal 1", signal);
}

protected override void OnTick()
{
Print(LocalStorage.GetString("Message")); 

var signal = LocalStorage.GetObject<Signal>("Signal 1"); 
Print(signal.TradeType);
Print(signal.SL);
Print(signal.TP);
}

If we build our cBot and launch it, we should see the correct values being printed in the log.

Scopes of local storage

When using local storage you can also define the scope in which the saved values are exposed for future retrieval. There are three different scopes available:

Instance scope - saved values are only available to a specific instance.
Type scope - saved values are available to all instances of a specific algorithm.
Device scope - saved values are available to all algorithms regardless of their types.

Here is how using instance scope could look like.

[Parameter()]
public bool IsWriter { get; set; }


protected override void OnStart()
{   
    if(IsWriter)
    { 
        LocalStorage.SetString("Message",Message, LocalStorageScope.Instance);
    }
}

protected override void OnTick()
{        
    if(!IsWriter)
    {
        if(LocalStorage.GetString("Message") != string.Empty)
            Print(LocalStorage.GetString("Message"));
    }
}

Note that we have explicitly specified the scope in the SetString() method.

We can add several instances of this cBot and configure them so that one writes to local storage while another one retrieves information. In this case, reading information should be impossible. However, if just one instance is set up to execute both write and read operations, the cBot should work as intended.

Here is an example of using type scope.

protected override void OnStart()
{   
    if(IsWriter)
    {             
        LocalStorage.SetString("Message",Message, LocalStorageScope.Type);
    }
}

protected override void OnTick()
{        
    if(!IsWriter)
    {
        if(LocalStorage.GetString("Message", LocalStorageScope.Type) != string.Empty)
            Print(LocalStorage.GetString("Message"));
    }
}

If we create two instances of this bot and set them up so that one instance writes to local storage and another reads the saved value, everything should work without raising any errors.

Last but not least, device scope allows for exchanging information between different algos. Here is an example of using this scope type.

protected override void OnStart()
{   
    if(IsWriter)
    {             
        LocalStorage.SetString("Message",Message, LocalStorageScope.Device);
    }
}

protected override void OnTick()
{        
    if(!IsWriter)
    {
        if(LocalStorage.GetString("Message", LocalStorageScope.Device) != string.Empty)
            Print(LocalStorage.GetString("Message"));
    }
}

We can build several cBots that all use the same code. If we set them up correctly, one cBot can save information to local storage while another one retrieves it. As long as the scope is equal to LocalStorageScope.Device, our system should work as intended.

Using `Flush()` and `Reload()` methods

If you want to share information between several instances of cTrader, call the Flush() and Reload() methods.

protected override void OnStart()
{   
    if(IsWriter)
    {             
        LocalStorage.SetString("Message",Message, LocalStorageScope.Device);
        LocalStorage.Flush(LocalStorageScope.Device);
    }
}

protected override void OnTick()
{        
    if(!IsWriter)
    {
        LocalStorage.Reload(LocalStorageScope.Device);
        if(LocalStorage.GetString("Message", LocalStorageScope.Device) != string.Empty)
            Print(LocalStorage.GetString("Message"));
    }
}

If we build several cBots with this code and conduct an experiment to share information between different instances of cTrader, we will see that our saved values are persisted as intended.