/// <summary>
/// Finds the first document in the collection that satisfies the query criteria.
/// </summary>
/// <param name="filter">
/// A document describing the find criteria using <see href="https://docs.mongodb.com/manual/reference/operator/query/">query operators</see>.
/// If not specified, all documents in the collection will match the request.
/// </param>
/// <param name="replacementDoc">
/// The replacement document. Cannot contain update operator expressions.
/// </param>
/// <param name="sort">
/// A document describing the sort criteria. If not specified, the order of the returned documents is not guaranteed.
/// </param>
/// <param name="projection">
/// A document describing the fields to return for all matching documents. If not specified, all fields are returned.
/// </param>
/// <param name="upsert">
/// A boolean controlling whether the replace should insert a document if no documents match the <paramref name="filter"/>.
/// Defaults to <c>false</c>.
/// <br/>
/// MongoDB will add the <c>_id</c> field to the replacement document if it is not specified in either the filter or
/// replacement documents. If <c>_id</c> is present in both, the values must be equal.
/// </param>
/// <param name="returnNewDocument">
/// A boolean controlling whether to return the replacement document. If set to <c>false</c> the original document
/// before the update is returned. Defaults to <c>false</c>.
/// </param>
/// <returns>
/// An awaitable <see cref="Task{T}"/> representing the remote find one operation. The result of the task is the first document that matches the find criteria.
/// </returns>
/// <seealso href="https://docs.mongodb.com/manual/reference/method/db.collection.findOneAndReplace/"/>
public async Task <TDocument> FindOneAndReplaceAsync(object filter, TDocument replacementDoc, object sort = null, object projection = null, bool upsert = false, bool returnNewDocument = false)
{
Argument.NotNull(replacementDoc, nameof(replacementDoc));
var result = await _handle.FindOneAndReplace(filter?.ToNativeJson(), replacementDoc.ToNativeJson(), FindAndModifyOptions.FindAndModify(projection, sort, upsert, returnNewDocument));
return(result.GetValue <TDocument>());
}
