Google.Cloud.Firestore

Google.Cloud.Firestore is a.NET client library for the Firestore API.

Note: This documentation is for version 2.3.1 of the library. Some samples may not work with other versions.

Installation

Install the Google.Cloud.Firestore package from NuGet. Add it to your project in the normal way (for example by right-clicking on the project in Visual Studio and choosing "Manage NuGet Packages...").

Authentication

When running on Google Cloud Platform, no action needs to be taken to authenticate.

Otherwise, the simplest way of authenticating your API calls is to download a service account JSON file then set the GOOGLE_APPLICATION_CREDENTIALS environment variable to refer to it. The credentials will automatically be used to authenticate. See the Getting Started With Authentication guide for more details.

Getting started

Everything starts with FirestoreDb. Create an instance using the Create or CreateAsync methods, passing in your Google Cloud project ID. The default credentials will be used to authenticate with the server. FirestoreDb is thread-safe, and we recommend using a single instance across your application where possible.

From there, you can create, fetch and modify documents, and run queries.

For customization of credentials and other settings, create a FirestoreDbBuilder, set the appropriate properties, and call Build to create a FirestoreDb.

Sample code

FirestoreDb db = FirestoreDb.Create(projectId);

// Create a document with a random ID in the "users" collection.
CollectionReference collection = db.Collection("users");
DocumentReference document = await collection.AddAsync(new { Name = new { First = "Ada", Last = "Lovelace" }, Born = 1815 });

// A DocumentReference doesn't contain the data - it's just a path.
// Let's fetch the current document.
DocumentSnapshot snapshot = await document.GetSnapshotAsync();

// We can access individual fields by dot-separated path
Console.WriteLine(snapshot.GetValue<string>("Name.First"));
Console.WriteLine(snapshot.GetValue<string>("Name.Last"));
Console.WriteLine(snapshot.GetValue<int>("Born"));

// Or deserialize the whole document into a dictionary
Dictionary<string, object> data = snapshot.ToDictionary();
Dictionary<string, object> name = (Dictionary<string, object>) data["Name"];
Console.WriteLine(name["First"]);
Console.WriteLine(name["Last"]);

// See the "data model" guide for more options for data handling.

// Query the collection for all documents where doc.Born < 1900.
Query query = collection.WhereLessThan("Born", 1900);
QuerySnapshot querySnapshot = await query.GetSnapshotAsync();
foreach (DocumentSnapshot queryResult in querySnapshot.Documents)
{
    string firstName = queryResult.GetValue<string>("Name.First");
    string lastName = queryResult.GetValue<string>("Name.Last");
    int born = queryResult.GetValue<int>("Born");
    Console.WriteLine($"{firstName} {lastName}; born {born}");
}

See the user guide for more samples.

Connecting to the emulator

To connect to the Firestore Emulator, you need to:

  • Connect to the emulator endpoint
  • Use ChannelCredentials.Insecure as the channel credentials
  • Specify an "Authorization: Bearer owner" header on each request

As of version 1.1.0-beta02, the library has support for detecting the emulator via the environment variable and connecting to it automatically, if requested. This is configured via FirestoreDbBuilder, which can also be used to configure custom credentials easily.

The following code creates a FirestoreDb which will use the emulator when the environment variables are present, but will otherwise connect to the production environment.

FirestoreDb db = new FirestoreDbBuilder
{
    ProjectId = projectId,
    EmulatorDetection = EmulatorDetection.EmulatorOrProduction
}.Build();
// Use db as normal

See the EmulatorDetection property for more details.