IDocumentClient.UpsertDocumentAsync Method

Definition

Namespace:

Microsoft.Azure.Documents

Assemblies:

Microsoft.Azure.DocumentDB.Core.dll, Microsoft.Azure.Documents.Client.dll

Packages:

Microsoft.Azure.DocumentDB v2.18.0, Microsoft.Azure.DocumentDB.Core v2.18.0

Overloads

UpsertDocumentAsync(String, Object, RequestOptions, Boolean, CancellationToken)	Upserts a Document as an asychronous operation in the Azure Cosmos DB service.
UpsertDocumentAsync(Uri, Object, RequestOptions, Boolean, CancellationToken)	Upserts a document as an asychronous operation in the Azure Cosmos DB service.

UpsertDocumentAsync(String, Object, RequestOptions, Boolean, CancellationToken)

Upserts a Document as an asychronous operation in the Azure Cosmos DB service.

public System.Threading.Tasks.Task<Microsoft.Azure.Documents.Client.ResourceResponse<Microsoft.Azure.Documents.Document>> UpsertDocumentAsync (string collectionLink, object document, Microsoft.Azure.Documents.Client.RequestOptions options = default, bool disableAutomaticIdGeneration = false, System.Threading.CancellationToken cancellationToken = default);

abstract member UpsertDocumentAsync : string * obj * Microsoft.Azure.Documents.Client.RequestOptions * bool * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Azure.Documents.Client.ResourceResponse<Microsoft.Azure.Documents.Document>>

Public Function UpsertDocumentAsync (collectionLink As String, document As Object, Optional options As RequestOptions = Nothing, Optional disableAutomaticIdGeneration As Boolean = false, Optional cancellationToken As CancellationToken = Nothing) As Task(Of ResourceResponse(Of Document))

Parameters

collectionLink

String

The link of the DocumentCollection to upsert the document in. E.g. dbs/db_rid/colls/coll_rid/

document

Object

The document object to upsert.

options

RequestOptions

(Optional) Any request options you wish to set. E.g. Specifying a Trigger to execute when creating the document. RequestOptions

disableAutomaticIdGeneration

Boolean

(Optional) Disables the automatic id generation, If this is True the system will throw an exception if the id property is missing from the Document.

cancellationToken

CancellationToken

(Optional) A CancellationToken that can be used by other objects or threads to receive notice of cancellation.

Returns

Task<ResourceResponse<Document>>

The Document that was upserted contained within a Task object representing the service response for the asynchronous operation.

Exceptions

ArgumentNullException

If either collectionLink or document is not set.

AggregateException

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

DocumentClientException

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. It is likely that disableAutomaticIdGeneration was true and an id was not supplied
403	Forbidden - This likely means the collection in to which you were trying to upsert the document is full.
409	Conflict - This means a Document with an id matching the id field of document already existed
413	RequestEntityTooLarge - This means the Document 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

Azure Cosmos DB supports a number of different ways to work with documents. A document can extend Resource

public class MyObject : Resource
{
    public string MyProperty {get; set;}
}

using (IDocumentClient client = new DocumentClient(new Uri("service endpoint"), "auth key"))
{
    Document doc = await client.UpsertDocumentAsync("dbs/db_rid/colls/coll_rid/", new MyObject { MyProperty = "A Value" });
}

A document can be any POCO object that can be serialized to JSON, even if it doesn't extend from Resource

public class MyPOCO
{
    public string MyProperty {get; set;}
}

using (IDocumentClient client = new DocumentClient(new Uri("service endpoint"), "auth key"))
{
    Document doc = await client.UpsertDocumentAsync("dbs/db_rid/colls/coll_rid/", new MyPOCO { MyProperty = "A Value" });
}

A Document can also be a dynamic object

using (IDocumentClient client = new DocumentClient(new Uri("service endpoint"), "auth key"))
{
    Document doc = await client.UpsertDocumentAsync("dbs/db_rid/colls/coll_rid/", new { SomeProperty = "A Value" } );
}

Upsert a Document and execute a Pre and Post Trigger

using (IDocumentClient client = new DocumentClient(new Uri("service endpoint"), "auth key"))
{
    Document doc = await client.UpsertDocumentAsync(
        "dbs/db_rid/colls/coll_rid/",
        new { id = "DOC123213443" },
        new RequestOptions
        {
            PreTriggerInclude = new List<string> { "MyPreTrigger" },
            PostTriggerInclude = new List<string> { "MyPostTrigger" }
        });
}

See also

• Document
• RequestOptions
• ResourceResponse<TResource>
• Task

UpsertDocumentAsync(Uri, Object, RequestOptions, Boolean, CancellationToken)

Upserts a document as an asychronous operation in the Azure Cosmos DB service.

public System.Threading.Tasks.Task<Microsoft.Azure.Documents.Client.ResourceResponse<Microsoft.Azure.Documents.Document>> UpsertDocumentAsync (Uri documentCollectionUri, object document, Microsoft.Azure.Documents.Client.RequestOptions options = default, bool disableAutomaticIdGeneration = false, System.Threading.CancellationToken cancellationToken = default);

abstract member UpsertDocumentAsync : Uri * obj * Microsoft.Azure.Documents.Client.RequestOptions * bool * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Azure.Documents.Client.ResourceResponse<Microsoft.Azure.Documents.Document>>

Public Function UpsertDocumentAsync (documentCollectionUri As Uri, document As Object, Optional options As RequestOptions = Nothing, Optional disableAutomaticIdGeneration As Boolean = false, Optional cancellationToken As CancellationToken = Nothing) As Task(Of ResourceResponse(Of Document))

Parameters

documentCollectionUri

Uri

The URI of the document collection to upsert the document in.

document

Object

The document object.

options

RequestOptions

(Optional) The RequestOptions for the request.

disableAutomaticIdGeneration

Boolean

A flag to disable the automatic id generation.

cancellationToken

CancellationToken

(Optional) A CancellationToken that can be used by other objects or threads to receive notice of cancellation.

Returns

Task<ResourceResponse<Document>>

The task object representing the service response for the asynchronous operation.