MongoDbRepositoryCore 5.0.0

📖 MongoDbRepository Developer's Guide (v4.5.0)

Welcome to the daily cookbook for the MongoDbRepository framework. This guide covers how to leverage the advanced v4.5 features, including Zero-Boilerplate Source Generators, AI Semantic Search, Microservices Caching, the Outbox Pattern, and Code-First Migrations.

1. Zero-Boilerplate DI (New in V4.5)

Forget manually registering dozens of repositories and services. V4.5 introduces a blazing-fast Roslyn Source Generator that wires up your entire database layer at compile-time.

Step 1: Add the [GenerateRepository] attribute to your entity.

[GenerateRepository]
[Cacheable] // Optional: Stacks the caching decorator automatically!
public class User : Entity 
{
    public string Name { get; set; }
}
Step 2: Call the auto-generated extension method in Program.cs. The generator automatically maps the interfaces, applies your decorators, and registers MediatR for background tasks.

C#
builder.Services.AddAutoGeneratedMongoRepositories();
builder.Services.AddAutoGeneratedMongoServices();
2. Generative AI & Vector Search
MongoDB Atlas supports native AI Vector Searches. This library reduces the complex aggregation pipelines into a single attribute and method call.

Step 1: Add the [VectorEmbedding] attribute to a float[] property on your entity. The repository will automatically provision the Atlas Search Indexes on startup.

C#
public class SupportArticle : Entity
{
    public string Title { get; set; }
    public string Content { get; set; }

    [VectorEmbedding(Dimensions = 1536, Similarity = "cosine")]
    public float[] ContentEmbedding { get; set; } 
}
Step 2: Execute a Semantic Search natively.

C#
// Generate embedding via OpenAI, HuggingFace, etc.
float[] userQuestionVector = await _aiService.GetEmbeddingAsync("How do I reset my password?");

// Search, with optional pre-filtering!
var topArticles = await _articleRepo.SemanticSearchAsync(
    queryVector: userQuestionVector, 
    limit: 5, 
    filter: article => article.IsActive // Pre-filters using standard LINQ
);
3. The Transactional Outbox Pattern (Guaranteed Events)
In a distributed system, saving a database record and firing an event (like sending a welcome email) is dangerous. If the server crashes between the two, the event is lost. V4.5 handles this flawlessly with a Zero-Config Outbox.

When you attach an event using IHasDomainEvents and save the entity, the repository serializes the MediatR event into a System_Outbox MongoDB collection inside the exact same ACID transaction.

Thanks to v4.5 Source Generators, the Background Worker and MediatR are now automatically registered for you! A background worker safely leases the message, fires the MediatR event, and retries on failure.

C#
user.AddDomainEvent(new UserRegisteredEvent(user.Id));
await _userRepo.AddAsync(user); // 100% Guaranteed Delivery
4. Distributed Cluster Caching (Redis)
If you run multiple instances of your API (e.g., in Kubernetes), standard RAM caching leads to stale data. V4.5 introduces the DistributedCachingRepositoryDecorator.

By registering your cache settings, the library uses Microsoft's IDistributedCache. If Pod A updates a user, it deletes the key from Redis, meaning Pods B, C, and D instantly fetch fresh data on their next request!

C#
builder.Services.AddMongoDbRepositories(db => { ... }, cache => 
{
    cache.ApplicationName = "BillingApi"; 
});
5. Code-First Migrations
Need to seed an Admin user or rename a property across 1 million documents? Write a migration script. The framework will automatically run it on application startup and track its execution.

C#
public class Migration_001_SeedAdmin : IMongoMigration
{
    public int Version => 1;

    public async Task UpAsync(IMongoDatabase database)
    {
        var users = database.GetCollection<User>("users");
        await users.InsertOneAsync(new User { Email = "admin@system.com", Role = "SuperAdmin" });
    }
}
6. Mockless Unit Testing
Stop mocking IMongoCollection! We ship a blazing-fast, thread-safe fake that implements IRepository<T, TId> and executes your queries in memory.

C#
[Fact]
public async Task GetActiveUsers_ReturnsCorrectData()
{
    // Arrange: Use the fake repository (0 milliseconds execution!)
    var fakeRepo = new InMemoryRepository<User, Guid>();
    fakeRepo.Seed(new[] { new User { Id = Guid.NewGuid(), IsActive = true, Name = "Alice" } });

    var service = new UserService(fakeRepo);

    // Act
    var activeUsers = await service.GetActiveUsersAsync();

    // Assert
    Assert.Single(activeUsers); 
}