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:

Parameter Type Description
sender IDocumentStore The subscribed store that triggered the event
args BeforeRequestEventArgs See 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:

Parameter Type Description
sender IDocumentStore The subscribed store that triggered the event
args SucceedRequestEventArgs See 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:

Parameter Type Description
sender IDocumentStore The subscribed store whose disposal triggered the event
args EventHandler args 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:

Parameter Type Description
sender IDocumentStore The subscribed store whose disposal triggered the event
args EventHandler args 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:

Parameter Type Description
sender IDocumentStore The subscribed store that triggered the event
args RequestExecutor The 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:

Parameter Type Description
sender IDocumentStore The subscribed store that triggered the event
args SessionCreatedEventArgs The 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:

Parameter Type Description
sender IDocumentStore The subscribed store that triggered the event
args FailedRequestEventArgs See 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:

Parameter Type Description
sender IDocumentStore The subscribed store that triggered the event
args TopologyUpdatedEventArgs The updated list of nodes

TopologyUpdatedEventArgs:

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

Topology:
public class Topology { public long Etag; public List 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.