# .NET

Source: https://docs.interop.io/desktop/capabilities/app-preferences/net/index.html

## 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:

```csharp
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:

```csharp
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:

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

## Set

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:

```csharp
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`:

```csharp
var request = new PreferenceSetRequest
{
    Clear = true
};

await io.Preferences.Set(request);
```

## Subscribe

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:

```csharp
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:

```csharp
class MyAppPrefs
{
    int FontSize;
};

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