MongoDbRepositoryCore 3.4.5

🍃 MongoDbRepository (v3.4.5) A robust, enterprise-grade, and async-first MongoDB Repository pattern implementation for .NET.

Designed for high performance and excellent Developer Experience (DX), Version 3.4.5 moves beyond simple CRUD operations. This library natively provides ACID transactions, optimistic concurrency, transparent RAM caching, automatic audit trails, declarative data modeling, and seamless unit testing—all with zero boilerplate.

✨ What's New in V3.4.5 (The Enterprise Update) Transparent Read Caching: Drop [Cacheable] on any entity for instant, automatic RAM caching with auto-invalidation on writes.

Automatic Audit Logs: Drop [AuditHistory] on a class to automatically track every field-level BSON diff to a centralized System_AuditLogs collection.

Optimistic Concurrency: Prevent "last-write-wins" data loss natively using the [Version] attribute.

Ambient ACID Transactions: Use IMongoTransactionManager to automatically flow transactions across multiple repositories without passing session variables.

Domain Event Dispatching: Entities can hold events that are automatically published via MediatR immediately after a successful database commit.

Mockless Unit Testing: Ships with a blazing-fast InMemoryRepository so you never have to mock IMongoCollection again.

Cloud Resilient: Built-in Polly retry policies handle MongoDB Atlas node elections and transient network blips automatically.

📦 Installation Install via NuGet Package Manager:

Bash dotnet add package MongoDbRepositoryCore --version 3.4.5 🛠️ Quick Start

1. Define your Entity Implement IEntity<TId>. You can completely control database behavior, indexing, caching, and encryption using our powerful attribute engine directly on your C# models!

C# [BsonCollection("users")] [Cacheable(Seconds = 3600)] // V3.4: Automatically caches reads in RAM for 1 hour! [AuditHistory] // V3.4: Automatically tracks all changes in System_AuditLogs public class User : IEntity<Guid>, IAuditableEntity, ISoftDeletable, IHasDomainEvents { public Guid Id { get; set; }

[TextSearch] // Adds this field to the global $text search index
public string Name { get; set; }

[UniqueIndex] // Ensures no duplicate emails ever enter the database
public string Email { get; set; }

[SecureString] // Encrypts the data in MongoDB, decrypts it in C#!
public string SocialSecurityNumber { get; set; }

[Version] // V3.4: Enables Optimistic Concurrency Control
public int Version { get; set; }

public DateTime CreatedAt { get; set; }

[UpdatedAt] // Automatically updated to DateTime.UtcNow on every Upsert/Update!
public DateTime LastModified { get; set; }

public bool IsDeleted { get; set; }
public DateTime? DeletedAt { get; set; }

// V3.4: Domain Events Support
[BsonIgnore]
public IReadOnlyList<IDomainEvent> DomainEvents { get; }
public void AddDomainEvent(IDomainEvent eventItem) { ... }
public void ClearDomainEvents() { ... }

} 2. Register in Dependency Injection Setup is a simple, fluent one-liner. The builder automatically detects your attributes ([Cacheable], [TimeSeries], etc.) and configures the dependency injection container for you:

C# builder.Services.AddMongoDbRepositories(db ⇒ { db.ConnectionString = "mongodb://localhost:27017"; db.DatabaseName = "MyApp"; }) .WithGuidRepresentation(GuidRepresentation.Standard) .AddRepository<User, Guid>() // Automatically wrapped in CachingDecorator due to [Cacheable]! .EnableFieldLevelEncryption("MySecureApp.Encryption"); 3. Inject and Use C# public class UserService { private readonly IRepository<User, Guid> _userRepo;

public UserService(IRepository<User, Guid> userRepo)
{
    _userRepo = userRepo;
}

public async Task CreateUserAsync(User user)
{
    // 1. Saves to DB
    // 2. Invalidates the Cache
    // 3. Publishes any MediatR Domain Events attached to the user
    await _userRepo.AddAsync(user);
}

} 📖 Documentation & Deep Dives To keep this README clean, we have moved the detailed documentation for advanced features into the Developer's Guide.

Please see docs/DevelopersGuide.md for full tutorials on:

Mockless Unit Testing: How to use the InMemoryRepository to test without mocking MongoDB.

Ambient ACID Transactions: How to save across multiple collections atomically.

Domain Events: How to trigger MediatR notifications automatically on save.

Time-Series Collections: How to optimize logs and snapshots with [TimeSeries].

Projections & Math: How to save RAM and network bandwidth with .GetProjectedManyAsync() and .SumAsync().

Global Query Filters: How to implement multi-tenancy seamlessly.

Keyset Pagination: How to query millions of rows without performance degradation.

Distributed Tracing: How to hook the repository into OpenTelemetry.

🗑️ Deleting Data Soft Deletes: Calling await repo.DeleteAsync(id) on an entity implementing ISoftDeletable will set IsDeleted = true. It will automatically be hidden from all future GetManyAsync queries.

Hard Deletes: To permanently wipe a document (e.g., GDPR compliance), bypass the soft delete via the escape hatch: await repo.HardDeleteAsync(id). (Note: If [AuditHistory] is enabled, a pre-fetch log is still safely recorded before physical deletion).