public sealed class DocumentReference : IEquatable<DocumentReference>, IComparable<DocumentReference>Reference documentation and code samples for the Firestore API 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.
Namespace
Google.Cloud.FirestoreAssembly
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 | stringThe 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)Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object.
| Parameter | |
|---|---|
| Name | Description |
other | DocumentReferenceAn object to compare with this instance. |
| Returns | |
|---|---|
| Type | Description |
int | A value that indicates the relative order of the objects being compared. The return value has these meanings: Meaning Less than zero This instance precedes Zero This instance occurs in the same position in the sort order as Greater than zero This instance follows |
CreateAsync(object, CancellationToken)
public Task<WriteResult> CreateAsync(object documentData, CancellationToken cancellationToken = default)Asynchronously creates a document on the server with the given data. The document must not exist beforehand.
| Parameters | |
|---|---|
| Name | Description |
documentData | objectThe data for the document. Must not be null. |
cancellationToken | CancellationTokenA cancellation token to monitor for the asynchronous operation. |
| Returns | |
|---|---|
| Type | Description |
TaskWriteResult | The write result of the server operation. |
DeleteAsync(Precondition, CancellationToken)
public Task<WriteResult> DeleteAsync(Precondition precondition = null, CancellationToken cancellationToken = default)Asynchronously deletes the document referred to by this path, with an optional precondition.
| Parameters | |
|---|---|
| Name | Description |
precondition | PreconditionOptional precondition for deletion. May be null, in which case the deletion is unconditional. |
cancellationToken | CancellationTokenA cancellation token to monitor for the asynchronous operation. |
| Returns | |
|---|---|
| Type | Description |
TaskWriteResult | The write result of the server operation. |
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()Serves as the default hash function.
| Returns | |
|---|---|
| Type | Description |
int | A hash code for the current object. |
GetSnapshotAsync(CancellationToken)
public Task<DocumentSnapshot> GetSnapshotAsync(CancellationToken cancellationToken = default)Asynchronously fetches a snapshot of the document.
| Parameter | |
|---|---|
| Name | Description |
cancellationToken | CancellationToken |
| Returns | |
|---|---|
| Type | Description |
TaskDocumentSnapshot | 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 |
IAsyncEnumerableCollectionReference | A lazily-iterated sequence of collection references within this document. |
Listen(Action<DocumentSnapshot>, CancellationToken)
public FirestoreChangeListener Listen(Action<DocumentSnapshot> callback, CancellationToken cancellationToken = default)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 | ActionDocumentSnapshotThe callback to invoke each time the query results change. Must not be null. |
cancellationToken | CancellationTokenOptional 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)Watch this document for changes.
| Parameters | |
|---|---|
| Name | Description |
callback | FuncDocumentSnapshotCancellationTokenTaskThe callback to invoke each time the document changes. Must not be null. |
cancellationToken | CancellationTokenOptional 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)Asynchronously sets data in the document, either replacing it completely or merging fields.
| Parameters | |
|---|---|
| Name | Description |
documentData | objectThe data to store in the document. Must not be null. |
options | SetOptionsThe options to use when updating the document. May be null, which is equivalent to Overwrite. |
cancellationToken | CancellationTokenA cancellation token to monitor for the asynchronous operation. |
| Returns | |
|---|---|
| Type | Description |
TaskWriteResult | The write result of the server operation. |
ToString()
public override string ToString()Returns a string that represents the current object.
| Returns | |
|---|---|
| Type | Description |
string | A string that represents the current object. |
UpdateAsync(IDictionary<FieldPath, object>, Precondition, CancellationToken)
public Task<WriteResult> UpdateAsync(IDictionary<FieldPath, object> updates, Precondition precondition = null, CancellationToken cancellationToken = default)Asynchronously performs a set of updates on the document referred to by this path, with an optional precondition.
| Parameters | |
|---|---|
| Name | Description |
updates | IDictionaryFieldPathobjectThe 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 | PreconditionOptional precondition for updating the document. May be null, which is equivalent to MustExist. |
cancellationToken | CancellationTokenA cancellation token to monitor for the asynchronous operation. |
| Returns | |
|---|---|
| Type | Description |
TaskWriteResult | 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)Asynchronously performs a set of updates on the document referred to by this path, with an optional precondition.
| Parameters | |
|---|---|
| Name | Description |
updates | IDictionarystringobjectThe 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 | PreconditionOptional precondition for updating the document. May be null, which is equivalent to MustExist. |
cancellationToken | CancellationTokenA cancellation token to monitor for the asynchronous operation. |
| Returns | |
|---|---|
| Type | Description |
TaskWriteResult | 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)Asynchronously performs a single field update on the document referred to by this path, with an optional precondition.
| Parameters | |
|---|---|
| Name | Description |
field | stringThe dot-separated name of the field to update. Must not be null. |
value | objectThe new value for the field. May be null. |
precondition | PreconditionOptional precondition for updating the document. May be null, which is equivalent to MustExist. |
cancellationToken | CancellationTokenA cancellation token to monitor for the asynchronous operation. |
| Returns | |
|---|---|
| Type | Description |
TaskWriteResult | The write result of the server operation. |