FirebaseExtensions 10.1.0

Firebase Extensions for C# (.NET 10)

This library provides convenient extension methods for working with Google Cloud Firestore in your .NET applications, simplifying Firebase initialization, configuration inspection, and document/collection CRUD operations using the fluent ErrorOr pattern.

Installation

Ensure you have the following NuGet packages installed:

• Google.Cloud.Firestore (4.4.0+)
• ErrorOr (2.1.1+)
• FirebaseAdmin (optional, for Firebase Admin features)

Firebase Project Setup

1. Create a Firebase Project: If you don't have one already, create a project on the Firebase Console.
2. Generate a Service Account Key:
   • In the Firebase console, navigate to Project settings → Service accounts.
   • Click Generate new private key.
   • Download the JSON credentials file and keep it secure.

Usage

1. Initializing Firebase and Firestore

You can initialize Firebase via the static Firebase.Current singleton or by registering IFirebase in your Dependency Injection container:

using ErrorOr;
using Fishman.Firebase.Extension;
using Google.Cloud.Firestore;

// 1. Specify the path to your service account JSON file
string serviceAccountPath = "path/to/your/serviceAccountKey.json";

// 2. Set the configuration path
ErrorOr<Success> pathResult = Firebase.Current.SetPathFile(serviceAccountPath);
if (pathResult.IsError)
{
    Console.WriteLine($"Failed to set path: {pathResult.FirstError.Description}");
    return;
}

// 3. Initialize Firestore (automatically reads project ID from JSON)
ErrorOr<Success> initResult = Firebase.Current.Init();
if (initResult.IsError)
{
    Console.WriteLine($"Initialization failed: {initResult.FirstError.Description}");
    return;
}

FirestoreDb? db = Firebase.Current.FirestoreDb;
Console.WriteLine($"Connected to Firestore project: {db?.ProjectId}");

2. Dependency Injection Support

Firebase implements IFirebase and provides a public constructor, making it simple to register in IServiceCollection:

services.AddSingleton<IFirebase, Firebase>();

3. Data Model Definition

To use custom C# classes with Firestore, always decorate them with [FirestoreData] and their properties with [FirestoreProperty]:

using Google.Cloud.Firestore;

[FirestoreData]
public class User
{
    [FirestoreProperty]
    public string Name { get; set; } = string.Empty;

    [FirestoreProperty]
    public int Age { get; set; }

    public User() { }

    public User(string name, int age)
    {
        Name = name;
        Age = age;
    }
}

4. Firestore CRUD Operations

All extension methods return ErrorOr<T> for predictable, exception-safe error handling.

using ErrorOr;
using Fishman.Firebase.Extension;
using Fishman.Firebase.Firestore;
using Google.Cloud.Firestore;

FirestoreDb db = Firebase.Current.FirestoreDb!;
DocumentReference docRef = db.Collection("Users").Document("user_123");

// CREATE / SET
User user = new("Oleg", 20);
ErrorOr<WriteResult> setResult = await docRef.SetValueAsync(user);
if (setResult.IsError)
{
    Console.WriteLine($"Set failed: {setResult.FirstError.Description}");
}

// READ / GET
ErrorOr<User> getResult = await docRef.GetValueAsync<User>();
if (getResult.IsError)
{
    Console.WriteLine($"Get failed: {getResult.FirstError.Description}");
}
else
{
    Console.WriteLine($"User: {getResult.Value.Name}, Age: {getResult.Value.Age}");
}

// UPDATE FIELDS
Dictionary<string, object> updates = new()
{
    { nameof(User.Age), 21 }
};
ErrorOr<WriteResult> updateResult = await docRef.UpdateFieldsAsync(updates);

// DELETE
ErrorOr<WriteResult> deleteResult = await docRef.DeleteValueAsync();

// COLLECTION OPERATIONS
CollectionReference colRef = db.Collection("Users");

// Add document with auto-generated ID
ErrorOr<DocumentReference> addResult = await colRef.AddValueAsync(new User("Anna", 28));

// Read all documents from collection
ErrorOr<IReadOnlyList<User>> allUsers = await colRef.GetAllValuesAsync<User>();
if (!allUsers.IsError)
{
    Console.WriteLine($"Found {allUsers.Value.Count} users.");
}

5. Reading Service Account Configuration

You can safely inspect properties from the loaded service account JSON without re-parsing files:

ErrorOr<string> projectId = Firebase.Current.GetProjectId();
ErrorOr<string> clientEmail = Firebase.Current.GetClientEmail();
ErrorOr<string> universeDomain = Firebase.Current.GetUniverseDomain();

6. Resource Cleanup

Firebase implements IDisposable to clean up cached JSON documents:

Firebase.Current.Dispose();