Class 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()

Namespace: Google.Cloud.Firestore

Assembly: Google.Cloud.Firestore.dll

Syntax

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

Properties

Database

The database which contains the document.

Declaration

public FirestoreDb Database { get; }

Property Value

Type	Description
FirestoreDb

Id

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

Declaration

public string Id { get; }

Property Value

Type	Description
string

Parent

The parent collection. Never null.

Declaration

public CollectionReference Parent { get; }

Property Value

Type	Description
CollectionReference

Path

The complete document path, including project and database ID.

Declaration

public string Path { get; }

Property Value

Type	Description
string

Methods

Collection(string)

Creates a CollectionReference for a child collection of this document.

Declaration

public CollectionReference Collection(string path)

Parameters

Type	Name	Description
string	path	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)

Declaration

public int CompareTo(DocumentReference other)

Parameters

Type	Name	Description
DocumentReference	other

Returns

Type	Description
int

Implements

IComparable<T>.CompareTo(T)

CreateAsync(object, CancellationToken)

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

Declaration

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

Parameters

Type	Name	Description
object	documentData	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)

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

Declaration

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

Parameters

Type	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()

Declaration

public override int GetHashCode()

Returns

Type	Description
int

Overrides

object.GetHashCode()

GetSnapshotAsync(CancellationToken)

Asynchronously fetches a snapshot of the document.

Declaration

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

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

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

ListCollectionsAsync()

Retrieves the collections within this document.

Declaration

public IAsyncEnumerable<CollectionReference> ListCollectionsAsync()

Returns

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

Listen(Action<DocumentSnapshot>, 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.

Declaration

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

Parameters

Type	Name	Description
Action<DocumentSnapshot>	callback	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)

Watch this document for changes.

Declaration

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

Parameters

Type	Name	Description
Func<DocumentSnapshot, CancellationToken, Task>	callback	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)

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

Declaration

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

Parameters

Type	Name	Description
object	documentData	The data to store in the document. Must not be null.
SetOptions	options	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()

Declaration

public override string ToString()

Returns

Type	Description
string

Overrides

object.ToString()

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

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

Declaration

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

Parameters

Type	Name	Description
IDictionary<FieldPath, object>	updates	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)

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

Declaration

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

Parameters

Type	Name	Description
IDictionary<string, object>	updates	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)

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

Declaration

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

Parameters

Type	Name	Description
string	field	The dot-separated name of the field to update. Must not be null.
object	value	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.