MongoFramework Documentation

MongoFramework is an "Entity Framework"-like interface for MongoDB built on top of the official MongoDB C# driver. It provides several high-level abstractions to simplify MongoDB development in .NET:

• Entity Mapping: Map collections, IDs, and properties using attributes or a fluent API.
• Indexing: Define single-field, compound, and multikey indexes via attributes or fluent API (including text and geospatial).
• Change Tracking: Includes entity change tracking, changeset support (batching updates), and diff-updates (writing only changed fields).
• Entity Buckets: Implements the bucket pattern to cluster small documents into larger ones for improved performance.
• Runtime Type Discovery: Automatically handles serialization/deserialization of polymorphic types without needing to pre-register all known subtypes.
• Special Queries: Built-in support for text search and geospatial (intersecting and near) queries.

Entity Buckets allow you to store many small documents inside a single larger document to improve index performance and reduce storage overhead.

To use them, define a MongoDbBucketSet<TGrouping, TItem> in your context and decorate it with the [BucketSetOptions] attribute.

• bucketSize: The maximum number of items allowed in a single bucket.
• entityTimeProperty: The name of the property in the sub-entity (TItem) that stores the timestamp.

Note: Managing buckets is currently limited to add-only operations via AddRange.

public class MyBucketGrouping
{
  public string SensorId { get; set; }
  public DateTime Date { get; set; }
}

public class MyBucketItem
{
  public DateTime EntryTime { get; set; }
  public int Value { get; set; }
}

public class MyContext : MongoDbContext
{
  public MyContext(IMongoDbConnection connection) : base(connection) { }
  [BucketSetOptions(bucketSize: 1000, entityTimeProperty = nameof(MyBucketItem.EntryTime))]
  public MongoDbBucketSet<MyBucketGrouping, MyBucketItem> MyBuckets { get; set; }
}

// Usage
using (var context = new MyContext(MongoDbConnection.FromConnectionString("mongodb://localhost:27017/MyDatabase")))
{
  context.MyBuckets.AddRange(new MyBucketGrouping
  {
    SensorId = "ABC123",
    Date = DateTime.Parse("2020-04-04")
  }, new []
  {
    new MyBucketItem { EntryTime = DateTime.Parse("2020-04-04T01:00"), Value = 123 },
    new MyBucketItem { EntryTime = DateTime.Parse("2020-04-04T02:00"), Value = 456 }
  });

  await context.SaveChangesAsync();
}

Indexes are applied to properties and are synchronized with the database when the context is saved.

Attribute Mapping

Use the [Index] attribute on properties. You can specify the index name and sort order using IndexSortOrder.

public class IndexExample
{
  public string Id { get; set; }

  [Index("Email", IndexSortOrder.Ascending)]
  public string EmailAddress { get; set; }

  public string Name { get; set; }
}

Fluent Mapping

Use HasIndex within the OnConfigureMapping method. For compound indexes, define multiple properties with the same index name. You can control the order of fields in a compound index using IndexPriority (for attributes) or by the order of declaration/configuration.

mappingBuilder.Entity<IndexExample>()
  .HasIndex(e => e.EmailAddress, b => b.HasName("Email").IsDescending(false));

Compound Indexes

To create a compound index, ensure multiple properties share the same index name. For complex structures or arrays, you can use an anonymous object in the fluent API:

mappingBuilder.Entity<TestModel>()
  .HasIndex(m => new
  {
    m.SomethingIndexable,
    m.OneOfThem.Description,
    m.ManyOfThem.First().AnotherThingIndexable
  }, b => {
    b.HasName("MyIndex")
      .IsDescending(true, false, false)
  });

Special Index Types

MongoFramework supports Text and 2dSphere indexes. For attribute mapping, set the IndexType property on the [Index] attribute.

You can configure how entities map to MongoDB collections and how properties map to BSON elements using the MappingBuilder inside your MongoDbContext.OnConfigureMapping override.

Use .Entity<T>() to start configuration, .ToCollection("Name") to specify the collection, and .HasProperty(expr, config) to remap property names.

using MongoFramework;

public class MyEntity
{
  public string Id { get; set; }
  public string Name { get; set; }
  public string Description { get; set; }
}

public class MyContext : MongoDbContext
{
  public MyContext(IMongoDbConnection connection) : base(connection) { }
  public MongoDbSet<MyEntity> MyEntities { get; set; }

  protected override void OnConfigureMapping(MappingBuilder mappingBuilder)
  {
    mappingBuilder.Entity<MyEntity>()
      .HasProperty(m => m.Name, b => b.HasElementName("MappedName"))
      .ToCollection("MyCustomEntities");
  }
}

Alternatively, you can use attributes directly on your entity classes to define mapping behavior. Many core attributes are part of the System.ComponentModel.Annotations package.

using MongoFramework;
using System.ComponentModel.DataAnnotations;

[Table("MyCustomEntities")]
public class MyEntity
{
  public string Id { get; set; }
  [Column("MappedName")]
  public string Name { get; set; }
  public string Description { get; set; }
}

public class MyContext : MongoDbContext
{
  public MyContext(IMongoDbConnection connection) : base(connection) { }
  public MongoDbSet<MyEntity> MyEntities { get; set; }
}

To use MongoFramework, you need to define your entities, create a context class inheriting from MongoDbContext, and manage operations through a MongoDbSet<T>.

1. Define an Entity: Create a class with properties (e.g., Id, Name).
2. Create a Context: Inherit from MongoDbContext and expose your entities as MongoDbSet<T> properties.
3. Initialize Connection: Use MongoDbConnection.FromConnectionString to establish a connection.
4. Perform Operations: Use the context to query entities via LINQ and persist changes using SaveChangesAsync().

using MongoFramework;
using System.ComponentModel.DataAnnotations;

public class MyEntity
{
  public string Id { get; set; }
  public string Name { get; set; }
  public string Description { get; set; }
}

public class MyContext : MongoDbContext
{
  public MyContext(IMongoDbConnection connection) : base(connection) { }
  public MongoDbSet<MyEntity> MyEntities { get; set; }
}

// Usage
var connection = MongoDbConnection.FromConnectionString("YOUR_CONNECTION_STRING");
using (var myContext = new MyContext(connection))
{
  var myEntity = myContext.MyEntities.Where(myEntity => myEntity.Name == "MongoFramework").FirstOrDefault();
  myEntity.Description = "An 'Entity Framework'-like interface for MongoDB";
  await myContext.SaveChangesAsync();
}