Skip to main content

Client API: Subscribing to Store Events

Store events​

You can subscribe to the following events only at the store level, not within a session.
Subscribe to the request and topology events (OnBeforeRequest, OnSucceedRequest, OnFailedRequest, and OnTopologyUpdated) before you call store.Initialize().

OnBeforeRequest​

This event is invoked by sending a request to the server, before the request is actually sent.
See its arguments in the Syntax section below.

private void OnBeforeRequestEvent(object sender, BeforeRequestEventArgs args);

Example: block requests to a forbidden URL​

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
    }
}

Subscribe to the event:

store.OnBeforeRequest += OnBeforeRequestEvent;

OnSucceedRequest​

This event is invoked by receiving a successful reply from the server.
See its arguments in the Syntax section below.

private void OnSucceedRequestEvent(object sender, SucceedRequestEventArgs args);

Example: act on a successful request​

private void OnSucceedRequestEvent(object sender, SucceedRequestEventArgs args)
{
    if (args.Response.IsSuccessStatusCode == true)
    {
        // action to be taken after a successful request
    }
}

Subscribe to the event:

store.OnSucceedRequest += OnSucceedRequestEvent;

AfterDispose​

This event is invoked immediately after a document store is disposed of.
The args parameter has no contents for this event.

private void AfterDisposeEvent(object sender, EventArgs args);

Subscribe to the event:

store.AfterDispose += AfterDisposeEvent;

BeforeDispose​

This event is invoked immediately before a document store is disposed of.
The args parameter has no contents for this event.

private void BeforeDisposeEvent(object sender, EventArgs args);

Subscribe to the event:

store.BeforeDispose += BeforeDisposeEvent;

RequestExecutorCreated​

This event is invoked when a Request Executor is created, letting you subscribe to the various events of that request executor.

private void RequestExecutorCreatedEvent(object sender, RequestExecutor args);

Subscribe to the event:

store.RequestExecutorCreated += RequestExecutorCreatedEvent;

OnSessionCreated​

This event is invoked after a session is created, letting you, for example, change session configurations.
See its arguments in the Syntax section below.

private void OnSessionCreatedEvent(object sender, SessionCreatedEventArgs args);

Example: configure a new session​

private void OnSessionCreatedEvent(object sender, SessionCreatedEventArgs args)
{
    args.Session.MaxNumberOfRequestsPerSession = 100;
}

Subscribe to the event:

store.OnSessionCreated += OnSessionCreatedEvent;

OnFailedRequest​

This event is invoked when a request to a node has failed. Use it, for example, to track and log failed requests.
See its arguments in the Syntax section below.

private void OnFailedRequestEvent(object sender, FailedRequestEventArgs args);

Example: log every failed request​

private void OnFailedRequestEvent(object sender, FailedRequestEventArgs args)
{
    Logger($"Failed request for database '{args.Database}' ('{args.Url}')", args.Exception);
}

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.
See its arguments in the Syntax section below.

private void OnTopologyUpdatedEvent(object sender, TopologyUpdatedEventArgs args);

You can also use this event to rewrite the URLs the client will use: change the Url of any node in args.Topology.Nodes, and the client will route its requests to the new address.
This is useful when the node URLs registered in the cluster are not the addresses reachable from where the client runs.
A common case is a cluster whose nodes use hostnames that resolve only inside the cluster's network, while an external client must reach those same nodes through publicly reachable hostnames.
You can then map each internal hostname to its public counterpart, so the client connects through reachable addresses.
RavenDB invokes your OnTopologyUpdated handler on every topology update, so your URL mapping is re-applied to each new topology the client receives.

Example: remap node URLs​

void OnTopologyUpdatedEvent(object sender, TopologyUpdatedEventArgs args)
{
    foreach (var node in args.Topology.Nodes)
    {
        // Map each node's internal hostname to one reachable from this client
        node.Url = node.Url.Replace("internal.example.com", "public.example.com");
    }
}

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 that session.
  • Subscribing to an event at the store level is inherited by all subsequent sessions.

Unsubscribing from an event​

To stop responding to an event, detach the handler with the -= operator, passing the same method you subscribed with:

store.OnFailedRequest -= OnFailedRequestEvent;

The request and topology events (OnBeforeRequest, OnSucceedRequest, OnFailedRequest, and OnTopologyUpdated) can be subscribed and unsubscribed only before you call store.Initialize(), so they cannot be unsubscribed at runtime.
All other events on this page can be unsubscribed at any time.

Syntax​

Events​

public event EventHandler<BeforeRequestEventArgs> OnBeforeRequest
public event EventHandler<SucceedRequestEventArgs> OnSucceedRequest
public event EventHandler AfterDispose
public event EventHandler BeforeDispose
public event EventHandler<RequestExecutor> RequestExecutorCreated
public event EventHandler<SessionCreatedEventArgs> OnSessionCreated
public event EventHandler<FailedRequestEventArgs> OnFailedRequest
public event EventHandler<TopologyUpdatedEventArgs> OnTopologyUpdated

Event arguments​

class BeforeRequestEventArgs
{
    string Database
    string Url
    HttpRequestMessage Request
    int AttemptNumber
}
PropertyTypeDescription
DatabasestringThe database name
UrlstringThe database URL
RequestHttpRequestMessageThe request intended to be sent to the server
AttemptNumberintThe number of attempts made to send the request
class FailedRequestEventArgs
{
    string Database
    string Url
    Exception Exception
    HttpResponseMessage Response
    HttpRequestMessage Request
}
PropertyTypeDescription
DatabasestringThe database name
UrlstringThe database URL
ExceptionExceptionThe exception raised by the failed request
ResponseHttpResponseMessageThe response returned from the server
RequestHttpRequestMessageThe original request sent to the server
class TopologyUpdatedEventArgs
{
    Topology Topology
    string Reason
}
PropertyTypeDescription
TopologyTopologyThe updated topology
ReasonstringThe reason for the topology update

In this article