Table of Contents

Class ConnectionPolicy

Namespace
Microsoft.Azure.Documents.Client
Assembly
Microsoft.Azure.Documents.Client.dll

Represents the connection policy associated with a DocumentClient to connect to the Azure Cosmos DB service.

public sealed class ConnectionPolicy
Inheritance
ConnectionPolicy
Inherited Members
Extension Methods

Constructors

ConnectionPolicy()

Initializes a new instance of the ConnectionPolicy class to connect to the Azure Cosmos DB service.

public ConnectionPolicy()

Properties

ConnectionMode

Gets or sets the connection mode used by the client when connecting to the Azure Cosmos DB service.

public ConnectionMode ConnectionMode { get; set; }

Property Value

ConnectionMode

Default value is Gateway

Remarks

For more information, see Connection policy: Use direct connection mode.

ConnectionProtocol

Gets or sets the connection protocol when connecting to the Azure Cosmos DB service.

public Protocol ConnectionProtocol { get; set; }

Property Value

Protocol

Default value is Https.

Remarks

This setting is not used when ConnectionMode is set to Gateway. Gateway mode only supports HTTPS. For more information, see Connection policy: Use the TCP protocol.

Default

Gets the default connection policy used to connect to the Azure Cosmos DB service.

public static ConnectionPolicy Default { get; }

Property Value

ConnectionPolicy

Refer to the default values for the individual properties of ConnectionPolicy that determine the default connection policy.

EnableEndpointDiscovery

Gets or sets the flag to enable endpoint discovery for geo-replicated database accounts in the Azure Cosmos DB service.

public bool EnableEndpointDiscovery { get; set; }

Property Value

bool

Remarks

When the value of this property is true, the SDK will automatically discover the current write and read regions to ensure requests are sent to the correct region based on the regions specified in the PreferredLocations property. Default value is true indicating endpoint discovery is enabled.

EnableReadRequestsFallback

Gets or sets whether to allow for reads to go to multiple regions configured on an account of Azure Cosmos DB service.

public bool? EnableReadRequestsFallback { get; set; }

Property Value

bool?

Default value is null.

Remarks

If this property is not set, the default is true for all Consistency Levels other than Bounded Staleness, The default is false for Bounded Staleness. This property only has effect if the following conditions are satisifed:

  1. EnableEndpointDiscovery is true
  2. the Azure Cosmos DB account has more than one region

IdleTcpConnectionTimeout

(Direct/TCP) Controls the amount of idle time after which unused connections are closed.

public TimeSpan? IdleTcpConnectionTimeout { get; set; }

Property Value

TimeSpan?

By default, idle connections are kept open indefinitely. Value must be greater than or equal to 10 minutes. Recommended values are between 20 minutes and 24 hours.

Remarks

Mainly useful for sparse infrequent access to a large database account.

MaxConnectionLimit

Gets or sets the maximum number of concurrent connections allowed for the target service endpoint in the Azure Cosmos DB service.

public int MaxConnectionLimit { get; set; }

Property Value

int

Default value is 50.

Remarks

This setting is only applicable in Gateway mode.

MaxRequestsPerTcpConnection

(Direct/TCP) Controls the number of requests allowed simultaneously over a single TCP connection. When more requests are in flight simultaneously, the direct/TCP client will open additional connections.

public int? MaxRequestsPerTcpConnection { get; set; }

Property Value

int?

The default settings allow 30 simultaneous requests per connection. Do not set this value lower than 4 requests per connection or higher than 50-100 requests per connection. The former can lead to a large number of connections to be created. The latter can lead to head of line blocking, high latency and timeouts.

Remarks

Applications with a very high degree of parallelism per connection, with large requests or responses, or with very tight latency requirements might get better performance with 8-16 requests per connection.

MaxTcpConnectionsPerEndpoint

(Direct/TCP) Controls the maximum number of TCP connections that may be opened to each Cosmos DB back-end. Together with MaxRequestsPerTcpConnection, this setting limits the number of requests that are simultaneously sent to a single Cosmos DB back-end(MaxRequestsPerTcpConnection x MaxTcpConnectionPerEndpoint).

public int? MaxTcpConnectionsPerEndpoint { get; set; }

Property Value

int?

The default value is 65,535. Value must be greater than or equal to 16.

MediaReadMode

Gets or sets the attachment content (a.k.a. media) download mode when connecting to the Azure Cosmos DB service.

public MediaReadMode MediaReadMode { get; set; }

Property Value

MediaReadMode

Default value is Buffered.

MediaRequestTimeout

Gets or sets the media request timeout in seconds when connecting to the Azure Cosmos DB service. The number specifies the time to wait for response to come back from network peer for attachment content (a.k.a. media) operations.

public TimeSpan MediaRequestTimeout { get; set; }

Property Value

TimeSpan

Default value is 300 seconds.

OpenTcpConnectionTimeout

(Direct/TCP) Controls the amount of time allowed for trying to establish a connection.

public TimeSpan? OpenTcpConnectionTimeout { get; set; }

Property Value

TimeSpan?

The default timeout is 5 seconds. Recommended values are greater than or equal to 5 seconds.

Remarks

When the time elapses, the attempt is cancelled and an error is returned. Longer timeouts will delay retries and failures.

PortReuseMode

(Direct/TCP) Controls the client port reuse policy used by the transport stack.

public PortReuseMode? PortReuseMode { get; set; }

Property Value

PortReuseMode?

The default value is PortReuseMode.ReuseUnicastPort.

PreferredLocations

Gets and sets the preferred locations (regions) for geo-replicated database accounts in the Azure Cosmos DB service. For example, "East US" as the preferred location.

public Collection<string> PreferredLocations { get; }

Property Value

Collection<string>

Remarks

When EnableEndpointDiscovery is true and the value of this property is non-empty, the SDK uses the locations in the collection in the order they are specified to perform operations, otherwise if the value of this property is not specified, the SDK uses the write region as the preferred location for all operations.

If EnableEndpointDiscovery is set to false, the value of this property is ignored.

RequestTimeout

Gets or sets the request timeout in seconds when connecting to the Azure Cosmos DB service. The number specifies the time to wait for response to come back from network peer.

public TimeSpan RequestTimeout { get; set; }

Property Value

TimeSpan

Default value is 60 seconds.

RetryOptions

Gets or sets the RetryOptions associated with the DocumentClient in the Azure Cosmos DB service.

public RetryOptions RetryOptions { get; set; }

Property Value

RetryOptions

If this property is not set, the SDK uses the default retry policy that has MaxRetryAttemptsOnThrottledRequests set to 9 and MaxRetryWaitTimeInSeconds set to 30 seconds.

Examples

The example below creates a new DocumentClient and sets the ConnectionPolicy using the RetryOptions property.

MaxRetryAttemptsOnThrottledRequests is set to 3, so in this case, if a request operation is rate limited by exceeding the reserved throughput for the collection, the request operation retries 3 times before throwing the exception to the application. MaxRetryWaitTimeInSeconds is set to 60, so in this case if the cumulative retry wait time in seconds since the first request exceeds 60 seconds, the exception is thrown. 

ConnectionPolicy connectionPolicy = new ConnectionPolicy();
    connectionPolicy.RetryOptions.MaxRetryAttemptsOnThrottledRequests = 3;
    connectionPolicy.RetryOptions.MaxRetryWaitTimeInSeconds = 60;

DocumentClient client = new DocumentClient(new Uri("service endpoint"), "auth key", connectionPolicy);</code></pre>

Remarks

For more information, see Handle rate limiting/request rate too large.

See Also

UseMultipleWriteLocations

Gets or sets the flag to enable writes on any locations (regions) for geo-replicated database accounts in the Azure Cosmos DB service.

public bool UseMultipleWriteLocations { get; set; }

Property Value

bool

Remarks

When the value of this property is true, the SDK will direct write operations to available writable locations of geo-replicated database account. Writable locations are ordered by PreferredLocations property. Setting the property value to true has no effect until Microsoft.Azure.Documents.DatabaseAccount.EnableMultipleWriteLocations is also set to true. Default value is false indicating that writes are only directed to first region in PreferredLocations property.

UserAgentSuffix

A suffix to be added to the default user-agent for the Azure Cosmos DB service.

public string UserAgentSuffix { get; set; }

Property Value

string

Remarks

Setting this property after sending any request won't have any effect.

Methods

SetCurrentLocation(string)

Automatically populates the PreferredLocations for geo-replicated database accounts in the Azure Cosmos DB service, based on the current region that the client is running in.

public void SetCurrentLocation(string location)

Parameters

location string

The current region that this client is running in. E.g. "East US"