Conventions
- Conventions are adjustable RavenDB settings that users can configure to modify client behaviors by their preferences.
-
Access conventions through the
DocumentStore
objectConventions
property. -
In this page:
- Client Conventions
- MaxHttpCacheSize
- MaxNumberOfRequestsPerSession
- UseOptimisticConcurrency
- RequestTimeout
- DisableTopologyUpdates
- SaveEnumsAsIntegers
- UseCompression
- OperationStatusFetchMode
- Change fields/properties Naming Convention
- IdentityPartsSeparator
- TopologyCacheLocation
- AddIdFieldToDynamicObjects
- ShouldIgnoreEntityChanges
- WaitForIndexesAfterSaveChangesTimeout
- WaitForReplicationAfterSaveChangesTimeout
- WaitForNonStaleResultsTimeout
- CreateHttpClient
- HttpClientType
Client Conventions
Access conventions via the Conventions
property of the
DocumentStore
object.
using (var store = new DocumentStore()
{
Conventions =
{
// customizations go here
}
}.Initialize())
{
}
Customize conventions before DocumentStore.Initialize()
is called.
MaxHttpCacheSize
Use MaxHttpCacheSize
as follows to modify the maximum HTTP cache size.
MaxHttpCacheSize = new Size(256, SizeUnit.Megabytes)
Default:
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 |
64MB 128MB 512MB |
32-bit | 32MB |
- Caching is set per database.
- Disabling Caching:
To disable caching globally, setMaxHttpCacheSize
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.
MaxNumberOfRequestsPerSession
Use MaxNumberOfRequestsPerSession
to get or set the maximum number of GET requests per session.
Default: 30
MaxNumberOfRequestsPerSession = 10
UseOptimisticConcurrency
Use UseOptimisticConcurrency
to control whether optimistic
concurrency is set to true by default for all future sessions.
Default: false
UseOptimisticConcurrency = true
RequestTimeout
Use RequestTimeout
to define the global request timeout
value for all RequestExecutors
created per database.
Default: null
RequestTimeout = TimeSpan.FromSeconds(90)
DisableTopologyUpdates
Use DisableTopologyUpdates
to disable database topology updates.
Default: false
DisableTopologyUpdates = false
SaveEnumsAsIntegers
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
UseCompression
UseCompression
determines if the client would send the
server headers indicating whether compression is to be used.
Default: true
UseCompression = true
OperationStatusFetchMode
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)
IdentityPartsSeparator
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:
TopologyCacheLocation
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"
AddIdFieldToDynamicObjects
Use AddIdFieldToDynamicObjects
to determine whether an Id field is automatically added to dynamic objects.
Default: true
AddIdFieldToDynamicObjects = false
ShouldIgnoreEntityChanges
Configure this function to disable entity tracking for certain entities.
Learn more in Customize tracking in conventions.
WaitForIndexesAfterSaveChangesTimeout
Use WaitForIndexesAfterSaveChangesTimeout
to set the default timeout
for the DocumentSession.Advanced.WaitForIndexesAfterSaveChanges method.
Default: 15 Seconds
WaitForIndexesAfterSaveChangesTimeout = TimeSpan.FromSeconds(10)
WaitForReplicationAfterSaveChangesTimeout
Use WaitForReplicationAfterSaveChangesTimeout
to set the default timeout
for the DocumentSession.Advanced.WaitForReplicationAfterSaveChanges method.
Default: 15 Seconds
WaitForReplicationAfterSaveChangesTimeout = TimeSpan.FromSeconds(10)
WaitForNonStaleResultsTimeout
Use WaitForNonStaleResultsTimeout
to set the default timeout WaitForNonStaleResults
methods used when querying.
Default: 15 Seconds
WaitForNonStaleResultsTimeout = TimeSpan.FromSeconds(10)
CreateHttpClient
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.
HttpClientType
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.