Configuration Options

This page lists the complete set of options available to configure the Hazelcast .NET client. For more details regarding configuration in general, including configuration sources, refer to the Configuration page.

See HazelcastOptions for full documentation of the class.

Property	Summary
ClusterName	Gets or sets the name of the cluster. This must match the name of the cluster that the client is going to connect to.
ClientName	Gets or sets the name of the client. This is optional. If no client name is specified, a name will be generated.
Labels	Gets the set of client labels.
LoadBalancer	Gets the SingletonServiceFactory<TService> for the ILoadBalancer. When set in the configuration file, it is defined as an injected type, for instance: `"loadBalancer": { "typeName": "My.LoadBalancer", "args": { "foo": 42 } }` where `typeName` is the name of the type, and `args` is an optional dictionary of arguments for the type constructor. In addition to custom type names, `typeName` can be any of the predefined `Random`, `RoundRobin` or `Static` values. The default load balancer is the RoundRobinLoadBalancer.
LoggerFactory	Gets the SingletonServiceFactory<TService> for ILoggerFactory. The only option available for logging is the ILoggerFactory creator, which can only be set programmatically. All other logging options (level, etc.) are configured via the default Microsoft configuration system. See https://docs.microsoft.com/en-us/aspnet/core/fundamentals/logging for details and documentation.
PatternMatcher	Gets or sets the configuration pattern matcher. This can only be set programmatically.
NearCaches	Gets the dictionary which contains the NearCacheOptions for each near cache.
FlakeIdGenerators	Gets the dictionary which contains the FlakeIdGeneratorOptions for each Flake Id Generator.
Subscribers	Gets the list of subscribers. Subscribers can be added to the configuration programmatically via the AddSubscriber(IHazelcastClientEventSubscriber) method or any of its overloads. A subscriber is a class that implements IHazelcastClientEventSubscriber and subscribes the client to events as soon as the client is connected. In a configuration file, they are defined as an array of injected types, for instance: `"subscribers": [ { "typeName": "My.Subscriber, My.Dll" }, { "typeName": "My.OtherSubscriber, My.dll", "args": { "foo": 33 } } ]` where `typeName` is the name of the type, and `args` is an optional dictionary of arguments for the type constructor.

Authentication

Access AuthenticationOptions via options.Authentication.

Property Summary

Property	Summary
CredentialsFactory	Gets the SingletonServiceFactory<TService> for the ICredentialsFactory. When set in the configuration file, it is defined as an injected type, for instance: `"credentialsFactory": { "typeName": "My.CredentialsFactory", "args": { "foo": 42 } }` where `typeName` is the name of the type, and `args` is an optional dictionary of arguments for the type constructor. In addition, shortcuts exists for common credentials factory. The whole `credentialsFactory` block can be omitted and replace by one of the following: Username and password: `"username-password": { "username": "someone", "password": "secret" }` Kerberos: `"kerberos": { "spn": "service-provider-name" }` Token: `"token": { "data": "some-secret-token", "encoding": "none" }` Supported encodings are: `none` and `base64`.

CredentialsFactory

Gets the SingletonServiceFactory<TService> for the ICredentialsFactory.

When set in the configuration file, it is defined as an injected type, for instance:

"credentialsFactory":
{
  "typeName": "My.CredentialsFactory",
  "args":
  {
    "foo": 42
  }
}

where typeName is the name of the type, and args is an optional dictionary of arguments for the type constructor.

In addition, shortcuts exists for common credentials factory. The whole credentialsFactory block can be omitted and replace by one of the following:

Username and password:

"username-password":
                         {
                           "username": "someone",
                           "password": "secret"
                         }

Kerberos:

"kerberos":
            {
              "spn": "service-provider-name"
            }

Token:

"token":
         {
           "data": "some-secret-token",
           "encoding": "none"
         }

Supported encodings are: none and base64.

Heartbeat

Access HeartbeatOptions via options.Heartbeat.

Property	Summary
PeriodMilliseconds	Gets or sets the heartbeat period. Heartbeat will run periodically, and send a ping request to connections that have not been written to over the previous period.
TimeoutMilliseconds	Gets or sets the timeout (how long to wait before declaring a connection down). Heartbeat will consider that connections that have not received data for the timeout duration, although they should have been pinged, are down. The timeout should be longer than the period.

Property

Summary

PeriodMilliseconds

Gets or sets the heartbeat period.

Heartbeat will run periodically, and send a ping request to connections that have not been written to over the previous period.

TimeoutMilliseconds

Gets or sets the timeout (how long to wait before declaring a connection down).

Heartbeat will consider that connections that have not received data for the timeout duration, although they should have been pinged, are down.

The timeout should be longer than the period.

Messaging

Access MessagingOptions via options.Messaging.

Property	Summary
MinRetryDelayMilliseconds	Gets or sets the min retry delay.
RetryUnsafeOperations	Whether to retry all operations including unsafe operations. Operations can fail due to various reasons. Read-only operations are retried by default. If you want to enable retry for all operations, set this property to `true`. However, note that a failed operation leaves the cluster in an undecided state. The cluster may have received the request and executed the operation, but failed to respond to the client. For idempotent operations this is harmless, but for non idempotent ones retrying can cause undesirable effects. Also note that the redo can perform on any member. For these reasons, this is `false` by default.
RetryTimeoutSeconds	Gets or sets the invocation timeout. The RetryTimeoutSeconds is a soft timeout that prevents retrying an invocation for too long in case it fails. It does not controls the duration of a single try, and does not abort it. And invocation single try can run for as long as the connection that supports it remains open.
RetryOnClientReconnecting	Whether to retry an invocation that has failed to start because the client was offline but still active and reconnecting. This is `true` by default, i.e. if the client got disconnected and is reconnecting, invocations will be retried until they reach their timeout, or the client reconnects. Set this to `false` if you want invocations to fail immediately in case the client gets disconnected, even if it is trying to reconnect. Note that this only applies to invocation that failed to start, and therefore this is safe for all invocations. See RetryUnsafeOperations for what happens once the invocation has started.

Networking

Access NetworkingOptions via options.Networking.

Property	Summary
Addresses	Gets or sets the list of initial addresses. The client uses this list to find a running member and connect to it. This initial member will then send the list of other members to the client. Each address must be a valid IPv4 or IPv6 address.
ShuffleAddresses	Whether to shuffle addresses when attempting to connect to the cluster.
SmartRouting	Whether smart routing is enabled. If true (default), client will route the key based operations to owner of the key at the best effort. Note that it however does not guarantee that the operation will always be executed on the owner, as the member table is only updated every 10 seconds.
RedoOperations	Whether to retry operations. While sending the requests to related members, operations can fail due to various reasons. Read-only operations are retried by default. If you want to enable retry for the other operations, set this property to `true`. Note that it is not clear whether the operation is performed or not. For idempotent operations this is harmless, but for non idempotent ones retrying can cause undesirable effects. Also note that the redo can perform on any member.
ReconnectMode	Gets or sets the ReconnectMode in case the client is disconnected.
Reconnect	Whether to attempt to automatically reconnect a client that has been disconnected. This is `true` by default, i.e. a client that has been disconnected but is still active will try to reconnect to the cluster. Set this to `false` if you want it to shut down and never reconnect.
UsePublicAddresses	Whether to use the public addresses of members. When connecting to clusters where members have different public and internal addresses, this option can be used to indicate whether to use, or not use, the public addresses. When `null` (by default), the client will try to determine which address to use automatically.
ConnectionTimeoutMilliseconds	Gets or sets the connection timeout. This timeout is used in various places. It is the connection timeout for each individual socket. It is also the timeout for cloud discovery.

Ssl

Access SslOptions via options.Networking.Ssl.

Property	Summary
Enabled	Whether to enable SSL.
ValidateCertificateChain	Whether to validate the certificate chain.
ValidateCertificateName	Whether to validate the certificate name.
CheckCertificateRevocation	Whether to check for certificate revocation.
CertificateName	Gets or sets the name of the certificate.
CertificatePath	Gets or sets the full path to the certificate file.
CertificatePassword	Gets or sets the password for the certificate file.
Protocol	Gets or sets the SSL protocol. The protocol must be a member of the SslProtocols enum, and currently only `Tls`, `Tls11` and `Tls12` are supported, though only the latest is recommended.

Cloud

Access CloudOptions via options.Networking.Cloud.

Property	Summary
Enabled	Whether Hazelcast Cloud is enabled. This property is read-only and is set automatically when DiscoveryToken is not null nor empty.
DiscoveryToken	Gets or sets the discovery token of the cluster.
Url	Gets or sets the cloud url base.

Socket

Access SocketOptions via options.Networking.Socket.

Property	Summary
BufferSizeKiB	The send and receive buffers size. The buffer size is expressed in Kibibytes, ie units of 1024 bytes. This sets the size of both the send and receive buffers.
KeepAlive	Whether to keep the socket alive.
LingerSeconds	The number of seconds to remain connected after the socket Close() method is called, or zero to disconnect immediately.
TcpNoDelay	Whether the socket is using the Nagle algorithm.

ConnectionRetry

Access ConnectionRetryOptions via options.Networking.ConnectionRetry.

Property	Summary
InitialBackoffMilliseconds	Gets or sets the initial back-off time in milliseconds.
MaxBackoffMilliseconds	Gets or sets the maximum back-off time in milliseconds.
Multiplier	Gets or sets the multiplier.
ClusterConnectionTimeoutMilliseconds	Gets or sets the timeout in milliseconds.
Jitter	Gets or sets the jitter.

Events

Access EventsOptions via options.Events.

Property	Summary
SubscriptionCollectDelay	Gets or sets the delay before collecting subscriptions starts.
SubscriptionCollectPeriod	Gets or sets the period of the subscription collection.
SubscriptionCollectTimeout	Gets or sets the subscription collection timeout, after which a subscription is considered dead and removed.

Preview

Access PreviewOptions via options.Preview.

Preview options are unsupported options that are provided to enable behaviors of the client that remain experimental and/or may break backward compatibility.

Property Summary

Property	Summary
EnableNewReconnectOptions	(unsupported) Whether to enable the new reconnect options. The ReconnectMode option specifies a synchronous and an asynchronous mode, but they are both implemented in the same way. These modes actually don't make a lot of sense. And, reconnection is disabled by default. When the new reconnect options are enabled, this option is ignored, and replaced by the Reconnect option, which is a boolean and indicates whether to reconnect or not. It is `true` by default. Invocations that fail because the client is reconnecting will be retried (all of them, reads and writes) until the client is reconnected, or the invocation times out.
EnableNewRetryOptions	(unsupported) Whether to enable the new retry options. Retrying failed invocations was originally controlled by the RedoOperations option. This option belongs more to messaging, where we may want to enable finer-grain control of retries. When the new retry options are enabled, this option is ignored and replaced by the RetryUnsafeOperations option: all safe (read) operations are retried by default, and this option controls whether to retry unsafe (write) operations. It is `false` by default.In addition, a new option is introduced, RetryOnClientReconnecting which controls retries when the operation cannot even start because the client is reconnecting. It is `true` by default.

EnableNewReconnectOptions

(unsupported) Whether to enable the new reconnect options.

The ReconnectMode option specifies a synchronous and an asynchronous mode, but they are both implemented in the same way. These modes actually don't make a lot of sense. And, reconnection is disabled by default.

When the new reconnect options are enabled, this option is ignored, and replaced by the Reconnect option, which is a boolean and indicates whether to reconnect or not. It is true by default. Invocations that fail because the client is reconnecting will be retried (all of them, reads and writes) until the client is reconnected, or the invocation times out.

EnableNewRetryOptions

(unsupported) Whether to enable the new retry options.

Retrying failed invocations was originally controlled by the RedoOperations option. This option belongs more to messaging, where we may want to enable finer-grain control of retries.

When the new retry options are enabled, this option is ignored and replaced by the RetryUnsafeOperations option: all safe (read) operations are retried by default, and this option controls whether to retry unsafe (write) operations. It is false by default.In addition, a new option is introduced, RetryOnClientReconnecting which controls retries when the operation cannot even start because the client is reconnecting. It is true by default.

Metrics

Access MetricsOptions via options.Metrics.

Property	Summary
Enabled	Whether client statistics are enabled.
PeriodSeconds	Gets or sets the period at which client metrics are sent to the cluster.

Serialization

Access SerializationOptions via options.Serialization.

IIdentifiedDataSerializable, IPortable, custom serializers, and global serializer can be configured using this config.

Property	Summary
EnableClrSerialization	Whether to enable CLR serialization via BinaryFormatter. BinaryFormatter is now considered insecure, and CLR serialization is disabled by default. In order to enable CLR serialization, set this value to `true`. Note that if a global serializer is configured via GlobalSerializer, then this option must be true, and OverrideClrSerialization must be false, for CLR serialization to be enabled.
Endianness	Gets or sets the Endianness. This value should match the server configuration.
ValidateClassDefinitions	Whether to check for class definition errors at start, and throw an Serialization Exception with error definition.
PortableVersion	Gets or sets the portable version.
ClassDefinitions	Gets the collection of IClassDefinition. This can only be done programmatically.
PortableFactories	Gets the collection of FactoryOptions<T> of IPortableFactory.
DataSerializableFactories	Gets the collection of FactoryOptions<T> of IDataSerializableFactory.
Serializers	Gets the collection of SerializerOptions.

Compact

Access CompactOptions via options.Serialization.Compact.

Property	Summary
SchemaReplicationRetries	Gets or sets the maximum number of retries for schema publication. When a schema is published to the cluster, the client ensures that it is replicated to all known members, thus protecting against split-brain situations where only some members would receive the schema. Should some members not receive the schema, publication is retried. The default value is 100.
SchemaReplicationDelay	Gets or sets the amount of time to wait between each schema publication retries. See SchemaReplicationRetries. The default value is 1 second.

Property

Summary

SchemaReplicationRetries

Gets or sets the maximum number of retries for schema publication.

When a schema is published to the cluster, the client ensures that it is replicated to all known members, thus protecting against split-brain situations where only some members would receive the schema. Should some members not receive the schema, publication is retried.

The default value is 100.

SchemaReplicationDelay

Gets or sets the amount of time to wait between each schema publication retries.

See SchemaReplicationRetries.

The default value is 1 second.

GlobalSerializer

Access GlobalSerializerOptions via options.Serialization.GlobalSerializer.

Property	Summary
OverrideClrSerialization	Whether to fully override (and ignore) the native CLR serialization.

NearCache

Access CommonNearCacheOptions via options.NearCache.

Property	Summary
ReconciliationIntervalSeconds	Gets or sets the reconciliation interval.
MinReconciliationIntervalSeconds	Gets or sets the minimum reconciliation interval.
MaxToleratedMissCount	Gets or sets the maximum tolerated miss count.