see on GitHub

Changes in DocumentStore

This article describes the changes in public API of DocumentStore.


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


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 ConnectionStringName property. Instead you can use .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.OnBeforeQueryExecuted += (s, e) => { };

  • Document conflicts are solved only on the server side using conflict resolution scripts defined in a database.


Instead of JsonRequestFactory 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.SetRequestsTimeout(TimeSpan.FromMilliseconds(180)))


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

Entity serialization and deserialization

Serialization and deserialization of entities can be customized using:

  • CustomizeJsonSerializer
  • DeserializeEntityFromBlittable

new DocumentStore
    Conventions =
        CustomizeJsonSerializer = serializer => throw new CodeOmitted(),
        DeserializeEntityFromBlittable = (type, blittable) => throw new CodeOmitted()

In order to customize bulk insert serialization you can use BulkInsert.TrySerializeEntityToJsonStream convention:

new DocumentStore
    Conventions =
        BulkInsert =
            TrySerializeEntityToJsonStream = (entity, metadata, writer) => throw new CodeOmitted(),


DocumentKeyGenerator has been removed. Use AsyncDocumentIdGenerator instead.


DefaultQueryingConsistency convention has been removed. Check the related article discussing how to deal with non stale results.


DefaultUseOptimisticConcurrency has been renamed to UseOptimisticConcurrency.


FindIdentityPropertyNameFromEntityName has been renamed to FindIdentityPropertyNameFromCollectionName.

FindTypeTagName and FindDynamicTagName

Renamed to FindCollectionName and FindCollectionNameForDynamic.


It has been removed. Only string identifiers are supported.


The client will failover automatically to different node in the cluster. You can customize the reads by using ReadBalanceBehavior convention.


The support for DTC transactions has been dropped.


Removed. The multi gets are processed in async manner on the server side.


Removed. Check How Client Integrates With Replication and Cluster article.

ShouldAggressiveCacheTrackChanges and ShouldSaveChangesForceAggressiveCacheCheck

The client listens to changes by default and evicts cached items if they change on the server side.


Removed. Indexes are automatically replicated within the cluster. Transformers has been removed completely.


Use ReadBalanceBehavior.FastestNode to if you need to ensure that get requests will executed against the fastest node in the cluster.


Removed. Check How Client Integrates With Replication and Cluster article.