MongoDB.Entities Documentation

MongoDB.Entities is a lightweight .NET Standard 2.1 library designed to simplify MongoDB access by abstracting the official MongoDB driver. It provides an elegant, human-friendly API surface with minimal overhead, focusing on scalable application development through an async-only API.

Key capabilities include:

• Relationship Management: Built-in support for One-To-One, One-To-Many, and Many-To-Many relationships.
• Querying: Support for LINQ, lambda expressions, filters, and aggregation pipelines, including sorting, paging, and projection.
• Data Management: Simple data migration framework (similar to EntityFramework), programmatic index management, and easy bulk operations.
• Advanced Search: Full-text search (with fuzzy matching), GeoSpatial search, and change-stream support.
• Developer Productivity: Avoids manual handling of ObjectIds, BsonDocuments, and magic strings; provides easy audit fields, global filters, and multi-document transaction support.
• File Handling: Ability to stream files in chunks to and from MongoDB (as a GridFS alternative).

The Template<T> class allows you to write raw MongoDB queries (as strings) and safely inject C# values or property paths using a tag-based replacement system. This avoids manual string concatenation and keeps your queries coupled to your C# entity schema.

How it works

1. Mark Tags: In your raw query string, wrap the parts you want to replace with < and > (e.g., <PropertyName> or <tag_name>).
2. Map Paths: Use .Path(expression) to automatically resolve a C# member expression into a MongoDB 'dotted' path string and replace the corresponding <Tag> in the query.
3. Inject Values: Use .Tag("tagName", value) to replace a specific tag with a literal value. Note that when using .Tag(), you do not include the < or > characters in the tag name.

Error Scenarios

The system throws an exception if:

• The input text contains no < and > tags.
• You have tags in the query that were not assigned a replacement.
• You provided a replacement via .Tag() or .Path() that does not exist in the query.

var query = new Template<Book>(
                """
                {
                  <Title> : '<book_name>',
                  <Price> : <book_price>
                }
                """
            )
            .Path(b => b.Title)
            .Path(b => b.Price)
            .Tag("book_name", "The Power Of Now")
            .Tag("book_price", "10.95");

var result = await db.Find<Book>()
                     .Match(query)
                     .ExecuteAsync();

The library uses the MongoDB driver's IIdGenerator to create IDs. By default, string IDs use ObjectId-formatted strings, while ObjectId and Guid use their respective types.

Registering ID Generators

Registration should be done at application startup, before calling DB.InitAsync().

1. Entity-specific generator: Use DB.RegisterIdGenerator<T>(generator) to target a specific entity type. This takes precedence over other registrations.
2. Type-specific generator: Use BsonSerializer.RegisterIdGenerator(typeof(T), generator) to affect all entities using that specific CLR type.

// Entity-specific
DB.RegisterIdGenerator<Book>(new MyCustomIdGenerator());

// Type-specific
BsonSerializer.RegisterIdGenerator(typeof(long), new MySequentialLongIdGenerator());

Important Notes

• ID Types: You can use any type serializable by the MongoDB driver (e.g., Guid, long, ObjectId).
• Relationships: Many<> relationships support any ID type. For One<TEntity> one-to-one references, if you are not using a string ID, you must use the typed One<TEntity, TIdentity> version.
• Guid Warning: If using Guid, ensure you register a Guid serializer (e.g., BsonSerializer.RegisterSerializer(new GuidSerializer(GuidRepresentation.Standard));) before initializing the library. Be aware that Guid carries a risk of duplicates during partial entity saving (upserts), which could lead to data loss.
• Recommendation: It is highly recommended to use ObjectId to minimize the risk of duplicate IDs.

Referenced relationships in MongoDB.Entities are defined using One<T> for one-to-one relationships and Many<TChild, TParent> for one-to-many and many-to-many relationships.

To use these, you must initialize the Many<TChild, TParent> properties in the entity's constructor using InitOneToMany or InitManyToMany:

• InitOneToMany(() => Property): Used for one-to-many relationships. Takes a single lambda pointing to the property.
• InitManyToMany(() => Property, otherSide => otherSide.Property): Used for many-to-many relationships. Takes a lambda for the local property and a second lambda pointing to the corresponding property on the related entity.

For many-to-many relationships, use the [OwnerSide] attribute on the property in the parent entity and the [InverseSide] attribute on the property in the related entity to define the relationship direction.

public class Book : Entity
{
    public One<Author> MainAuthor { get; set; }
    public Many<Author, Book> CoAuthors { get; set; }

    [OwnerSide]
    public Many<Genre, Book> Genres { get; set; }

    public Book()
    {
        this.InitOneToMany(() => CoAuthors);
        this.InitManyToMany(() => Genres, genre => genre.Books);
    }
}

public class Genre : Entity
{
    [InverseSide]
    public Many<Book, Genre> Books { get; set; }

    public Genre()
    {
        this.InitManyToMany(() => Books, book => book.Genres);
    }
}