Skip to main content

Client API: Subscribing to Store Events

  • Events allow users to perform custom actions in response to operations made in a Document Store or a Session.

  • An event is invoked when the selected action is executed on an entity, or querying is performed.

  • Subscribing to an event at the DocumentStore level subscribes to this event in all subsequent sessions.

    E.g., to invoke an event after SaveChanges() is called by any subsequent session, use -
    store.OnAfterSaveChanges += OnAfterSaveChangesEvent;

  • Subscribing to an event in a Session is valid only for this session.

    E.g., to invoke an event after SaveChanges() is called by this session only, use -
    session.Advanced.OnAfterSaveChanges += OnAfterSaveChangesEvent;

    Read more about Session events here.

  • In this page:

Store Events​

You can subscribe to the following events only at the store level, not within a session.

OnBeforeRequest​

This event is invoked by sending a request to the server, before the request is actually sent.
It should be defined with this signature:

private void OnBeforeRequestEvent(object sender, BeforeRequestEventArgs args);

Parameters:

ParameterTypeDescription
senderIDocumentStore The subscribed store that triggered the event
argsBeforeRequestEventArgsSee details below

BeforeRequestEventArgs:

public class BeforeRequestEventArgs : EventArgs
{
  // Database Name
  public string Database { get; }
  // Database URL
  public string Url { get; }
  // The request intended to be sent to the server  
  public HttpRequestMessage Request { get; }
  // The number of attempts made to send the request to the server
  public int AttemptNumber { get; }
}
  • Example:
    To define a method that checks URLs sent in a document store request:
private void OnBeforeRequestEvent(object sender, BeforeRequestEventArgs args)
{
  var forbiddenURL = new Regex("/databases/[^/]+/docs");

  if (forbiddenURL.IsMatch(args.Url) == true)
  {
      // action to be taken if the URL is forbidden
  }
}

To subscribe to the event:

// Subscribe to the event
store.OnBeforeRequest += OnBeforeRequestEvent;

OnSucceedRequest​

This event is invoked by receiving a successful reply from the server.
It should be defined with this signature:

private void OnSucceedRequestEvent(object sender, SucceedRequestEventArgs args);

Parameters:

ParameterTypeDescription
senderIDocumentStore The subscribed store that triggered the event
argsSucceedRequestEventArgsSee details below

SucceedRequestEventArgs:

public class SucceedRequestEventArgs : EventArgs
{
  // Database Name
  public string Database { get; }
  // Database URL
  public string Url { get; }
  // The message returned from the server
  public HttpResponseMessage Response { get; }
  // The original request sent to the server
  public HttpRequestMessage Request { get; }
  // The number of attempts made to send the request to the server
  public int AttemptNumber { get; }
}
  • Example
    To define a method that would be activated when a request succeeds:
private void OnSucceedRequestEvent(object sender, SucceedRequestEventArgs args)
{
  if (args.Response.IsSuccessStatusCode == true)
  {
      // action to be taken after a successful request
  }
}

To subscribe to the event:

// Subscribe to the event
store.OnSucceedRequest += OnSucceedRequestEvent;

AfterDispose​

This event is invoked immediately after a document store is disposed of.
It should be defined with this signature:

private void AfterDisposeEvent(object sender, EventHandler args);

Parameters:

ParameterTypeDescription
senderIDocumentStore The subscribed store whose disposal triggered the event
argsEventHandlerargs has no contents for this event

BeforeDispose​

This event is invoked immediately before a document store is disposed of.
It should be defined with this signature:

private void BeforeDisposeEvent(object sender, EventHandler args);

Parameters:

ParameterTypeDescription
senderIDocumentStore The subscribed store whose disposal triggered the event
argsEventHandlerargs has no contents for this event

RequestExecutorCreated​

This event is invoked when a Request Executor is created, allowing you to subscribe to various events of the request executor.
It should be defined with this signature:

private void RequestExecutorCreatedEvent(object sender, RequestExecutor args);

Parameters:

ParameterTypeDescription
senderIDocumentStore The subscribed store that triggered the event
argsRequestExecutorThe created Request Executor instance

OnSessionCreated​

This event is invoked after a session is created, allowing you, for example, to change session configurations.
It should be defined with this signature:

private void OnSessionCreatedEvent(object sender, SessionCreatedEventArgs args);

Parameters:

ParameterTypeDescription
senderIDocumentStore The subscribed store that triggered the event
argsSessionCreatedEventArgsThe created Session

SessionCreatedEventArgs:

public class SessionCreatedEventArgs : EventArgs
{
  public InMemoryDocumentSessionOperations Session { get; }
}
  • Example
    To define a method that would be activated when a session is created:
private void OnSessionCreatedEvent(object sender, SessionCreatedEventArgs args)
{
      args.Session.MaxNumberOfRequestsPerSession = 100;
}

To subscribe to the event:

// Subscribe to the event
store.OnSessionCreated += OnSessionCreatedEvent;

OnFailedRequest​

This event is invoked before a request fails. It allows you, for example, to track and log failed requests.
It should be defined with this signature:

private void OnFailedRequestEvent(object sender, FailedRequestEventArgs args);

Parameters:

ParameterTypeDescription
senderIDocumentStore The subscribed store that triggered the event
argsFailedRequestEventArgsSee details below

FailedRequestEventArgs:

public class FailedRequestEventArgs : EventArgs
{
  // Database Name
  public string Database { get; }
  // Database URL
  public string Url { get; }
  // The exception returned from the server
  public Exception Exception { get; }
  // The message returned from the server
  public HttpResponseMessage Response { get; }
  // The original request sent to the server
  public HttpRequestMessage Request { get; }
}
  • Example
    To define a method that would be activated when a request fails:
private void OnFailedRequestEvent(object sender, FailedRequestEventArgs args)
{
  Logger($"Failed request for database '{args.Database}' ('{args.Url}')", args.Exception);
}

To subscribe to the event:

// Subscribe to the event
store.OnFailedRequest += OnFailedRequestEvent;

OnTopologyUpdated​

This event is invoked by a topology update (e.g. when a node is added), after the topology is updated.
It should be defined with this signature:

private void OnTopologyUpdatedEvent(object sender, TopologyUpdatedEventArgs args);

Parameters:

ParameterTypeDescription
senderIDocumentStore The subscribed store that triggered the event
argsTopologyUpdatedEventArgsThe updated list of nodes

TopologyUpdatedEventArgs:

public class TopologyUpdatedEventArgs : EventArgs
{
  public Topology Topology { get; }
}

Topology:
public class Topology { public long Etag; public List<ServerNode> Nodes; }

  • Example
    To define a method that would be activated on a topology update:
void OnTopologyUpdatedEvent(object sender, TopologyUpdatedEventArgs args)
{
  var topology = args.Topology;
  if (topology == null)
      return;
  for (var i = 0; i < topology.Nodes.Count; i++)
  {
      // perform relevant operations on the nodes after the topology was updated
  }
}

To subscribe to the event:

// Subscribe to the event
store.OnTopologyUpdated += OnTopologyUpdatedEvent;

Store/Session Events​

You can subscribe to the following events both at the store level and in a session.

  • Subscribing to an event in a session limits the scope of the subscription to this session.
  • When you subscribe to an event at the store level, the subscription is inherited by all subsequent sessions.