Table of Contents

Class ItemRequestOptions

Namespace
Microsoft.Azure.Cosmos
Assembly
Microsoft.Azure.Cosmos.Client.dll

Cosmos item request options

public class ItemRequestOptions : RequestOptions
Inheritance
ItemRequestOptions
Derived
Inherited Members
Extension Methods

Constructors

ItemRequestOptions() 

public ItemRequestOptions()

Properties

ConsistencyLevel

Gets or sets the consistency level required for the request in the Azure Cosmos DB service.

public ConsistencyLevel? ConsistencyLevel { get; set; }

Property Value

ConsistencyLevel?

The consistency level required for the request.

Remarks

Azure Cosmos DB offers 5 different consistency levels. Strong, Bounded Staleness, Session, Consistent Prefix and Eventual - in order of strongest to weakest consistency. ConnectionPolicy

While this is set at a database account level, Azure Cosmos DB allows a developer to override the default consistency level for each individual request.

DedicatedGatewayRequestOptions

Gets or sets the DedicatedGatewayRequestOptions for requests against the dedicated gateway. These options are only exercised when ConnectionMode is set to ConnectionMode.Gateway and the dedicated gateway endpoint is used for sending requests.

public DedicatedGatewayRequestOptions DedicatedGatewayRequestOptions { get; set; }

Property Value

DedicatedGatewayRequestOptions

Remarks

Learn more about dedicated gateway here.

EnableContentResponseOnWrite

Gets or sets the boolean to only return the headers and status code in the Cosmos DB response for write item operation like Create, Upsert, Patch and Replace. Setting the option to false will cause the response to have a null resource. This reduces networking and CPU load by not sending the resource back over the network and serializing it on the client.

public bool? EnableContentResponseOnWrite { get; set; }

Property Value

bool?

Examples

ItemRequestOptions requestOptions = new ItemRequestOptions() { EnableContentResponseOnWrite = false };
ItemResponse itemResponse = await this.container.CreateItemAsync<ToDoActivity>(tests, new PartitionKey(test.status), requestOptions);
Assert.AreEqual(HttpStatusCode.Created, itemResponse.StatusCode);
Assert.IsNull(itemResponse.Resource);

Remarks

This is optimal for workloads where the returned resource is not used.

IndexingDirective

Gets or sets the indexing directive (Include or Exclude) for the request in the Azure Cosmos DB service.

public IndexingDirective? IndexingDirective { get; set; }

Property Value

IndexingDirective?

The indexing directive to use with a request.

See Also

PostTriggers

Gets or sets the trigger to be invoked after the operation in the Azure Cosmos DB service.

public IEnumerable<string> PostTriggers { get; set; }

Property Value

IEnumerable<string>

The trigger to be invoked after the operation.

Remarks

Only valid when used with Create, Replace and Delete methods for items. Currently only one PostTriggers is permitted per operation.

PreTriggers

Gets or sets the trigger to be invoked before the operation in the Azure Cosmos DB service.

public IEnumerable<string> PreTriggers { get; set; }

Property Value

IEnumerable<string>

The trigger to be invoked before the operation.

Remarks

Only valid when used with Create, Replace and Delete methods for items. Currently only one PreTrigger is permitted per operation.

SessionToken

Gets or sets the token for use with session consistency in the Azure Cosmos DB service.

public string SessionToken { get; set; }

Property Value

string

The token for use with session consistency.

Remarks

One of the ConsistencyLevel for Azure Cosmos DB is Session. In fact, this is the default level applied to accounts.

When working with Session consistency, each new write request to Azure Cosmos DB is assigned a new SessionToken. The DocumentClient will use this token internally with each read/query request to ensure that the set consistency level is maintained.

In some scenarios you need to manage this Session yourself; Consider a web application with multiple nodes, each node will have its own instance of DocumentClient If you wanted these nodes to participate in the same session (to be able read your own writes consistently across web tiers) you would have to send the SessionToken from ItemResponse<T> of the write action on one node to the client tier, using a cookie or some other mechanism, and have that token flow back to the web tier for subsequent reads. If you are using a round-robin load balancer which does not maintain session affinity between requests, such as the Azure Load Balancer, the read could potentially land on a different node to the write request, where the session was created.

If you do not flow the Azure Cosmos DB SessionToken across as described above you could end up with inconsistent read results for a period of time.