4.6.0 (latest) 4.5.0 4.4.0 4.3.0 4.2.0 4.1.0 4.0.0 3.13.0 3.12.0 3.11.0 3.10.0 3.9.0 3.8.0 3.7.0 3.6.0 3.5.1 3.4.0 3.3.0 3.2.0 3.1.0 3.0.0 2.5.0 2.4.0 2.3.1

    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.

## Inheritance

[object](https://learn.microsoft.com/dotnet/api/system.object) \> DocumentReference

## Implements

[IEquatable](https://learn.microsoft.com/dotnet/api/system.iequatable-1)[DocumentReference](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.DocumentReference), [IComparable](https://learn.microsoft.com/dotnet/api/system.icomparable-1)[DocumentReference](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.DocumentReference)

## Inherited Members

[object.GetType()](https://learn.microsoft.com/dotnet/api/system.object.gettype)

## Namespace

[Google.Cloud.Firestore](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore)

## Assembly

Google.Cloud.Firestore.dll

## Properties

### Database

    public FirestoreDb Database { get; }

The database which contains the document.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.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** |
| `https://learn.microsoft.com/dotnet/api/system.string` |   |

### Parent

    public CollectionReference Parent { get; }

The parent collection. Never null.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.CollectionReference` |   |

### Path

    public string Path { get; }

The complete document path, including project and database ID.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.string` |   |

## Methods

### Collection(string)

    public CollectionReference Collection(string path)

Creates a [CollectionReference](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.CollectionReference) for a child collection of this document.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `path` | `https://learn.microsoft.com/dotnet/api/system.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** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.CollectionReference` | A [CollectionReference](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.CollectionReference) for the specified collection. |

### CompareTo(DocumentReference)

    public int CompareTo(DocumentReference other)

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `other` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.DocumentReference` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.int32` |   |

### 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` | `https://learn.microsoft.com/dotnet/api/system.object` The data for the document. Must not be null. |
| `cancellationToken` | `https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken` A cancellation token to monitor for the asynchronous operation. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.WriteResult` | 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` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.Precondition` Optional precondition for deletion. May be null, in which case the deletion is unconditional. |
| `cancellationToken` | `https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken` A cancellation token to monitor for the asynchronous operation. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.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](https://cloud.google.com/dotnet/docs/reference/Grpc.Core/latest/Grpc.Core.RpcException.html).

### GetHashCode()

    public override int GetHashCode()

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.int32` |   |

**Overrides** [object.GetHashCode()](https://learn.microsoft.com/dotnet/api/system.object.gethashcode)

### GetSnapshotAsync(CancellationToken)

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

Asynchronously fetches a snapshot of the document.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `cancellationToken` | `https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken` |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.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** |
| `https://learn.microsoft.com/dotnet/api/system.collections.generic.iasyncenumerable-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.CollectionReference` | 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)](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.DocumentReference#Google_Cloud_Firestore_DocumentReference_Listen_System_Func_Google_Cloud_Firestore_DocumentSnapshot_System_Threading_CancellationToken_System_Threading_Tasks_Task__System_Threading_CancellationToken_),
wrapping a synchronous callback to create an asynchronous one.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `callback` | `https://learn.microsoft.com/dotnet/api/system.action-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.DocumentSnapshot` The callback to invoke each time the query results change. Must not be null. |
| `cancellationToken` | `https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken` Optional cancellation token which may be used to cancel the listening operation. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.FirestoreChangeListener` | A [FirestoreChangeListener](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.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` | `https://learn.microsoft.com/dotnet/api/system.func-3https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.DocumentSnapshothttps://learn.microsoft.com/dotnet/api/system.threading.cancellationtokenhttps://learn.microsoft.com/dotnet/api/system.threading.tasks.task` The callback to invoke each time the document changes. Must not be null. |
| `cancellationToken` | `https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken` Optional cancellation token which may be used to cancel the listening operation. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.FirestoreChangeListener` | A [FirestoreChangeListener](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.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` | `https://learn.microsoft.com/dotnet/api/system.object` The data to store in the document. Must not be null. |
| `options` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.SetOptions` The options to use when updating the document. May be null, which is equivalent to [Overwrite](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.SetOptions#Google_Cloud_Firestore_SetOptions_Overwrite). |
| `cancellationToken` | `https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken` A cancellation token to monitor for the asynchronous operation. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.WriteResult` | The write result of the server operation. |

### ToString()

    public override string ToString()

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.string` |   |

**Overrides** [object.ToString()](https://learn.microsoft.com/dotnet/api/system.object.tostring)

### 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` | `https://learn.microsoft.com/dotnet/api/system.collections.generic.idictionary-2https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.FieldPathhttps://learn.microsoft.com/dotnet/api/system.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` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.Precondition` Optional precondition for updating the document. May be null, which is equivalent to [MustExist](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.Precondition#Google_Cloud_Firestore_Precondition_MustExist). |
| `cancellationToken` | `https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken` A cancellation token to monitor for the asynchronous operation. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.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)

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

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `updates` | `https://learn.microsoft.com/dotnet/api/system.collections.generic.idictionary-2https://learn.microsoft.com/dotnet/api/system.stringhttps://learn.microsoft.com/dotnet/api/system.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` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.Precondition` Optional precondition for updating the document. May be null, which is equivalent to [MustExist](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.Precondition#Google_Cloud_Firestore_Precondition_MustExist). |
| `cancellationToken` | `https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken` A cancellation token to monitor for the asynchronous operation. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.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)

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

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `field` | `https://learn.microsoft.com/dotnet/api/system.string` The dot-separated name of the field to update. Must not be null. |
| `value` | `https://learn.microsoft.com/dotnet/api/system.object` The new value for the field. May be null. |
| `precondition` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.Precondition` Optional precondition for updating the document. May be null, which is equivalent to [MustExist](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.Precondition#Google_Cloud_Firestore_Precondition_MustExist). |
| `cancellationToken` | `https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken` A cancellation token to monitor for the asynchronous operation. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Firestore/latest/Google.Cloud.Firestore.WriteResult` | The write result of the server operation. |