Plugin.CloudFirestore

A cross platform plugin for Firebase Cloud Firestore. A wrapper for Xamarin.Firebase.iOS.CloudFirestore and Xamarin.Firebase.Firestore.

Setup

Install Nuget package to each projects.

Plugin.CloudFirestore

iOS

• Add GoogleService-Info.plist to iOS project. Select BundleResource as build action.
• Initialize as follows in AppDelegate.

Firebase.Core.App.Configure();

Android

• Add google-services.json to Android project. Select GoogleServicesJson as build action. (If you can't select GoogleServicesJson, reload this android project.)
• Target framework version needs to be Android 10.0.

Upgrade from Version 3 to 4

Refer to Upgrade

Usage

Get

var document = await CrossCloudFirestore.Current
                                        .Instance
                                        .Collection("yourcollection")
                                        .Document("yourdocument")
                                        .GetAsync();

var yourModel = document.ToObject<YourModel>();

var query = await CrossCloudFirestore.Current
                                     .Instance
                                     .Collection("yourcollection")
                                     .WhereGreaterThan("Value", 100)
                                     .OrderBy("Value", false)
                                     .LimitTo(3)
                                     .GetAsync();

var yourModels = query.ToObjects<YourModel>();

var group = await CrossCloudFirestore.Current
                                     .Instance
                                     .CollectionGroup("yourcollection")
                                     .GetAsync();

var yourModels = group.ToObjects<YourModel>();

Filters

WhereEqualsTo

var query = await CrossCloudFirestore.Current
                                     .Instance
                                     .Collection("yourcollection")
                                     .WhereEqualsTo("Value", 100)
                                     .GetAsync();                                

WhereGreaterThan

var query = await CrossCloudFirestore.Current
                                     .Instance
                                     .Collection("yourcollection")
                                     .WhereGreaterThan("Value", 100)
                                     .GetAsync();                                

WhereGreaterThanOrEqualsTo

var query = await CrossCloudFirestore.Current
                                     .Instance
                                     .Collection("yourcollection")
                                     .WhereGreaterThanOrEqualsTo("Value", 100)
                                     .GetAsync();                                

WhereLessThan

var query = await CrossCloudFirestore.Current
                                     .Instance
                                     .Collection("yourcollection")
                                     .WhereLessThan("Value", 100)
                                     .GetAsync();                                

WhereLessThanOrEqualsTo

var query = await CrossCloudFirestore.Current
                                     .Instance
                                     .Collection("yourcollection")
                                     .WhereLessThanOrEqualsTo("Value", 100)
                                     .GetAsync();                                

WhereArrayContains

var query = await CrossCloudFirestore.Current
                                     .Instance
                                     .Collection("yourcollection")
                                     .WhereArrayContains("Values", 100)
                                     .GetAsync();                                

WhereArrayContainsAny

var query = await CrossCloudFirestore.Current
                                     .Instance
                                     .Collection("yourcollection")
                                     .WhereArrayContainsAny("Values", new object[] { 100, 200 })
                                     .GetAsync();                                

WhereIn

var query = await CrossCloudFirestore.Current
                                     .Instance
                                     .Collection("yourcollection")
                                     .WhereIn("Value", new object[] { 100, 200 })
                                     .GetAsync();                                

Add

await CrossCloudFirestore.Current
                         .Instance
                         .Collection("yourcollection")
                         .AddAsync(new YourModel());

Update

await CrossCloudFirestore.Current
                         .Instance
                         .Collection("yourcollection")
                         .Document("yourdocument")
                         .UpdateAsync(new { Value = 10 });

Set

await CrossCloudFirestore.Current
                         .Instance
                         .Collection("yourcollection")
                         .Document("yourdocument")
                         .SetAsync(new { Value = 1 });

// Create a document with auto-generated ID
await CrossCloudFirestore.Current
                         .Instance
                         .Collection("yourcollection")
                         .Document()
                         .SetAsync(new { Value = 2 });

Delete

await CrossCloudFirestore.Current
                         .Instance
                         .Collection("yourcollection")
                         .Document("yourdocument")
                         .DeleteAsync();

Transaction

var reference = CrossCloudFirestore.Current
                                   .Instance
                                   .Collection("yourcollection")
                                   .Document("yourdocument");

await CrossCloudFirestore.Current.Instance.RunTransactionAsync((transaction) =>
{
    var document = transaction.Get(reference);
    var yourModel = document.ToObject<YourModel>();
    
    yourModel.Value++;
    
    transaction.Update(reference, yourModel);
});

Batch

var reference1 = CrossCloudFirestore.Current
                                    .Instance
                                    .Collection("yourcollection")
                                    .Document("yourdocument1");

var reference2 = CrossCloudFirestore.Current
                                    .Instance
                                    .Collection("yourcollection")
                                    .Document("yourdocument2");
                                    
var reference3 = CrossCloudFirestore.Current
                                    .Instance
                                    .Collection("yourcollection")
                                    .Document("yourdocument3");

await CrossCloudFirestore.Current
                         .Instance
                         .Batch()
                         .Set(reference1, new YourModel())
                         .Update(reference2, "Value", 100)
                         .Delete(reference3)
                         .CommitAsync();

Realtime Update

CrossCloudFirestore.Current.Instance.Collection("yourcollection")
                           .Document("yourdocument")
                           .AddSnapshotListener((snapshot, error) =>
                           {
                               ...
                           });

CrossCloudFirestore.Current
                   .Instance
                   .Collection("yourcollection")
                   .AddSnapshotListener((snapshot, error) =>
                   {
                       if(snapshot != null) 
                       {
                           foreach (var documentChange in snapshot.DocumentChanges)
                           {
                               switch (documentChange.Type)
                               {
                                   case DocumentChangeType.Added:
                                       // Document Added
                                       break;
                                   case DocumentChangeType.Modified:
                                       // Document Modified
                                       break;
                                   case DocumentChangeType.Removed:
                                       // Document Removed
                                       break;
                                }
                            }
                        }
                    });

Use of Reactive Extensions

CrossCloudFirestore.Current.Instance
                           .Collection("yourcollection")
                           .Document("yourdocument")
                           .AsObservable()
                           .Subscribe(document =>
                           {
                               ...
                           });
// Added                        
CrossCloudFirestore.Current
                   .Instance
                   .Collection("yourcollection")
                   .ObserveAdded()
                   .Subscribe(documentChange =>
                   {
                       var document = documentChange.Document
                       ...
                   });

// Modified  
CrossCloudFirestore.Current
                   .Instance
                   .Collection("yourcollection")
                   .ObserveModified()
                   .Subscribe(documentChange =>
                   {
                       var document = documentChange.Document
                       ...
                   });

// Removed 
CrossCloudFirestore.Current
                   .Instance
                   .Collection("yourcollection")
                   .ObserveRemoved()
                   .Subscribe(documentChange =>
                   {
                       var document = documentChange.Document
                       ...
                   });

FieldPath

var query = await CrossCloudFirestore.Current
                                     .Instance
                                     .Collection("yourcollection")
                                     .WhereEqualsTo(FieldPath.DocumentId, "yourdocument")
                                     .GetDocumentsAsync();
                                     
await CrossCloudFirestore.Current
                         .Instance
                         .Collection("yourcollection")
                         .Document("yourdocument")
                         .UpdateAsync(new FieldPath("a", "b"), 1);
                         
// Create From Class Properties
var fieldPath = FieldPath.CreateFrom((YourModel model) => model.A.B);

FieldValue

var data = new
{
    DeletedValue = FieldValue.Delete,
    Date = FieldValue.ServerTimestamp,
    UnionArray = FieldValue.ArrayUnion(1, 2),
    RemovedArray = FieldValue.ArrayRemove(3, 4),
    LongValue = FieldValue.Increment(1),
    DoubleValue = FieldValue.Increment(2.5),
};

await CrossCloudFirestore.Current
                         .Instance
                         .Collection("yourcollection")
                         .Document("yourdocument")
                         .UpdateDataAsync(data);

Use Multiple Projects

var document = await CrossCloudFirestore.Current
                                        .GetInstance("SecondAppName")
                                        .Collection("yourcollection")
                                        .Document("yourdocument")
                                        .GetAsync();

Settings

CrossCloudFirestore.Current.Instance.FirestoreSettings = new FirestoreSettings
{
    CacheSizeBytes = FirestoreSettings.CacheSizeUnlimited
};

Data Mapping

This library can map native data to .NET data and .NET data to native data.

// native to .NET
var yourModel = document.ToObject<YourModel>();

// .NET to native
await CrossCloudFirestore.Current
                         .Instance
                         .Collection("yourcollection")
                         .DocumentAsync(new YourModel());

Support Data Type

Firestore Type	.NET Type
Array	System.Collections.IEnumerable
Boolean	bool and bool?
Byte	byte[] and Stream
Date and time	DateTime, DateTimeOffset, Plugin.CloudFirestore.Timestamp and these Nullable
Floating-point number	float, double, decimal and these Nullable
Geographical point	Plugin.CloudFirestore.GeoPoint
Integer	byte, sbyte, short, ushort, int, uint, long, ulong, enum and these Nullable
Map	System.Collections.IDictionary and Any Class
Null	null
Reference	Plugin.CloudFirestore.IDocumentReference
Text string	string, char, char?, Guid and Guid?

Attribute

You can specify attributes to data class properties and fields.

public class YourModel 
{
    [Id]
    public string Id { get; set; }
    
    [MapTo("value")]
    public int Value { get; set; }
    
    [Ignored]
    public string Text { get; set; }
    
    [ServerTimestamp(CanReplace = false)]
    public Timestamp CreatedAt { get; set; }

    [ServerTimestamp]
    public Timestamp UpdatedAt { get; set; }
    
    [DocumentConverter(typeof(EnumStringConverter))]
    public MyEnum Enum { get; set; }
    
    [DocumentConverter(typeof(CustomConverter), 1)]
    public YourModel Model { get; set; }
}

IdAttribute

Document id is set when mapping from native. When mapping to native, specified properties are ignored.

MapToAttribute

Specified name becomes Firestore field name.

IgnoredAttribute

Specified properties are ignored for mapping.

ServerTimestampAttribute

Specified properties are replaced to a server timestamp. If CanReplace is false, the properties are replaced when they are default or null. The default value for CanReplace is true.

DocumentConverterAttribute

Value is converted by specified converter. You can cpecify your custom converter. Your custom converter must inherit from DocumentConverter.

For example:

public class CustomConverter : DocumentConverter<int>
{
    private readonly int _parameter;

    public CustomConverter(Type targetType, int arg1) : base(targetType, arg1)
    {
        _parameter = arg1;
    }

    public override bool ConvertFrom(DocumentObject value, out object? result)
    {
        if (value.Type == DocumentObjectType.String)
        {
            result = new YourModel(value.String, _parameter);
            return true;
        }
        return false;
    }

    public override bool ConvertTo(object? value, out object? result)
    {
        if (value is YourModel yourModel)
        {
            result = yourModel.ToString(_parameter);
            return true;
        }
        return false;
    }
}

This libray has the following converters.

• EnumStringConverter - cnverts enum to string