MVFC.Aspire.Helpers.GcpFirestore 10.1.0

MVFC.Aspire.Helpers.GcpFirestore

🇧🇷 Leia em Português

Helpers for integrating with Google Cloud Firestore in .NET Aspire projects, including support for the emulator.

Motivation

Working with Google Cloud Firestore locally usually means:

• Spinning up an emulator container by hand.
• Remembering ports, project IDs and environment variables.
• Manually configuring readiness checks for the emulator.

With .NET Aspire you can define containers, but you still need to:

• Configure the emulator image and its ports.
• Keep emulator environment variables in sync across projects.
• Define project configurations in a consistent way before the application runs.

MVFC.Aspire.Helpers.GcpFirestore provides:

• AddGcpFirestore(...) to start the emulator.
• WithFirestoreConfigs(...) to describe project configurations in code.
• WithReference(...) to wire projects to the emulator and inject connection configurations automatically.

Overview

This project facilitates the configuration and integration of Google Cloud Firestore in distributed .NET Aspire applications, providing extension methods to:

• Add the Google Cloud Firestore emulator.
• Configure project IDs automatically upon startup.
• Properly inject the emulator host connection string for automatic detection by Firestore clients.

Firestore emulator advantages

• Simulates Firestore databases locally for development and testing.
• Allows testing data operations without depending on Google Cloud infrastructure.
• Facilitates development of robust data storage implementations.

Compatible Images

• Emulator:
  • mtlynch/firestore-emulator (Default in Aspire helper)

Project Structure

• MVFC.Aspire.Helpers.GcpFirestore: Helpers and extensions library for Firestore.

Features

• Adds the Google Cloud Firestore emulator.
• Configures project IDs according to configuration.
• Native TCP port health checks ensure the emulator is fully ready before projects start consuming it.
• Extension methods to facilitate AppHost configuration.

Installation

dotnet add package MVFC.Aspire.Helpers.GcpFirestore

Quick Aspire usage (AppHost)

using Aspire.Hosting;
using MVFC.Aspire.Helpers.GcpFirestore;
using MVFC.Aspire.Helpers.GcpFirestore.Models;

var builder = DistributedApplication.CreateBuilder(args);

var firestoreConfig = new FirestoreConfig(
    projectId: "test-project");

var firestore = builder.AddGcpFirestore("gcp-firestore")
                       .WithFirestoreConfigs(firestoreConfig);

builder.AddProject<Projects.MVFC_Aspire_Helpers_Playground_Api>("api-example")
       .WithReference(firestore)
       .WaitFor(firestore);

await builder.Build().RunAsync();

Emulated Resources Configuration

FirestoreConfig

Ports

• HTTP Port: 8084 (mapped to internal port 8080 in the container)

Provisioning diagram

sequenceDiagram
    participant Aspire as .NET Aspire
    participant Container as Firestore Emulator Container
    participant Configurator as Config Processor
    
    Aspire->>Container: Start container (mtlynch/firestore-emulator)
    Container-->>Aspire: Ready (HTTP port 8084 available)
    Aspire->>Configurator: Trigger OnResourceReady
    Configurator-->>Aspire: Provisioning Completed
    Aspire->>App: Start App with FIRESTORE_EMULATOR_HOST

Public methods

• AddGcpFirestore – adds the emulator container.
• WithFirestoreConfigs – configures project IDs.
• WithDockerImage – replaces the Docker image used by the resource.
• WithReference – wires projects to the emulator and sets the FIRESTORE_EMULATOR_HOST environment variable automatically.

Requirements

• .NET 9+
• Aspire.Hosting >= 13.5.3
• Docker running locally
• Google.Cloud.Firestore >= 4.4.0

License

Apache-2.0