Client Resets - .NET SDK

Recover Unsynced Local Changes

In a client reset that does not involve a breaking schema change, the SDK integrates objects created locally that did not sync before the client reset. The following rules determine how conflicts are resolved when both the backend and the client make changes to the same object:

• If an object is deleted on the server, but is modified on the recovering client, the delete takes precedence and the client discards the update.

• If an object is deleted on the recovering client, but not the server, then the client applies the delete instruction.

• In the case of conflicting updates to the same field, the client update is applied.

There are two client reset handlers that try to automatically recover the unsycned local data: RecoverOrDiscardUnsyncedChangesHandler and RecoverUnsyncedChangesHandler.

var conf = new FlexibleSyncConfiguration(user)
{
    ClientResetHandler = new RecoverOrDiscardUnsyncedChangesHandler
    {
        // The following callbacks are optional
        OnBeforeReset = (beforeReset) =>
        {
            // Executed before the client reset begins
            // Can be used to notify the user that a reset is going
            // to happen
        },
        OnAfterRecovery = (beforeReset, afterReset) =>
        {
            // Executed after the client reset is complete
            // Can be used to notify the user that the reset is done
        },
        OnAfterDiscard = (beforeReset, afterReset) =>
        {
            // Executed if the automatic recovery has failed
            // but the DiscardUnsyncedChanges fallback has completed
            // successfully
        },
        ManualResetFallback = (err) =>
        {
            // Automatic reset failed; handle the reset manually here
        }
    }
};

var conf = new FlexibleSyncConfiguration(user)
{
    ClientResetHandler = new RecoverUnsyncedChangesHandler
    {
        // The following callbacks are optional
        OnBeforeReset = (beforeReset) =>
        {
            // Executed before the client reset begins
            // Can be used to notify the user that a reset is going
            // to happen
        },
        OnAfterReset = (beforeReset, afterReset) =>
        {
            // Executed after the client reset is complete
            // Can be used to notify the user that the reset is done
        },
        ManualResetFallback = (err) =>
        {
            // Automatic reset failed; handle the reset manually here
        }
    }
};

Discard Unsynced Changes

This strategy permanently deletes all local unsynced changes made since the last successful sync. If you choose to use a DiscardUnsyncedChangesHandler, the SDK restores your local realm file to a syncable state without closing the realm and while keeping notifications fully working. If this process fails, it falls back to a manual reset strategy explained in the Manual Recovery section. This handler provides the following callback methods:

• OnBeforeReset, which the SDK invokes prior to the client reset. You can use this callback to notify the user before the reset begins.

• OnAfterReset, which the SDK invokes if and only if the reset completes successfully. You can use it to notify the user when the reset is complete.

• ManualResetFallback, which the SDK invokes if the reset fails. Your logic here should be similar to that described for a ManualRecoveryHandler.

The following example shows how you might implement a DiscardUnsyncedChangesHandler:

{
    var config = new FlexibleSyncConfiguration(user);
    config.ClientResetHandler = new DiscardUnsyncedChangesHandler()
    {
        // The following callbacks are optional
        OnBeforeReset = (beforeReset) =>
        {
            // Executed before the client reset begins
            // Can be used to notify the user that a reset is going
            // to happen
        },
        OnAfterReset = (beforeReset, afterReset) =>
        {
            // Executed after the client reset is complete
            // Can be used to notify the user that the reset is done
        },
        ManualResetFallback = (err) =>
        {
            // Automatic reset failed; handle the reset manually here
        }
    };
    try
    {
        var realm = await Realm.GetInstanceAsync(config);
    }
    catch (Exception ex)
    {
        Console.WriteLine($@"Error creating or opening the
            realm file. {ex.Message}");
    }

Manual Recovery

In most cases, you should use one of the other strategies for client resets. For those infrequent cases where you need to customize your data recovery process, select the ManualRecoveryHandler handler.

Within the ManualRecoveryHandler, you dispose the existing realm, and then call the InitiateClientReset() method.

The following example demonstrates implementing the ManualRecoveryHandler:

private void SetupRealm()
{
    var config = new FlexibleSyncConfiguration(user);
    config.ClientResetHandler =
        new ManualRecoveryHandler(HandleClientResetError);
    var realm = await Realm.GetInstanceAsync(config);
}

private void HandleClientResetError(ClientResetException clientResetException)
{
    Console.WriteLine($"Client Reset requested: {clientResetException.Message}");

    // Prompt user to perform a client reset immediately. If they don't,
    // they won't receive any data from the server until they restart the app
    // and all changes they make will be discarded when the app restarts.
    var didUserConfirmReset = ShowUserAConfirmationDialog();
    if (didUserConfirmReset)
    {
        // Close the Realm before doing the reset. It must be 
        // deleted as part of the reset.
        fsRealm.Dispose();

        // perform the client reset
        var didReset = clientResetException.InitiateClientReset();
        if (didReset)
        {
            // Navigate the user back to the main page or reopen the
            // the Realm and reinitialize the current page
        }
        else
        {
            // Reset failed - notify user that they'll need to
            // update the app
        }
    }
}

Test Client Reset Handling

You can manually test your application's client reset handling by terminating and re-enabling Device Sync.

When you terminate and re-enable Sync, clients that have previously connected with Sync are unable to connect until after they perform a client reset. Terminating Sync deletes the metadata from the server that allows the client to synchronize. The client must download a new copy of the realm from the server. The server sends a client reset error to these clients. So, when you terminate Sync, you trigger the client reset condition.

To test client reset handling:

1. Write data from a client application and wait for it to synchronize.

2. Terminate and re-enable Device Sync.

3. Run the client app again. The app should get a client reset error when it tries to connect to the server.