Custom User Data - .NET SDK

On this page

Overview

Read a User's Custom User Data
Create a User's Custom User Data Document
Update a User's Custom Data
Delete a User's Custom Data

Atlas Device SDKs are deprecated. Refer to the deprecation page for details.

Overview

You can store arbitrary custom user data about your users in realm. For example, you might store a user's preferred language, date of birth, or local timezone. Before writing and reading this data, you must enable custom user data in the backend. To learn more, see Enable Custom User Data.

Important

To use custom user data, you must first Enable Custom User Data.

To create, update, or delete custom user data, you will need the following information from your custom user data configuration:

The custom user data cluster
The custom user data database
The collection in which custom user data documents are stored
The user ID field used to map custom user data documents to users (via user ID)

You can find this information in the App Services UI. In the left sidebar, click App Users, and then select the Custom User Data tab.

Read a User's Custom User Data

You retrieve custom user data by calling the GetCustomData() method on the User object of a logged in user:

await user.RefreshCustomDataAsync();
// Tip: define a class that represents the custom data
// and use the gerneic overload of GetCustomData<>()
var customUserData = user.GetCustomData<CustomUserData>();
Console.WriteLine($"User has pets: {customUserData.HasPets}");
Console.WriteLine($"User's favorite color is {customUserData.FavoriteColor}");
Console.WriteLine($"User's timezone is {customUserData.LocalTimeZone}");

Warning

Custom Data May Be Stale

App Services does not dynamically update the value of the CustomData immediately when underlying data changes. Instead, App Services fetches the most recent version of custom user data whenever a user refreshes their access token or when you explicitly call the RefreshCustomDataAsync() method, which ensures your app has the latest custom user data.

Create a User's Custom User Data Document

To create custom user data for a user, create a MongoDB document in the custom user data collection. The user ID field of the document must contain the the user's user ID. The following example uses MongoDB Data Access to insert a document containing the user ID of the currently logged in user and several custom properties into the custom user data collection:

app = App.Create(myRealmAppId);
user = await app.LogInAsync(Credentials.Anonymous());
mongoClient = user.GetMongoClient("mongodb-atlas");
dbTracker = mongoClient.GetDatabase("tracker");
userDataCollection = dbTracker.GetCollection<CustomUserData>("user_data");
var cud = new CustomUserData(user.Id)
{
    FavoriteColor = "pink",
    LocalTimeZone = "+8",
    HasPets = true
};
var insertResult = await userDataCollection.InsertOneAsync(cud);

You may find it helpful to create a C# class (POCO) that represents the custom user data object. The SDK will serialize/deserialize this class to and from BSON when writing, reading, and updating properties. The example above uses the following class to map the properties:

public class CustomUserData
{
    public string _id { get; private set; }
    public string _partition { get; private set; }
    public string FavoriteColor { get; set; }
    public string LocalTimeZone { get; set; }
    public bool HasPets { get; set; }
    public CustomUserData(string id, string partition = "myPart")
    {
        this._id = id;
        this._partition = partition;
    }
}

Update a User's Custom Data

Updating custom user data uses the same code as writing. The following example finds and updates the data by using the UpdateOneAsync() method, and then refreshes the data to ensure the latest changes are available:

var updateResult = await userDataCollection.UpdateOneAsync(
    new BsonDocument("_id", user.Id),
    new BsonDocument("$set", new BsonDocument("HasPets", false)));
await user.RefreshCustomDataAsync();
var customUserData = user.GetCustomData<CustomUserData>();
Console.WriteLine($"User has pets: {customUserData.HasPets}");
Console.WriteLine($"User's favorite color is {customUserData.FavoriteColor}");
Console.WriteLine($"User's timezone is {customUserData.LocalTimeZone}");

Delete a User's Custom Data

Deleting custom user data uses the same approach as writing and updating. The following example finds and deletes the data by using the DeleteOneAsync() method:

var deleteResult = await userDataCollection.DeleteOneAsync(
    new BsonDocument("_id", user.Id));
// The `DeletedCount` should be 1
Console.WriteLine(deleteResult.DeletedCount);
// There should no longer be a custom user document for the user
var customData = await userDataCollection.FindOneAsync(
    new BsonDocument("_id", user.Id));
Console.WriteLine(customData == null);

Back

Authenticate Users

User Metadata