Container.UpsertItemAsync<T>(T, Nullable<PartitionKey>, ItemRequestOptions, CancellationToken) Method

Definition

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

public abstract System.Threading.Tasks.Task<Microsoft.Azure.Cosmos.ItemResponse<T>> UpsertItemAsync<T> (T item, Microsoft.Azure.Cosmos.PartitionKey? partitionKey = default, Microsoft.Azure.Cosmos.ItemRequestOptions requestOptions = default, System.Threading.CancellationToken cancellationToken = default);
abstract member UpsertItemAsync : 'T * Nullable<Microsoft.Azure.Cosmos.PartitionKey> * Microsoft.Azure.Cosmos.ItemRequestOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Azure.Cosmos.ItemResponse<'T>>
Public MustOverride Function UpsertItemAsync(Of T) (item As T, Optional partitionKey As Nullable(Of PartitionKey) = null, Optional requestOptions As ItemRequestOptions = null, Optional cancellationToken As CancellationToken = null) 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>

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

requestOptions
ItemRequestOptions

(Optional) The options for the item request.

cancellationToken
CancellationToken

(Optional) CancellationToken representing request cancellation.

Returns

Task<ItemResponse<T>>

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

Exceptions

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

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:

StatusCodeReason for exception
400BadRequest - This means something was wrong with the document supplied.
403Forbidden - This likely means the collection in to which you were trying to upsert the document is full.
413RequestEntityTooLarge - This means the item exceeds the current max entity size. Consult documentation for limits and quotas.
429TooManyRequests - 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));

Applies to