Class Session

An object encapsulating a Realm Object Server session. Sessions represent the communication between the client (and a local Realm file on disk), and the server (and a remote Realm at a given URL stored on a Realm Object Server). Sessions are always created by the SDK and vended out through various APIs. The lifespans of sessions associated with Realms are managed automatically.

Inheritance

Object

Session

Namespace: Realms.Sync

Assembly: Realm.dll

Syntax

public class Session

Properties

Path

Gets the on-disk path of the Realm file backing the Realm this Session represents.

Declaration

public string Path { get; }

Property Value

Type	Description
String	The file path.

ServerUri

Gets the Uri describing the remote Realm which this session connects to and synchronizes changes with.

Declaration

public Uri ServerUri { get; }

Property Value

Type	Description
Uri	The Uri where the Realm Object Server resides.

State

Gets the session’s current state.

Declaration

public SessionState State { get; }

Property Value

Type	Description
SessionState	An enum value indicating the state of the session.

User

Gets the User defined by the SyncConfigurationBase that is used to connect to the Realm Object Server.

Declaration

public User User { get; }

Property Value

Type	Description
User	The User that was used to create the Realm's SyncConfigurationBase.

Methods

GetProgressObservable(ProgressDirection, ProgressMode)

Gets an IObservable<T> that can be used to track upload or download progress.

Declaration

public IObservable<SyncProgress> GetProgressObservable(ProgressDirection direction, ProgressMode mode)

Parameters

Type	Name	Description
ProgressDirection	direction	The transfer direction (upload or download) to track in the subscription callback.
ProgressMode	mode	The desired behavior of this progress notification block.

Returns

Type	Description
IObservable<SyncProgress>	An observable that you can subscribe to and receive progress updates.

Remarks

To start receiving notifications, you should call Subscribe(IObserver<T>) on the returned object. The token returned from Subscribe(IObserver<T>) should be retained as long as progress notifications are desired. To stop receiving notifications, call Dispose() on the token. You don't need to keep a reference to the observable itself. The progress callback will always be called once immediately upon subscribing in order to provide the latest available status information.

Examples

class ProgressNotifyingViewModel
{
    private IDisposable notificationToken;

    public void ShowProgress()
    {
        var observable = session.GetProgressObservable(ProgressDirection.Upload, ProgressMode.ReportIndefinitely);
        notificationToken = observable.Subscribe(progress =>
        {
            // Update relevant properties by accessing
            // progress.TransferredBytes and progress.TransferableBytes
        });
    }

    public void HideProgress()
    {
        notificationToken?.Dispose();
        notificationToken = null;
    }
}

In this example we're using ObservableExtensions.Subscribe found in the Reactive Extensions class library. If you prefer not to take a dependency on it, you can create a class that implements IObserver<T> and use it to subscribe instead.

Reconnect()

Attempts to reconnect all sessions.

Declaration

public static void Reconnect()

Remarks

By default, the sync engine will attempt to reconnect sessions at incrementing intervals. This method is useful when you are monitoring connectivity yourself, using e.g. Connectivity Plugin or through the native connectivity API and you wish to cancel that delay and try to reconnect immediately.

Start()

Attempts to resume the session and enable synchronization with the Realm Object Server.

Declaration

public void Start()

Remarks

All sessions will be active by default and calling this method only makes sense if Stop() was called before that.

Stop()

Stops any synchronization with the Realm Object Server until the Realm is re-opened again after fully closing it.
Synchronization can be re-enabled by calling Start() again.

Declaration

public void Stop()

Remarks

If the session is already stopped, calling this method will do nothing.

WaitForDownloadAsync()

Waits for the Session to finish all pending downloads.

Declaration

public Task WaitForDownloadAsync()

Returns

Type	Description
Task	A Task that will be completed when all pending downloads for this Session are completed.

Exceptions

Type	Condition
InvalidOperationException	Thrown when a faulted session is waited on.

WaitForUploadAsync()

Waits for the Session to finish all pending uploads.

Declaration

public Task WaitForUploadAsync()

Returns

Type	Description
Task	A Task that will be completed when all pending uploads for this Session are completed.

Exceptions

Type	Condition
InvalidOperationException	Thrown when a faulted session is waited on.

Events

Error

Triggered when an error occurs on a session. The sender argument will be the session which has errored.

Declaration

public static event EventHandler<ErrorEventArgs> Error

Event Type

Type	Description
EventHandler<ErrorEventArgs>

Extension Methods

TestingExtensions.SimulateError(Session, ErrorCode, String, Boolean)