Container.UpsertItemAsync<T> 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) = 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>

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

The ItemResponse<T> that was upserted contained within a Task object representing the service response for the asynchronous 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));

Remarks

Upsert result i.e. creation or replace can be identified by the status code: 201 - item created 200 - item replaced

Applies to