/// <summary>
/// Asynchronously sets data in the document, either replacing it completely or merging fields.
/// </summary>
/// <param name="documentData">The data to store in the document. Must not be null.</param>
/// <param name="options">The options to use when updating the document. May be null, which is equivalent to <see cref="SetOptions.Overwrite"/>.</param>
/// <param name="cancellationToken">A cancellation token to monitor for the asynchronous operation.</param>
/// <returns>The write result of the server operation.</returns>
public async Task <WriteResult> SetAsync(object documentData, SetOptions options = null, CancellationToken cancellationToken = default)
{
var batch = Database.CreateWriteBatch();
batch.Set(this, documentData, options);
var results = await batch.CommitAsync(cancellationToken).ConfigureAwait(false);
return(results[0]);
}
/// <summary>
/// Adds an operation that sets data in a document, either replacing it completely or merging fields.
/// </summary>
/// <param name="documentReference">A document reference indicating the path of the document to update. Must not be null.</param>
/// <param name="documentData">The data to store in the document. Must not be null.</param>
/// <param name="options">The options to use when setting data in the document. May be null, which is equivalent to <see cref="SetOptions.Overwrite"/>.</param>
/// <returns>This batch, for the purposes of method chaining.</returns>
public WriteBatch Set(DocumentReference documentReference, object documentData, SetOptions options = null)
{
GaxPreconditions.CheckNotNull(documentReference, nameof(documentReference));
GaxPreconditions.CheckNotNull(documentData, nameof(documentData));
var fields = ValueSerializer.SerializeMap(documentData);
options = options ?? SetOptions.Overwrite;
var mask = options.FieldMask;
// TODO: Check it's okay to do this *after* serialization. The Java code is somewhat different.
var fieldPaths = mask.Count == 0
? fields.ToDictionary(pair => new FieldPath(pair.Key), pair => pair.Value)
: ApplyFieldMask(fields, mask);
var write = new Write
{
Update = new Document
{
Fields = { ExpandObject(fieldPaths) },
Name = documentReference.Path
}
};
if (options.Merge)
{
var paths = mask.Count == 0 ? ExtractDocumentMask(fields) : mask;
write.UpdateMask = new DocumentMask {
FieldPaths = { paths.Select(fp => fp.EncodedPath) }
};
}
AddUpdate(write);
return(this);
}
/// <summary>
/// Adds an operation to set a document's data in this transaction.
/// </summary>
/// <param name="documentReference">The document in which to set the data. Must not be null.</param>
/// <param name="documentData">The data for the document. Must not be null.</param>
/// <param name="options">The options to use when updating the document. May be null, which is equivalent to <see cref="SetOptions.Overwrite"/>.</param>
public void Set(DocumentReference documentReference, object documentData, SetOptions options = null)
{
// Preconditions are validated by WriteBatch.
_writes.Set(documentReference, documentData, options);
}
