App Preferences

Overview

The App Preferences API is accessible via the io.Preferences object.

Get

To retrieve the stored app preferences for an app, use the Get() method and pass as an argument the app name as defined in the io.Connect framework:

AppPrefs prefs = await io.Preferences.Get("my-app");

The AppPrefs object has the following properties:

Property	Type	Description
`App`	`string`	The name of the app with which the stored preferences are associated.
`Data`	`Value`	The stored app preferences.
`LastUpdate`	`DateTime`	Timestamp of the last update of the app preferences.

The Get() method has a typed overload which you can use to retrieve typed app preferences:

class MyAppPrefs
{
    int FontSize;
};

var prefs = await io.Preferences.Get<MyAppPrefs>("my-app");

To retrieve a list of the stored app preferences for all apps of the current user, use the GetAll() method:

AppPrefs[] prefs = await io.Preferences.GetAll();

To set the preferences for an app, use the Set() method and pass a PreferenceSetRequest object as an argument. Use the Merge Boolean property to specify whether the provided preferences will be merged with the existing ones or will replace them entirely:

var request = new PreferenceSetRequest
{
    App = "my-app",
    Data = new { FontSize = 18 },
    // The provided app preferences will replace the existing ones.
    Merge = false
};

await io.Preferences.Set(request);

The PreferenceSetRequest object has the following properties:

Property	Type	Description
`App`	`string`	The name of the app whose preferences to set.
`Data`	`object`	Object holding the preferences to set.
`Merge`	`bool`	If `true` (default), will merge the provided preferences with the existing ones overwriting the values of the already existing top-level properties in the preferences object. If `false`, the provided preferences will entirely replace the existing ones.
`Clear`	`bool`	If `true`, will clear the existing app preferences. Defaults to `false`.

Clear

To clear the preferences for an app, use the Set() method and pass a PreferenceSetRequest object as an argument with a Clear property set to true:

var request = new PreferenceSetRequest
{
    Clear = true
};

await io.Preferences.Set(request);

To retrieve a current snapshot of the preferences for an app and subscribe for future updates, use the GetAndSubscribe() method. Pass the app name as defined in the io.Connect framework and a callback function for handling the event:

IDisposable subscription = await io.Preferences.GetAndSubscribe(
    "my-app",
    (prefs) =>
    {
        Console.WriteLine($"The preferences for app {prefs.App} were last updated at {prefs.LastUpdate}.");
    }
);

// Closing the subscription.
subscription.Dispose();

Upon successful subscription, the GetAndSubscribe() method returns a subscription object of type IDisposable. Use its Dispose() method to stop receiving update notifications.

The GetAndSubscribe() method has a typed overload which you can use to retrieve and subscribe for typed app preferences:

class MyAppPrefs
{
    int FontSize;
};

await io.Preferences.GetAndSubscribe<MyAppPrefs>(
    "my-app",
    (prefs) =>
    {
        Console.WriteLine($"App preference for font size changed to {prefs.FontSize}.");
    }
);