CosmosContainer.UpsertItemAsync<T> Method

Definition

Namespace:

Azure.Cosmos

Assembly:

Azure.Cosmos.dll

Package:

Azure.Cosmos v4.0.0-preview3

Upserts an item as an asynchronous operation in the Azure Cosmos service.

public abstract System.Threading.Tasks.Task<Azure.Cosmos.ItemResponse<T>> UpsertItemAsync<T> (T item, Azure.Cosmos.PartitionKey? partitionKey = default, Azure.Cosmos.ItemRequestOptions requestOptions = default, System.Threading.CancellationToken cancellationToken = default);

abstract member UpsertItemAsync : 'T * Nullable<Azure.Cosmos.PartitionKey> * Azure.Cosmos.ItemRequestOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Azure.Cosmos.ItemResponse<'T>>

Public MustOverride Function UpsertItemAsync(Of T) (item As T, Optional partitionKey As Nullable(Of PartitionKey) = Nothing, Optional requestOptions As ItemRequestOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of ItemResponse(Of T))

Type Parameters

T

Parameters

item

T

A JSON serializable object that must contain an id property. CosmosSerializer to implement a custom serializer

partitionKey

Nullable<PartitionKey>

Partition key for the item. If not specified will be populated by extracting from {T}

requestOptions

ItemRequestOptions

(Optional) The options for the item request ItemRequestOptions

cancellationToken

CancellationToken

(Optional) CancellationToken representing request cancellation.

Returns

Task<ItemResponse<T>>

The Response<T> that was upserted contained within a Task object representing the service response for the asynchronous operation.

Exceptions

AggregateException

Represents a consolidation of failures that occurred during async processing. Look within InnerExceptions to find the actual exception(s)

CosmosException

This exception can encapsulate many different types of errors. To determine the specific error always look at the StatusCode property. Some common codes you may get when creating a Document are:

StatusCode	Reason for exception
400	BadRequest - This means something was wrong with the document supplied.
403	Forbidden - This likely means the collection in to which you were trying to upsert the document is full.
413	RequestEntityTooLarge - This means the item exceeds the current max entity size. Consult documentation for limits and quotas.
429	TooManyRequests - This means you have exceeded the number of request units per second. Consult the DocumentClientException.RetryAfter value to see how long you should wait before retrying this operation.

Examples

public class ToDoActivity{
    public string id {get; set;}
    public string status {get; set;}
}

ToDoActivity test = new ToDoActivity()
{
   id = Guid.NewGuid().ToString(),
   status = "InProgress"
};

ItemResponse<ToDoActivity> item = await this.container.UpsertItemAsync<ToDoActivity>(test, new PartitionKey(test.status));