Client Conventions

Access conventions via the Conventions property of the DocumentStore object.

using (var store = new DocumentStore()
    Conventions =
        // customizations go here


Customize conventions before DocumentStore.Initialize() is called.


Use MaxHttpCacheSize as follows to modify the maximum HTTP cache size.

MaxHttpCacheSize = new Size(256, SizeUnit.Megabytes)


System Usable Memory Default Value
64-bit Lower than or equal to 3GB
Greater than 3GB and Lower than or equal to 6GB
Greater than 6GB
32-bit 32MB
  • Caching is set per database.
  • Disabling Caching:
    To disable caching globally, set MaxHttpCacheSize to zero.
    MaxHttpCacheSize = new Size(0, SizeUnit.Megabytes)

    Please be aware that if cache is disabled ALL data requests will be sent to the server.


Use MaxNumberOfRequestsPerSession to get or set the maximum number of GET requests per session.
Default: 30

MaxNumberOfRequestsPerSession = 10


Use UseOptimisticConcurrency to control whether optimistic concurrency is set to true by default for all future sessions.
Default: false

UseOptimisticConcurrency = true


Use RequestTimeout to define the global request timeout value for all RequestExecutors created per database.
Default: null

RequestTimeout = TimeSpan.FromSeconds(90)


Use DisableTopologyUpdates to disable database topology updates.
Default: false

DisableTopologyUpdates = false


SaveEnumsAsIntegers determines whether C# enum types should be saved as integers or strings and instructs the LINQ provider to query enums as integer values.
Default: false

SaveEnumsAsIntegers = true

UseHttpCompression, UseHttpDecompression

It determines if the client will send headers to the server indicating that it allows compression/decompression to be used.
Default: true.

UseHttpCompression = true
UseHttpDecompression = true


OperationStatusFetchMode changes the way the operation is fetching the operation status when waiting for completion.

By default, the value is set to ChangesApi which uses the WebSocket protocol underneath when a connection is established with the server.
On some older systems like Windows 7 the WebSocket protocol might not be available due to the OS and .NET Framework limitations. To bypass this issue, the value can be changed to Polling.

OperationStatusFetchMode = OperationStatusFetchMode.ChangesApi

Change fields/properties Naming Convention

Different clients may use different casing conventions for entity field names.
E.g., here are the field naming defaults for clients of a few languages.

Language Default convention Example
C# PascalCase OrderLines
Java camelCase orderLines
JavaScript camelCase orderLines

Whatever naming convention a client uses, is by default reflected on the server-side.
These defauls can be customized, e.g. to allow inter-language operability.

Example: Using camelCase by a C# client

Make a C# client use camelCase by setting CustomizeJsonSerializer and PropertyNameConverter.

private string FirstCharToLower(string str) => $"{Char.ToLower(str[0])}{str.Substring(1)}";
Serialization = new NewtonsoftJsonSerializationConventions
    CustomizeJsonSerializer = s => s.ContractResolver = new CamelCasePropertyNamesContractResolver()
PropertyNameConverter = mi => FirstCharToLower(mi.Name)


Use the IdentityPartsSeparator convention to change the default ID (Identity) separator for automatically-generated document IDs.
Default: / (forward slash)

IdentityPartsSeparator = '~'
  • The value can be any char except | (pipe).

Changing the separator affects these ID generation strategies:


Use TopologyCacheLocation to change the location of topology cache files.
Setting this value will check directory existance and writing permissions.
Default: The application's base directory (AppContext.BaseDirectory)

TopologyCacheLocation = @"C:\RavenDB\TopologyCache"


Use AddIdFieldToDynamicObjects to determine whether an Id field is automatically added to dynamic objects.
Default: true

AddIdFieldToDynamicObjects = false


Configure this function to disable entity tracking for certain entities.
Learn more in Customize tracking in conventions.


Use WaitForIndexesAfterSaveChangesTimeout to set the default timeout for the DocumentSession.Advanced.WaitForIndexesAfterSaveChanges method.
Default: 15 Seconds

WaitForIndexesAfterSaveChangesTimeout = TimeSpan.FromSeconds(10)


Use WaitForReplicationAfterSaveChangesTimeout to set the default timeout for the DocumentSession.Advanced.WaitForReplicationAfterSaveChanges method.
Default: 15 Seconds

WaitForReplicationAfterSaveChangesTimeout = TimeSpan.FromSeconds(10)


Use WaitForNonStaleResultsTimeout to set the default timeout WaitForNonStaleResults methods used when querying.
Default: 15 Seconds

WaitForNonStaleResultsTimeout = TimeSpan.FromSeconds(10)


Use the CreateHttpClient convention to modify the HTTP client your client application uses.
Implementing your own HTTP client can be useful when, for example, you'd like your clients to provide the server with tracing info.

CreateHttpClient = handler =>
    // Your HTTP Client code here, e.g. -
    var httpClient = new MyHttpClient(new HttpClientXRayTracingHandler(new HttpClientHandler()));
    return httpClient;

If you override the default CreateHttpClient convention we advise that you also set the HTTP client type correctly using the HttpClientType convention.


Use HttpClientType to get or set the type of HTTP client you're using.

// The type of HTTP client you are using
HttpClientType = typeof(MyHttpClient)

RavenDB uses the HTTP type internally to manage its cache. If you override the CreateHttpClient convention to use a non-default HTTP client, we advise that you also set HttpClientType so it returns the client type you are actually using.


Use the DisposeCertificate convention to enable or disable the automatic disposal of X509Certificate2 certificates when the store is disposed of.
Default: true

// Disable the automatic disposal of certificates when the store is disposed of
DisposeCertificate = false