Class DocumentReference (2.4.0)

public sealed class DocumentReference : IEquatable<DocumentReference>, IComparable<DocumentReference>

A reference to a document in a Firestore database. The existence of this object does not imply that the document currently exists in storage.

Inheritance

Object > DocumentReference

Implements

IEquatable<DocumentReference>, IComparable<DocumentReference>

Inherited Members

Object.GetType()

Object.MemberwiseClone()

Namespace

Google.Cloud.Firestore

Assembly

Google.Cloud.Firestore.dll

Properties

Database

public FirestoreDb Database { get; }

The database which contains the document.

Property Value
Type	Description
`FirestoreDb`

Id

public string Id { get; }

The final part of the complete document path; this is the identity of the document relative to its parent collection.

Property Value
Type	Description
`String`

Parent

public CollectionReference Parent { get; }

The parent collection. Never null.

Property Value
Type	Description
`CollectionReference`

Path

public string Path { get; }

The complete document path, including project and database ID.

Property Value
Type	Description
`String`

Methods

Collection(String)

public CollectionReference Collection(string path)

Creates a CollectionReference for a child collection of this document.

Parameter
Name	Description
`path`	`String` The path to the collection, relative to this document. Must not be null, and must contain an odd number of slash-separated path elements.

Returns
Type	Description
`CollectionReference`	A CollectionReference for the specified collection.

CompareTo(DocumentReference)

public int CompareTo(DocumentReference other)

Parameter
Name	Description
`other`	`DocumentReference`

Returns
Type	Description
`Int32`

CreateAsync(Object, CancellationToken)

public Task<WriteResult> CreateAsync(object documentData, CancellationToken cancellationToken = default(CancellationToken))

Asynchronously creates a document on the server with the given data. The document must not exist beforehand.

Parameters
Name	Description
`documentData`	`Object` The data for the document. Must not be null.
`cancellationToken`	`CancellationToken` A cancellation token to monitor for the asynchronous operation.

Returns
Type	Description
`Task<WriteResult>`	The write result of the server operation.

DeleteAsync(Precondition, CancellationToken)

public Task<WriteResult> DeleteAsync(Precondition precondition = null, CancellationToken cancellationToken = default(CancellationToken))

Asynchronously deletes the document referred to by this path, with an optional precondition.

Parameters
Name	Description
`precondition`	`Precondition` Optional precondition for deletion. May be null, in which case the deletion is unconditional.
`cancellationToken`	`CancellationToken` A cancellation token to monitor for the asynchronous operation.

Returns
Type	Description
`Task<WriteResult>`	The write result of the server operation.

Remarks

If no precondition is specified and the document doesn't exist, this returned task will succeed. If a precondition is specified and not met, the returned task will fail with an RpcException.

GetHashCode()

public override int GetHashCode()

Returns
Type	Description
`Int32`

Overrides

Object.GetHashCode()

GetSnapshotAsync(CancellationToken)

public Task<DocumentSnapshot> GetSnapshotAsync(CancellationToken cancellationToken = default(CancellationToken))

Asynchronously fetches a snapshot of the document.

Parameter
Name	Description
`cancellationToken`	`CancellationToken`

Returns
Type	Description
`Task<DocumentSnapshot>`	A snapshot of the document. The snapshot may represent a missing document.

ListCollectionsAsync()

public IAsyncEnumerable<CollectionReference> ListCollectionsAsync()

Retrieves the collections within this document.

Returns
Type	Description
`IAsyncEnumerable<CollectionReference>`	A lazily-iterated sequence of collection references within this document.

Listen(Action<DocumentSnapshot>, CancellationToken)

public FirestoreChangeListener Listen(Action<DocumentSnapshot> callback, CancellationToken cancellationToken = default(CancellationToken))

Watch this document for changes. This method is a convenience method over Listen(Func<DocumentSnapshot, CancellationToken, Task>, CancellationToken), wrapping a synchronous callback to create an asynchronous one.

Parameters
Name	Description
`callback`	`Action<DocumentSnapshot>` The callback to invoke each time the query results change. Must not be null.
`cancellationToken`	`CancellationToken` Optional cancellation token which may be used to cancel the listening operation.

Returns
Type	Description
`FirestoreChangeListener`	A FirestoreChangeListener which may be used to monitor the listening operation and stop it gracefully.

Listen(Func<DocumentSnapshot, CancellationToken, Task>, CancellationToken)

public FirestoreChangeListener Listen(Func<DocumentSnapshot, CancellationToken, Task> callback, CancellationToken cancellationToken = default(CancellationToken))

Watch this document for changes.

Parameters
Name	Description
`callback`	`Func<DocumentSnapshot, CancellationToken, Task>` The callback to invoke each time the document changes. Must not be null.
`cancellationToken`	`CancellationToken` Optional cancellation token which may be used to cancel the listening operation.

Returns
Type	Description
`FirestoreChangeListener`	A FirestoreChangeListener which may be used to monitor the listening operation and stop it gracefully.

SetAsync(Object, SetOptions, CancellationToken)

public Task<WriteResult> SetAsync(object documentData, SetOptions options = null, CancellationToken cancellationToken = default(CancellationToken))

Asynchronously sets data in the document, either replacing it completely or merging fields.

Parameters
Name	Description
`documentData`	`Object` The data to store in the document. Must not be null.
`options`	`SetOptions` The options to use when updating the document. May be null, which is equivalent to Overwrite.
`cancellationToken`	`CancellationToken` A cancellation token to monitor for the asynchronous operation.

Returns
Type	Description
`Task<WriteResult>`	The write result of the server operation.

ToString()

public override string ToString()

Returns
Type	Description
`String`

Overrides

Object.ToString()

UpdateAsync(IDictionary<FieldPath, Object>, Precondition, CancellationToken)

public Task<WriteResult> UpdateAsync(IDictionary<FieldPath, object> updates, Precondition precondition = null, CancellationToken cancellationToken = default(CancellationToken))

Asynchronously performs a set of updates on the document referred to by this path, with an optional precondition.

Parameters
Name	Description
`updates`	`IDictionary<FieldPath, Object>` The updates to perform on the document, keyed by the field path to update. Fields not present in this dictionary are not updated. Must not be null or empty.
`precondition`	`Precondition` Optional precondition for updating the document. May be null, which is equivalent to MustExist.
`cancellationToken`	`CancellationToken` A cancellation token to monitor for the asynchronous operation.

Returns
Type	Description
`Task<WriteResult>`	The write result of the server operation.

UpdateAsync(IDictionary<String, Object>, Precondition, CancellationToken)

public Task<WriteResult> UpdateAsync(IDictionary<string, object> updates, Precondition precondition = null, CancellationToken cancellationToken = default(CancellationToken))

Asynchronously performs a set of updates on the document referred to by this path, with an optional precondition.

Parameters
Name	Description
`updates`	`IDictionary<String, Object>` The updates to perform on the document, keyed by the dot-separated field path to update. Fields not present in this dictionary are not updated. Must not be null or empty.
`precondition`	`Precondition` Optional precondition for updating the document. May be null, which is equivalent to MustExist.
`cancellationToken`	`CancellationToken` A cancellation token to monitor for the asynchronous operation.

Returns
Type	Description
`Task<WriteResult>`	The write result of the server operation.

UpdateAsync(String, Object, Precondition, CancellationToken)

public Task<WriteResult> UpdateAsync(string field, object value, Precondition precondition = null, CancellationToken cancellationToken = default(CancellationToken))

Asynchronously performs a single field update on the document referred to by this path, with an optional precondition.

Parameters
Name	Description
`field`	`String` The dot-separated name of the field to update. Must not be null.
`value`	`Object` The new value for the field. May be null.
`precondition`	`Precondition` Optional precondition for updating the document. May be null, which is equivalent to MustExist.
`cancellationToken`	`CancellationToken` A cancellation token to monitor for the asynchronous operation.

Returns
Type	Description
`Task<WriteResult>`	The write result of the server operation.