Changes API: What is Changes API?

The RavenDB client offers a push notification feature that allows you to receive messages from a server about events that occurred there. You are able to subscribe to events for all documents or indexes as well as to indicate a particular one that you are interested in. This mechanism lets you notify users if something has changed without the need to do any expensive polling.

Accessing Changes API

The changes subscription is accessible by a document store. Depending on the type of the store you use (DocumentStore, ShardedDocumentStore or EmbeddableDocumentStore) you will get an appropriate instance which is an implementation of a common IDatabaseChanges interface.

IDatabaseChanges Changes(string database = null);

Connection Properties

IDatabaseChanges has three properties that are related to the server connection:

// represents the task responsible for establishing connection with the server
Task Task { get; }

// returns state of the connection
bool Connected { get; }

// the event raised if a connection state is changed
event EventHandler ConnectionStatusChanged

Subscriptions

In order to retrieve notifications, you have to subscribe to server-side events by using one of the following methods:

• ForAllDocuments
• ForAllIndexes
• ForAllReplicationConflicts
• ForAllTransformers
• ForBulkInsert
• ForDocument
• ForDocumentsInCollection
• ForDocumentsOfType
• ForDocumentsStartingWith
• ForIndex
• ForAllDataSubscriptions

Unsubscribing

In order to end a subscription (stop listening for particular notifications), you must Dispose it.

IDisposable subscription = store
	.Changes()
	.ForAllDocuments()
	.Subscribe(change => Console.WriteLine("{0} on document {1}", change.Type, change.Id));

try
{
	// application code here
}
finally
{
	if (subscription != null)
		subscription.Dispose();
}

Remarks