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
GoogleCloudFirestoreAssembly
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)| Parameter | |
|---|---|
| Name | Description |
other | DocumentReference |
| Returns | |
|---|---|
| Type | Description |
int | |
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()| Returns | |
|---|---|
| Type | Description |
int | |
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 | |
|---|---|
| Type | Description |
string | |
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. |