Skip to main content

Google Firestore Provider

The Firestore provider implements ICloudNativePersistenceProvider for Google Cloud workloads with real-time document listeners, hierarchical collection paths, and batch write support.

Before You Start​

  • .NET 8.0+ (or .NET 9/10 for latest features)
  • A Google Cloud project with Firestore enabled
  • Familiarity with data access and IDb interface

Installation​

dotnet add package Excalibur.Data.Firestore

Dependencies: Excalibur.Data.Abstractions, Google.Cloud.Firestore

Quick Start​

using Microsoft.Extensions.DependencyInjection;

services.AddFirestore(options =>
{
    options.ProjectId = "my-gcp-project";
});

Registration Options​

// With options callback
services.AddFirestore(options =>
{
    options.ProjectId = "my-gcp-project";
    options.EmulatorHost = "localhost:8080"; // Local development
});

// From configuration
services.AddFirestore(configuration);
services.AddFirestore(configuration, sectionName: "Firestore");

// With specific database
services.AddFirestoreWithDatabase(options =>
{
    options.ProjectId = "my-gcp-project";
    options.DatabaseId = "my-database";
});

Snapshot Store​

services.AddFirestoreSnapshotStore(options =>
{
    options.CollectionName = "snapshots";
});

Inbox Store​

services.AddFirestoreInboxStore(options =>
{
    options.CollectionName = "inbox";
});

Change Data Capture​

services.AddFirestoreCdc(options =>
{
    options.CollectionPath = "orders";
});

services.AddFirestoreCdcStateStore(options =>
{
    options.CollectionName = "cdc-state";
});

Collection Hierarchies​

Firestore supports hierarchical document/collection paths:

var key = new PartitionKey("users/user-123/orders", "/collection");
var orders = await provider.QueryAsync<Order>(
    queryText: "",
    key,
    parameters: null,
    consistencyOptions: null,
    cancellationToken: ct);

See Also​