Class SubscriptionSet

A collection representing the set of active subscriptions for a Realm instance. This is used in combination with FlexibleSyncConfiguration to declare the set of queries you want to synchronize with the server. You can access and read the subscription set freely, but mutating it must happen in an Update(Action) block.

Inheritance

object

SubscriptionSet

Implements

IReadOnlyList<Subscription>

IReadOnlyCollection<Subscription>

IEnumerable<Subscription>

IEnumerable

Namespace: Realms.Sync

Assembly: Realm.dll

Syntax

public class SubscriptionSet : IReadOnlyList<Subscription>, IReadOnlyCollection<Subscription>, IEnumerable<Subscription>, IEnumerable

Remarks

Any changes to the subscription set will be persisted locally and be available the next time the application starts up - i.e. it's not necessary to subscribe for the same query every time. Updating the subscription set can be done while offline, and only the latest update will be sent to the server whenever connectivity is restored.
It is strongly recommended that you batch updates as much as possible and request the dataset your application needs upfront. Updating the set of active subscriptions for a Realm is an expensive operation serverside, even if there's very little data that needs downloading.

Properties

| Edit this page View Source

Count

Gets the number of elements in the collection.

Declaration

public int Count { get; }

Property Value

Type	Description
int	The number of elements in the collection.

| Edit this page View Source

Error

Gets the error associated with this subscription set, if any. This will only be non-null if State is Error.

Declaration

public Exception? Error { get; }

Property Value

Type	Description
Exception	The Exception that provides more details for why the subscription set was rejected by the server.

| Edit this page View Source

this[int]

Gets the Subscription at the specified index in the set.

Declaration

public Subscription this[int index] { get; }

Parameters

Type	Name	Description
int	index	The zero-based index of the element to get.

Property Value

Type	Description
Subscription	The Subscription at the specified index in the set.

| Edit this page View Source

State

Gets the state of the subscription set.

Declaration

public SubscriptionSetState State { get; }

Property Value

Type	Description
SubscriptionSetState	The subscription set's state.

Methods

| Edit this page View Source

Add<T>(IQueryable<T>, SubscriptionOptions?)

Adds a query to the set of active subscriptions. The query will be joined via an OR statement with any existing queries for the same type.

Declaration

public Subscription Add<T>(IQueryable<T> query, SubscriptionOptions? options = null) where T : IRealmObject

Parameters

Type	Name	Description
IQueryable<T>	query	The query that will be matched on the server.
SubscriptionOptions	options	The subscription options controlling the name and/or the type of insert that will be performed.

Returns

Type	Description
Subscription	The subscription that represents the specified query.

Type Parameters

Name	Description
T	The type of objects in the query results.

Remarks

Adding a query that already exists is a no-op and the existing subscription will be returned.

| Edit this page View Source

Find(string)

Finds a subscription by name.

Declaration

public Subscription? Find(string name)

Parameters

Type	Name	Description
string	name	The name of the subscription.

Returns

Type	Description
Subscription	A Subscription instance where Name is equal to `name` if the subscription set contains a subscription with the provided name; `null` otherwise.

| Edit this page View Source

Find<T>(IQueryable<T>)

Finds a subscription by query.

Declaration

public Subscription? Find<T>(IQueryable<T> query) where T : IRealmObject

Parameters

Type	Name	Description
IQueryable<T>	query	The query describing the subscription.

Returns

Type	Description
Subscription	A Subscription instance where Query matches the provided `query`; `null` if the subscription set doesn't contain a match.

Type Parameters

Name	Description
T	The type of objects in the query.

| Edit this page View Source

Remove(Subscription)

Removes the provided subscription from this subscription set.

Declaration

public bool Remove(Subscription subscription)

Parameters

Type	Name	Description
Subscription	subscription	The subscription to remove.

Returns

Type	Description
bool	`true` if the subscription existed in this subscription set and was removed; `false` otherwise.

| Edit this page View Source

Remove(string)

Removes a subscription with the specified name.

Declaration

public bool Remove(string name)

Parameters

Type	Name	Description
string	name	The name of the subscription to remove.

Returns

Type	Description
bool	`true` if the subscription existed in this subscription set and was removed; `false` otherwise.

| Edit this page View Source

RemoveAll(bool)

Removes all subscriptions from this subscription set.

Declaration

public int RemoveAll(bool removeNamed = false)

Parameters

Type	Name	Description
bool	removeNamed	A flag indicating whether to also remove named subscriptions. Default is false.

Returns

Type	Description
int	The number of subscriptions that existed in the set and were removed.

| Edit this page View Source

RemoveAll(string, bool)

Removes all subscriptions for the provided className.

Declaration

public int RemoveAll(string className, bool removeNamed = false)

Parameters

Type	Name	Description
string	className	The name of the type whose subscriptions are to be removed.
bool	removeNamed	A flag indicating whether to also remove named subscriptions. Default is false.

Returns

Type	Description
int	The number of subscriptions that existed for this type and were removed.

| Edit this page View Source

RemoveAll<T>(bool)

Removes all subscriptions for a specified type.

Declaration

public int RemoveAll<T>(bool removeNamed = false) where T : IRealmObject

Parameters

Type	Name	Description
bool	removeNamed	A flag indicating whether to also remove named subscriptions. Default is false.

Returns

Type	Description
int	The number of subscriptions that existed for this type and were removed.

Type Parameters

Name	Description
T	The type of objects whose subscriptions should be removed.

| Edit this page View Source

Remove<T>(IQueryable<T>, bool)

Removes a subscription with the specified query.

Declaration

public int Remove<T>(IQueryable<T> query, bool removeNamed = false) where T : IRealmObject

Parameters

Type	Name	Description
IQueryable<T>	query	The query whose matching subscription should be removed.
bool	removeNamed	A flag indicating whether to also remove named subscriptions. Default is false.

Returns

Type	Description
int	`true` if the subscription existed in this subscription set and was removed; `false` otherwise.

Type Parameters

Name	Description
T	The type of objects in the query results.

| Edit this page View Source

Update(Action)

Update the subscription set and send the request to the server in the background.

Declaration

public void Update(Action action)

Parameters

Type	Name	Description
Action	action	Action to execute, adding or removing subscriptions to this set.

Remarks

Calling Update(Action) is a prerequisite for mutating the subscription set - e.g. by calling Add<T>(IQueryable<T>, SubscriptionOptions?), Remove(Subscription), or RemoveAll(bool).
Calling this may update the content of this SubscriptionSet - e.g. if another Update(Action) was called on a background thread or if the State changed.
If you want to wait for the server to acknowledge and send back the data that matches the updated subscriptions, use WaitForSynchronizationAsync(CancellationToken?).

| Edit this page View Source

WaitForSynchronizationAsync(CancellationToken?)

Waits for the server to acknowledge the subscription set and return the matching objects.

Declaration

public Task WaitForSynchronizationAsync(CancellationToken? cancellationToken = null)

Parameters

Type	Name	Description
CancellationToken?	cancellationToken	An optional cancellation token that can be used to cancel the wait operation.

Returns

Type	Description
Task	An awaitable task, whose successful completion indicates that the server has processed the subscription change and has sent all the data that matches the new subscriptions.

Remarks

If the State of the subscription set is Complete the returned Task will complete immediately. If the State is Error, the returned task will be immediately rejected with an error.
If the change results in removing objects from the Realm - e.g. because subscriptions have been removed, then those objects will have been removed prior to the returned task completing.

Implements

IReadOnlyList<T>

IReadOnlyCollection<T>

IEnumerable<T>

IEnumerable