SubscribeAsync #

Subscribes by providing a set of filters: messages, document changes and, optionally, user events matching the provided filters will generate real-time notifications, sent to you in real-time by Kuzzle.

Arguments #

public async Task<string> SubscribeAsync(
        string index,
        string collection,
        JObject filters,
        NotificationHandler handler,
        SubscribeOptions options = null);

Argument	Type	Description
`index`	string	Index name
`collection`	string	Collection name
`filters`	JObject	JObject representing a set of filters following Koncorde syntax
`listener`	NotificationHandler	Listener function to handle notifications
`options`	SubscribeOptions (`null`)	Subscription options

listener #

Listener function that will be called each time a new notification is received. The listener will receive a Response as only argument.

options #

Additional subscription options.

Property	Type (default)	Description
`scope`	string (`all`)	Subscribes to document entering or leaving the scope Possible values: `all`, `in`, `out`, `none`
`users`	string (`none`)	Subscribes to users entering or leaving the room Possible values: `all`, `in`, `out`, `none`
`subscribeToSelf`	bool (`true`)	Subscribes to notifications fired by our own queries
`volatile`	JObject (`null`)	JObject representing subscription information, used in user join/leave notifications

Return #

The room ID.

Exceptions #

Throws a KuzzleException if there is an error. See how to handle error.

Usage #

Simple subscription to document notifications

NotificationHandler listener = (notification) => {
  string id = notification.Result["_id"]?.ToString();
  if (notification.Scope == "in") {
    Console.WriteLine($"Document {id} entered the scope");
  } else {
    Console.WriteLine($"Document {id} left the scope");
  }
};
try {
  // Subscribes to notifications for documents containing a 'name' property
  JObject filters = JObject.Parse("{ exists: 'name' }");
  await kuzzle.Realtime.SubscribeAsync(
    "nyc-open-data",
    "yellow-taxi",
    filters,
    listener);
  // Creates a document matching the provided filters
  await kuzzle.Document.CreateAsync(
    "nyc-open-data",
    "yellow-taxi",
    JObject.Parse("{ name: 'nina vkote', age: 19 }"),
    "nina-vkote");
} catch (KuzzleException e) {
  Console.WriteLine(e);
}

Subscription to document notifications with scope option

NotificationHandler listener = (notification) => {
  string scope = notification.Scope.ToString();
  if (scope == "out") {
    Console.WriteLine("Document left the scope");
  } else {
    Console.WriteLine($"Document moved {scope} the scope");
  }
};
try {
  // Subscribes to notifications when documents leave the scope
  JObject filters = JObject.Parse("{ range: { age: { lte: 20 } } }");
  SubscribeOptions options = new SubscribeOptions();
  options.Scope = "all";
  await kuzzle.Realtime.SubscribeAsync(
    "nyc-open-data",
    "yellow-taxi",
    filters,
    listener,
    options);
  // Creates a document which is in the scope
  await kuzzle.Document.CreateAsync(
    "nyc-open-data",
    "yellow-taxi",
    JObject.Parse("{ name: 'nina vkote', age: 19 }"),
    "nina-vkote");
  // Updates the document to make it leave the scope
  // we shall receive a notification
  await kuzzle.Document.UpdateAsync(
    "nyc-open-data",
    "yellow-taxi",
    "nina-vkote",
    JObject.Parse("{ age: 42 }"));
} catch (KuzzleException e) {
  Console.WriteLine(e);
}

Subscription to message notifications

NotificationHandler listener = (notification) => {
  Console.WriteLine("Message notification received");
  Console.WriteLine(notification.Result);
  /*
  {
  "_source": {
    "metAt": "Insane",
    "hello": "world",
    "_kuzzle_info": {
      "author": "-1",
      "createdAt": 1564474215073
    }
  },
  "_id": null
  } */
};
try {
  // Subscribes to notifications for documents
  await kuzzle.Realtime.SubscribeAsync(
    "i-dont-exist",
    "in-database",
    JObject.Parse("{}"), listener);
  JObject message = JObject.Parse("{ metAt: 'Insane', hello: 'world' }");
  await kuzzle.Realtime.PublishAsync("i-dont-exist", "in-database", message);
} catch (KuzzleException e) {
  Console.WriteLine(e);
}

Subscription to user notifications

NotificationHandler listener = (notification) => {
  int count = (int)notification.Result["count"];
  Console.WriteLine("Currently " + count + " users in the room");
  Console.WriteLine(notification.Volatile);
  // "{ "username": "nina vkote" }"
};
try {
  // Subscription to notifications sent whenever a user joins or leaves
  JObject filters = JObject.Parse("{ exists: 'name' }");
  SubscribeOptions options = new SubscribeOptions();
  options.Users = "all";
  await kuzzle.Realtime.SubscribeAsync(
    "nyc-open-data",
    "yellow-taxi",
    filters,
    listener,
    options);
  // Instantiates a second kuzzle client:
  //  multiple subscriptions made by the same user
  //  will not trigger "new user" notifications
  WebSocket ws2 = new WebSocket(new Uri("ws://kuzzle:7512"));
  Kuzzle kuzzle2 = new Kuzzle(ws2);
  await kuzzle2.ConnectAsync(CancellationToken.None);
  // Sets some volatile data
  SubscribeOptions options2 = new SubscribeOptions();
  options2.Volatile = JObject.Parse("{ username: 'nina vkote' }");
  // Subscribes to the same room with the second client
  await kuzzle2.Realtime.SubscribeAsync(
    "nyc-open-data",
    "yellow-taxi",
    filters,
    listener,
    options2);
} catch (KuzzleException e) {
  Console.WriteLine(e);
}

Edit this page on Github