Class Builder

Helper class to build Cluster instances.

Inheritance

System.Object

Builder

DseClusterBuilder

Implements

IInitializer

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: Dse

Assembly: Dse.dll

Syntax

public class Builder : IInitializer

Constructors

Builder()

Declaration

public Builder()

Properties

ContactPoints

Gets the contact points that were added as IPEndPoint" instances.

Note that only contact points that were added using AddContactPoint(IPEndPoint) and AddContactPoints(IPEndPoint[]) are returned by this property, as IP addresses and host names must be resolved and assigned the port number, which is performed on Build().

Declaration

public ICollection<IPEndPoint> ContactPoints { get; }

Property Value

Type	Description
System.Collections.Generic.ICollection<System.Net.IPEndPoint>

PoolingOptions

The pooling options used by this builder.

Declaration

public PoolingOptions PoolingOptions { get; }

Property Value

Type	Description
PoolingOptions	the pooling options that will be used by this builder. You can use the returned object to define the initial pooling options for the built cluster.

SocketOptions

The socket options used by this builder.

Declaration

public SocketOptions SocketOptions { get; }

Property Value

Type	Description
SocketOptions	the socket options that will be used by this builder. You can use the returned object to define the initial socket options for the built cluster.

Methods

AddContactPoint(IPAddress)

Add contact point. See AddContactPoint(String) for more details on contact points.

Declaration

public Builder AddContactPoint(IPAddress address)

Parameters

Type	Name	Description
System.Net.IPAddress	address	address of the node to add as contact point

Returns

Type	Description
Builder	this Builder

AddContactPoint(IPEndPoint)

Add contact point. See AddContactPoint(String) for more details on contact points.

Declaration

public Builder AddContactPoint(IPEndPoint address)

Parameters

Type	Name	Description
System.Net.IPEndPoint	address	address of the node to add as contact point

Returns

Type	Description
Builder	this Builder

AddContactPoint(String)

Adds a contact point. Contact points are addresses of Cassandra nodes that the driver uses to discover the cluster topology. Only one contact point is required (the driver will retrieve the address of the other nodes automatically), but it is usually a good idea to provide more than one contact point, as if that unique contact point is not available, the driver won't be able to initialize itself correctly.

Declaration

public Builder AddContactPoint(string address)

Parameters

Type	Name	Description
System.String	address	the address of the node to connect to

Returns

Type	Description
Builder	this Builder

Remarks

However, this can be useful if the Cassandra nodes are behind a router and are not accessed directly. Note that if you are in this situation (Cassandra nodes are behind a router, not directly accessible), you almost surely want to provide a specific IAddressTranslator (through Builder.WithAddressTranslater) to translate actual Cassandra node addresses to the addresses the driver should use, otherwise the driver will not be able to auto-detect new nodes (and will generally not function optimally).

AddContactPoints(IEnumerable<IPAddress>)

Add contact points. See Builder.AddContactPoint for more details on contact points.

Declaration

public Builder AddContactPoints(IEnumerable<IPAddress> addresses)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.Net.IPAddress>	addresses	addresses of the nodes to add as contact point

Returns

Type	Description
Builder	this Builder

AddContactPoints(IEnumerable<IPEndPoint>)

Add contact points. See Builder.AddContactPoint for more details on contact points.

Declaration

public Builder AddContactPoints(IEnumerable<IPEndPoint> addresses)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.Net.IPEndPoint>	addresses	addresses of the nodes to add as contact point

Returns

Type	Description
Builder	this Builder

AddContactPoints(IEnumerable<String>)

Add contact points. See Builder.AddContactPoint for more details on contact points.

Declaration

public Builder AddContactPoints(IEnumerable<string> addresses)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.String>	addresses	addresses of the nodes to add as contact point

Returns

Type	Description
Builder	this Builder

AddContactPoints(IPAddress[])

Add contact points. See Builder.AddContactPoint for more details on contact points.

Declaration

public Builder AddContactPoints(params IPAddress[] addresses)

Parameters

Type	Name	Description
System.Net.IPAddress[]	addresses	addresses of the nodes to add as contact point

Returns

Type	Description
Builder	this Builder

AddContactPoints(IPEndPoint[])

Add contact points. See Builder.AddContactPoint for more details on contact points.

Declaration

public Builder AddContactPoints(params IPEndPoint[] addresses)

Parameters

Type	Name	Description
System.Net.IPEndPoint[]	addresses	addresses of the nodes to add as contact point

Returns

Type	Description
Builder	this Builder

AddContactPoints(String[])

Add contact points. See AddContactPoint(String) for more details on contact points.

Declaration

public Builder AddContactPoints(params string[] addresses)

Parameters

Type	Name	Description
System.String[]	addresses	addresses of the nodes to add as contact point

Returns

Type	Description
Builder	this Builder

Build()

Build the cluster with the configured set of initial contact points and policies.

Declaration

public Cluster Build()

Returns

Type	Description
Cluster	the newly build Cluster instance.

Exceptions

Type	Condition
NoHostAvailableException	Throws a NoHostAvailableException when no host could be resolved.
System.ArgumentException	Throws an ArgumentException when no contact point was provided.

GetConfiguration()

The configuration that will be used for the new cluster.

You should not modify this object directly as change made to the returned object may not be used by the cluster build. Instead, you should use the other methods of this Builder

.

Declaration

public Configuration GetConfiguration()

Returns

Type	Description
Configuration	the configuration to use for the new cluster.

WithAddressTranslator(IAddressTranslator)

Configures the address translator to use for the new cluster.

Declaration

public Builder WithAddressTranslator(IAddressTranslator addressTranslator)

Parameters

Type	Name	Description
IAddressTranslator	addressTranslator	the translator to use.

Returns

Type	Description
Builder	this Builder

Remarks

See IAddressTranslator for more detail on address translation, but the default translator, Dse.DefaultAddressTranslator, should be correct in most cases. If unsure, stick to the default.

WithAuthProvider(IAuthProvider)

Use the specified AuthProvider when connecting to Cassandra hosts.

Use this method when a custom authentication scheme is in place. You shouldn't call both this method and {@code withCredentials}' on the same Builder instance as one will supersede the other

Declaration

public Builder WithAuthProvider(IAuthProvider authProvider)

Parameters

Type	Name	Description
IAuthProvider	authProvider	the AuthProvider"> to use to login to Cassandra hosts.

Returns

Type	Description
Builder	this Builder

WithCloudSecureConnectionBundle(String)

Configures a Cluster using the Cloud Secure Connection Bundle. Using this method will configure this builder with specific contact points, SSL options, credentials and load balancing policy. When needed, you can specify custom settings by calling other builder methods.

In case you need to specify a different set of credentials from the one in the bundle, here is an example: ///

        Cluster.Builder()
                  .WithCloudSecureConnectionBundle("/path/to/bundle.zip")
                  .WithCredentials("username", "password")
                  .Build();

Build() will throw System.InvalidOperationException when an error occurs that is not related to connectivity and NoHostAvailableException when an error occurs while trying to obtain the cluster metadata from the remote endpoint.

Declaration

public Builder WithCloudSecureConnectionBundle(string bundlePath)

Parameters

Type	Name	Description
System.String	bundlePath	Path of the secure connection bundle.

Returns

Type	Description
Builder	A preconfigured builder ready for use.

WithCompression(CompressionType)

Sets the compression to use for the transport.

Declaration

public Builder WithCompression(CompressionType compression)

Parameters

Type	Name	Description
CompressionType	compression	the compression to set

Returns

Type	Description
Builder	this Builder ProtocolOptions.Compression

WithConnectionString(String)

Configure the cluster by applying settings from ConnectionString.

Declaration

public Builder WithConnectionString(string connectionString)

Parameters

Type	Name	Description
System.String	connectionString	the ConnectionString to use

Returns

Type	Description
Builder	this Builder

WithCredentials(String, String)

Uses the provided credentials when connecting to Cassandra hosts.

This should be used if the Cassandra cluster has been configured to use the PasswordAuthenticator. If the the default * AllowAllAuthenticator is used instead, using this method has no effect.

Declaration

public Builder WithCredentials(string username, string password)

Parameters

Type	Name	Description
System.String	username	the user name to use to login to Cassandra hosts.
System.String	password	the password corresponding to

Returns

Type	Description
Builder	this Builder

WithCustomCompressor(IFrameCompressor)

Sets a custom compressor to be used for the compression type. If specified, the compression type is mandatory. If not specified the driver default compressor will be use for the compression type.

Declaration

public Builder WithCustomCompressor(IFrameCompressor compressor)

Parameters

Type	Name	Description
IFrameCompressor	compressor	Implementation of IFrameCompressor

Returns

Type	Description
Builder

WithDefaultKeyspace(String)

Sets default keyspace name for the created cluster.

Declaration

public Builder WithDefaultKeyspace(string defaultKeyspace)

Parameters

Type	Name	Description
System.String	defaultKeyspace	Default keyspace name.

Returns

Type	Description
Builder	this builder

WithExecutionProfiles(Action<IExecutionProfileOptions>)

Adds Execution Profiles to the Cluster instance.

Execution profiles are like configuration presets, multiple methods of the driver accept an execution profile name which is like telling the driver which settings to use for that particular request. This makes it easier to change settings like ConsistencyLevel and ReadTimeoutMillis on a per request basis.

Note that subsequent calls to this method will override the previously provided profiles.

To add execution profiles you can use WithProfile(String, Action<IExecutionProfileBuilder>):

        Cluster.Builder()
                .WithExecutionProfiles(options => options
                    .WithProfile("profile1", profileBuilder => profileBuilder
                        .WithReadTimeoutMillis(10000)
                        .WithConsistencyLevel(ConsistencyLevel.LocalQuorum)))
                .Build()

Declaration

public Builder WithExecutionProfiles(Action<IExecutionProfileOptions> profileOptionsBuilder)

Parameters

Type	Name	Description
System.Action<IExecutionProfileOptions>	profileOptionsBuilder

Returns

Type	Description
Builder	This builder

WithLoadBalancingPolicy(ILoadBalancingPolicy)

Configure the load balancing policy to use for the new cluster.

If no load balancing policy is set through this method, DefaultLoadBalancingPolicy will be used instead.

To specify the local datacenter with the default load balancing policy, use the following method to create a new policy instance: NewDefaultLoadBalancingPolicy(String).

Declaration

public Builder WithLoadBalancingPolicy(ILoadBalancingPolicy policy)

Parameters

Type	Name	Description
ILoadBalancingPolicy	policy	the load balancing policy to use.

Returns

Type	Description
Builder	this Builder

WithMaxProtocolVersion(ProtocolVersion)

Limits the maximum protocol version used to connect to the nodes

When it is not set, the protocol version used is negotiated between the driver and the Cassandra cluster upon establishing the first connection.

Useful when connecting to a cluster that contains nodes with different major/minor versions of Cassandra. For example, preparing for a rolling upgrade of the Cluster.

Declaration

public Builder WithMaxProtocolVersion(ProtocolVersion version)

Parameters

Type	Name	Description
ProtocolVersion	version

Returns

Type	Description
Builder	this instance

Remarks

Some Cassandra features are only available with a specific protocol version.

WithMaxProtocolVersion(Byte)

Limits the maximum protocol version used to connect to the nodes

When it is not set, the protocol version used is negotiated between the driver and the Cassandra cluster upon establishing the first connection.

Useful when connecting to a cluster that contains nodes with different major/minor versions of Cassandra. For example, preparing for a rolling upgrade of the Cluster.

Declaration

public Builder WithMaxProtocolVersion(byte version)

Parameters

Type	Name	Description
System.Byte	version	The native protocol version. Different Cassandra versions support a range of protocol versions, for example: - Cassandra 2.0 (DSE 4.0 - 4.6): Supports protocol versions 1 and 2. - Cassandra 2.1 (DSE 4.7 - 4.8): Supports protocol versions 1, 2 and 3. - Cassandra 2.2: Supports protocol versions 1, 2, 3 and 4. - Cassandra 3.0: Supports protocol versions 3 and 4.

Returns

Type	Description
Builder	this instance

Remarks

Some Cassandra features are only available with a specific protocol version.

WithMaxSchemaAgreementWaitSeconds(Int32)

Sets the maximum time to wait for schema agreement before returning from a DDL query.

DDL queries introduce schema changes that need to be propagated to all nodes in the cluster. Once they have settled on a common version, we say that they are in agreement.

If not set through this method, the default value (10 seconds) will be used.

Declaration

public Builder WithMaxSchemaAgreementWaitSeconds(int maxSchemaAgreementWaitSeconds)

Parameters

Type	Name	Description
System.Int32	maxSchemaAgreementWaitSeconds	The new value to set.

Returns

Type	Description
Builder	This Builder.

Exceptions

Type	Condition
System.ArgumentException	If the provided value is zero or less.

WithMetadataSyncOptions(MetadataSyncOptions)

If not set through this method, the default value options will be used (metadata synchronization is enabled by default). The api reference of MetadataSyncOptions specifies what is the default for each option.

In case you disable Metadata synchronization, please ensure you invoke RefreshSchemaAsync(String, String) in order to keep the token metadata up to date otherwise you will not be getting everything you can out of token aware routing, i.e. TokenAwarePolicy, which is enabled by the default.

Disabling this feature has the following impact:

• Token metadata will not be computed and stored. This means that token aware routing (TokenAwarePolicy, enabled by default) will only work correctly if you keep the token metadata up to date using the RefreshSchemaAsync(String, String) method. If you wish to go this route of manually refreshing the metadata then it's recommended to refresh only the keyspaces that this application will use, by passing the

  keyspace

  parameter.
• Keyspace metadata will not be cached by the driver. Every time you call methods like GetTable(String, String), GetKeyspace(String) and other similar methods of the Metadata class, the driver will query that data on demand and will not cache it.
• The driver will not handle

  SCHEMA_CHANGED

  responses. This means that when you execute schema changing statements through the driver, it will not update the schema or topology metadata automatically before returning.

Declaration

public Builder WithMetadataSyncOptions(MetadataSyncOptions metadataSyncOptions)

Parameters

Type	Name	Description
MetadataSyncOptions	metadataSyncOptions	The new options to set.

Returns

Type	Description
Builder	This Builder.

WithMetrics(IDriverMetricsProvider)

Enables metrics. DataStax provides an implementation based on a third party library (App.Metrics) on a separate NuGet package: CassandraCSharpDriver.AppMetrics Alternatively, you can implement your own provider that implements IDriverMetricsProvider.

This method enables all individual metrics without a bucket prefix. To customize these options, use WithMetrics(IDriverMetricsProvider, DriverMetricsOptions).

Declaration

public Builder WithMetrics(IDriverMetricsProvider driverMetricsProvider)

Parameters

Type	Name	Description
IDriverMetricsProvider	driverMetricsProvider	Metrics Provider implementation.

Returns

Type	Description
Builder	This builder

WithMetrics(IDriverMetricsProvider, DriverMetricsOptions)

Enables metrics. DataStax provides an implementation based on a third party library (App.Metrics) on a separate NuGet package: CassandraCSharpDriver.AppMetrics Alternatively, you can implement your own provider that implements IDriverMetricsProvider.

This method enables all individual metrics without a bucket prefix. To customize these settings, use WithMetrics(IDriverMetricsProvider, DriverMetricsOptions). For explanations on these settings, see the API docs of the DriverMetricsOptions class.

The AppMetrics provider also has some settings that can be customized, check out the API docs of Cassandra.AppMetrics.DriverAppMetricsOptions.

Here is an example:

var cluster = 
    Cluster.Builder()
           .WithMetrics(
               metrics.CreateDriverMetricsProvider(new DriverAppMetricsOptions()),
               new DriverMetricsOptions()
                   .SetEnabledNodeMetrics(NodeMetric.DefaultNodeMetrics.Except(new [] { NodeMetric.Meters.BytesSent }))
                   .SetEnabledSessionMetrics(
                       SessionMetric.DefaultSessionMetrics.Except(new[] { SessionMetric.Meters.BytesReceived }))
                   .SetBucketPrefix("web.app"))
           .Build();

Declaration

public Builder WithMetrics(IDriverMetricsProvider driverMetricsProvider, DriverMetricsOptions metricsOptions)

Parameters

Type	Name	Description
IDriverMetricsProvider	driverMetricsProvider	Metrics Provider implementation.
DriverMetricsOptions	metricsOptions	Metrics Provider implementation.

Returns

Type	Description
Builder	This builder

WithNoCompact()

Enables the NO_COMPACT startup option.

When this option is set, SELECT, UPDATE, DELETE, and BATCH statements on COMPACT STORAGE tables function in "compatibility" mode which allows seeing these tables as if they were "regular" CQL tables.

This option only affects interactions with tables using COMPACT STORAGE and it is only supported by C* 3.0.16+, 3.11.2+, 4.0+ and DSE 6.0+.

Declaration

public Builder WithNoCompact()

Returns

Type	Description
Builder

WithoutRowSetBuffering()

Disables row set buffering for the created cluster (row set buffering is enabled by default otherwise).

Declaration

public Builder WithoutRowSetBuffering()

Returns

Type	Description
Builder	this builder

WithPoolingOptions(PoolingOptions)

Declaration

public Builder WithPoolingOptions(PoolingOptions value)

Parameters

Type	Name	Description
PoolingOptions	value

Returns

Type	Description
Builder

WithPort(Int32)

The port to use to connect to all Cassandra hosts. If not set through this method, the default port (9042) will be used instead.

Declaration

public Builder WithPort(int port)

Parameters

Type	Name	Description
System.Int32	port	the port to set.

Returns

Type	Description
Builder	this Builder

WithQueryOptions(QueryOptions)

Sets the QueryOptions to use for the newly created Cluster.

If no query options are set through this method, default query options will be used.

Declaration

public Builder WithQueryOptions(QueryOptions options)

Parameters

Type	Name	Description
QueryOptions	options	the QueryOptions to use.

Returns

Type	Description
Builder	this Builder.

WithQueryTimeout(Int32)

Specifies the number of milliseconds that the driver should wait for the response before the query times out in a synchronous operation.

This will cause that synchronous operations like Execute(String) to throw a System.TimeoutException after the specified number of milliseconds.

Default timeout value is set to

20,000

(20 seconds).

Declaration

public Builder WithQueryTimeout(int queryAbortTimeout)

Parameters

Type	Name	Description
System.Int32	queryAbortTimeout	Timeout specified in milliseconds.

Returns

Type	Description
Builder	this builder

Remarks

If you want to define a read timeout at a lower level, you can use SetReadTimeoutMillis(Int32).

WithReconnectionPolicy(IReconnectionPolicy)

Configure the reconnection policy to use for the new cluster.

If no reconnection policy is set through this method,

Policies.DefaultReconnectionPolicy will be used instead.

Declaration

public Builder WithReconnectionPolicy(IReconnectionPolicy policy)

Parameters

Type	Name	Description
IReconnectionPolicy	policy	the reconnection policy to use

Returns

Type	Description
Builder	this Builder

WithRetryPolicy(IRetryPolicy)

Configure the retry policy to be used for the new cluster.

When the retry policy is not set with this method, the DefaultRetryPolicy will be used instead.

Use a IExtendedRetryPolicy implementation to cover all error scenarios.

Declaration

public Builder WithRetryPolicy(IRetryPolicy policy)

Parameters

Type	Name	Description
IRetryPolicy	policy	the retry policy to use

Returns

Type	Description
Builder	this Builder

WithSessionName(String)

ISession objects created through the ICluster built from this builder will have SessionName set to the value provided in this method. The first session created by this cluster instance will have its name set exactly as it is provided in this method. Any session created by the ICluster built from this builder after the first one will have its name set as a concatenation of the provided value plus a counter.

        var cluster = Cluster.Builder().WithSessionName("main-session").Build();
        var session = cluster.Connect(); // session.SessionName == "main-session"
        var session1 = cluster.Connect(); // session1.SessionName == "main-session1"
        var session2 = cluster.Connect(); // session2.SessionName == "main-session2"

If this setting is not set, the default session names will be "s0", "s1", "s2", etc.

        var cluster = Cluster.Builder().Build();
        var session = cluster.Connect(); // session.SessionName == "s0"
        var session1 = cluster.Connect(); // session1.SessionName == "s1"
        var session2 = cluster.Connect(); // session2.SessionName == "s2"

Declaration

public Builder WithSessionName(string sessionName)

Parameters

Type	Name	Description
System.String	sessionName

Returns

Type	Description
Builder

WithSocketOptions(SocketOptions)

Configures the socket options that are going to be used to create the connections to the hosts.

Declaration

public Builder WithSocketOptions(SocketOptions value)

Parameters

Type	Name	Description
SocketOptions	value

Returns

Type	Description
Builder

WithSpeculativeExecutionPolicy(ISpeculativeExecutionPolicy)

Configure the speculative execution to use for the new cluster.

If no speculative execution policy is set through this method, DefaultSpeculativeExecutionPolicy will be used instead.

Declaration

public Builder WithSpeculativeExecutionPolicy(ISpeculativeExecutionPolicy policy)

Parameters

Type	Name	Description
ISpeculativeExecutionPolicy	policy	the speculative execution policy to use

Returns

Type	Description
Builder	this Builder

WithSSL()

Enables the use of SSL for the created Cluster. Calling this method will use default SSL options.

Declaration

public Builder WithSSL()

Returns

Type	Description
Builder	this builder

Remarks

If SSL is enabled, the driver will not connect to any Cassandra nodes that doesn't have SSL enabled and it is strongly advised to enable SSL on every Cassandra node if you plan on using SSL in the driver. Note that SSL certificate common name(CN) on Cassandra node must match Cassandra node hostname.

WithSSL(SSLOptions)

Enables the use of SSL for the created Cluster using the provided options.

Declaration

public Builder WithSSL(SSLOptions sslOptions)

Parameters

Type	Name	Description
SSLOptions	sslOptions	SSL options to use.

Returns

Type	Description
Builder	this builder

Remarks

If SSL is enabled, the driver will not connect to any Cassandra nodes that doesn't have SSL enabled and it is strongly advised to enable SSL on every Cassandra node if you plan on using SSL in the driver. Note that SSL certificate common name(CN) on Cassandra node must match Cassandra node hostname.

WithTimestampGenerator(ITimestampGenerator)

Configures the generator that will produce the client-side timestamp sent with each query.

This feature is only available with protocol version 3 or above of the native protocol. With earlier versions, timestamps are always generated server-side, and setting a generator through this method will have no effect.

If no generator is set through this method, the driver will default to client-side timestamps by using AtomicMonotonicTimestampGenerator.

Declaration

public Builder WithTimestampGenerator(ITimestampGenerator generator)

Parameters

Type	Name	Description
ITimestampGenerator	generator	The generator to use.

Returns

Type	Description
Builder	This builder instance

WithTypeSerializers(TypeSerializerDefinitions)

Sets the TypeSerializer<T> to be used, replacing the default ones.

Declaration

public Builder WithTypeSerializers(TypeSerializerDefinitions definitions)

Parameters

Type	Name	Description
TypeSerializerDefinitions	definitions

Returns

Type	Description
Builder	this instance

Implements

IInitializer