Migration: Changes in DocumentStore

This article describes the changes in public API of DocumentStore.


IDocumentStore can be referenced using Raven.Client.Documents (previously Raven.Client).


The DefaultDatabase property has been renamed to Database.

Credentials and ApiKey

The support for WindowsAuth and OAuth has been dropped. RavenDB 4.0 uses X.509 certificate-based authentication.

Url and FailoverServers

When initializing DocumentStore, you can provide multiple URLs to RavenDB servers holding your database in the cluster. It will grab the cluster topology from the first accessible server.

new DocumentStore
    Urls = new[]


As the configuration system has been changed in .NET Core, we removed the ConnectionStringName property. Instead you can use the .NET core configuration mechanism, retrieve the connection string entry from appsettings.json, convert it, and manually set Urls and Database properties.


All listeners have been removed in favor of events.

  • Usage of the events:

store.OnBeforeStore += (s, e) => { };
store.OnAfterSaveChanges += (s, e) => { };
store.OnBeforeDelete += (s, e) => { };
store.OnBeforeQuery += (s, e) => { };
  • Document conflicts are solved only on the server side using conflict resolution scripts defined in a database.


Instead of JsonRequestFactory, the IDocumentStore instance has RequestExecutor. Using it you can:

  • send any command:

RequestExecutor requestExecutor = store.GetRequestExecutor();

using (requestExecutor.ContextPool.AllocateOperationContext(out JsonOperationContext context))
    var command = new GetDocumentsCommand(start: 0, pageSize: 10);
    requestExecutor.Execute(command, context);

    GetDocumentsResult result = command.Result;
  • check the number of cached items or clear the cache (cache size capacity can be configured via MaxHttpCacheSize convention):

int numberOfCachedItems = requestExecutor.Cache.NumberOfItems;

  • check the number of sent requests:

var numberOfSentRequests = requestExecutor.NumberOfServerRequests;
  • change default request timeout:

requestExecutor.DefaultTimeout = TimeSpan.FromSeconds(180);

The timeout change can be also scoped with the usage of:

using (store.SetRequestTimeout(TimeSpan.FromMilliseconds(180)))


All conventions needs to be set before DocumentStore.Initialize is called. Otherwise, an InvalidOperationException will be thrown.

Read more about changes in document conventions in dedicated article.

Do you need any help with Migration?