mongodb-integration

# ABP MongoDB Integration Guidance for the MongoDB data-access layer of an ABP solution. Types live in `Volo.Abp.MongoDB`. The integration lives in the `*.MongoDB` project; repository interfaces belong in the `*.Domain` project. ## When to Use - Defining an `AbpMongoDbContext` and exposing collections as `IMongoCollection<T>`. - Naming collections with `[MongoCollection]` and mapping entities in `CreateModel`. - Registering the DbContext and repositories with `AddMongoDbContext`. - Writing a custom repository over `MongoDbRepository<TMongoDbContext, TEntity, TKey>`. - Reaching another collection via `IMongoDbContextProvider<TMongoDbContext>`, or dropping to the native driver with `GetCollectionAsync()` / `GetAggregateAsync()`. ## When Not to Use - **EF Core data access, `OnModelCreating`, or `dotnet ef` migrations** — use the **ef-core-integration** skill instead. - **Transaction / Unit of Work boundaries** — use **manage-units-of-work**. - **Soft-delete / multi-tenant / custom filters** (including `MongoDbRepositoryFilterer`) — use **apply-data-filters**. - **Optimistic concurrency** — use **handle-optimistic-concurrency**. - **Connection-string configuration** — use **configure-connection-strings**; **data seeding** — use **seed-application-data**. ## How it works ### DbContext Derive from `AbpMongoDbContext`. Expose each collection as an `IMongoCollection<T>` property and mark it with `[MongoCollection]` (from `Volo.Abp.MongoDB`) to name the collection. Attach the module's model configuration by overriding `CreateModel`. ```csharp [ConnectionStringName("Default")] public class MyProjectMongoDbContext : AbpMongoDbContext { [MongoCollection("AppBooks")] public IMongoCollection<Book> Books => Collection<Book>(); protected override void CreateModel(IMongoModelBuilder modelBuilder) { base.CreateModel(modelBuilder); modelBuilder.Entity<Book>(b => { b.CollectionName = "AppBooks"; }); } } ``` - `[MongoCollection]` sets the collection name (`CollectionName` on the attribute); without it the DbContext collection property name is used (e.g. the `Books` property maps to a `Books` collection). - `Collection<T>()` (defined on `AbpMongoDbContext`) returns the underlying `IMongoCollection<T>`. - `IMongoModelBuilder.Entity<TEntity>(...)` maps an entity; set `CollectionName`, indexes, or a BSON class map there. - The base `AbpMongoDbContext.CreateModel` is empty; calling `base.CreateModel(modelBuilder)` is a harmless convention, not a requirement that wires up ABP's entities. ### Module ConfigureXxx() convention Reusable modules ship a `builder.Configure<Module>()` extension on `IMongoModelBuilder`. Call them inside `CreateModel`: ```csharp modelBuilder.ConfigurePermissionManagement(); modelBuilder.ConfigureSettingManagement(); ``` ### Registration Register in your `*.MongoDB` module's `ConfigureServices` via `AddMongoDbContext<TMongoDbContext>`: ```csharp public override void ConfigureServices(ServiceConfigurationContext context) { context.Services.AddMongoDbContext<MyProjectMongoDbContext>(options => { options.AddDefaultRepositories(includeAllEntities: true); // Custom repository override options.AddRepository<Book, MongoDbBookRepository>(); }); } ``` The registration builder shares the same API as EF Core: `AddDefaultRepositories`, `AddDefaultRepository<TEntity>()`, `AddRepository<TEntity, TRepository>()`. ### Custom repositories Declare the interface in the **Domain** project (same as EF Core — `IRepository<TEntity, TKey>`): ```csharp public interface IBookRepository : IRepository<Book, Guid> { Task<List<Book>> GetListByAuthorAsync(Guid authorId); } ``` `IRepository` is the right base inside a **final application**. For a **reusable module** published for other apps, extend `IBasicRepository<Book, Guid>` (or `IReadOnlyBasicRepository`) instead, so consumers aren't coupled to a provider's `IQueryable` (see use-abp-repositories). Implement in the **MongoDB** project by deriving from `MongoDbRepository<TMongoDbContext, TEntity, TKey>`: ```csharp public class MongoDbBookRepository : MongoDbRepository<MyProjectMongoDbContext, Book, Guid>, IBookRepository { public MongoDbBookRepository(IMongoDbContextProvider<MyProjectMongoDbContext> dbContextProvider) : base(dbContextProvider) { } public async Task<List<Book>> GetListByAuthorAsync(Guid authorId) { var queryable = await GetQueryableAsync(); return await queryable.Where(b => b.AuthorId == authorId).ToListAsync(); } } ``` #### Querying inside a repository - `GetQueryableAsync()` → `IQueryable<TEntity>` (LINQ over the collection; the driver translates it). - `GetCollectionAsync()` → the raw `IMongoCollection<TEntity>` for native driver operations (aggregation, bulk writes). - `GetAggregateAsync()` → an `IAggregateFluent<TEntity>` for aggregation pipelines. The base repository already applies ABP's global filters (soft-delete, multi-tenancy) to `GetQueryableAsync()`; going through the raw collection bypasses them. #### DbContext provider Inject `IMongoDbContextProvider<TMongoDbContext>` to reach the DbContext directly and get another collection: ```csharp var dbContext = await _dbContextProvider.GetDbContextAsync(); var authors = dbContext.Collection<Author>(); ``` ### Differences vs EF Core - **No migrations.** MongoDB is schemaless — there is no `dotnet ef migrations` step. The startup template's schema migrator (`MongoDb...DbSchemaMigrator`) instead calls `InitializeCollections`, which creates the collections and any configured indexes; the `DbMigrator` console app (if present) also runs `IDataSeeder` to seed data. - **No relational joins.** You cannot compose cross-collection joins the way you would with EF Core navigation properties. Load related aggregates with separate queries, or model them within the aggregate. Use `GetAggregateAsync()` / `$lookup` only when a real aggregation pipeline is needed. - **Attribute for naming is `[MongoCollection]`**, not table mapping. - Everything else — repository interfaces in Domain, `AddDefaultRepositories`, custom repository pattern, `[ConnectionStringName]` — mirrors the EF Core integration, so application/domain code stays provider-agnostic. ## Validation - The `*.MongoDB` project references `Volo.Abp.MongoDB`; the DbContext derives from `AbpMongoDbContext` and carries `[ConnectionStringName]`. - Injecting the default `IRepository<Book, Guid>` (or your `IBookRepository`) resolves after `AddMongoDbContext` registration — confirm the app boots and the repository is available. - Queried results honor ABP's global filters when you go through `GetQueryableAsync()`; a native `GetCollectionAsync()` query returns unfiltered rows. - The Domain/Application projects do not reference `Volo.Abp.MongoDB` — repository interfaces stay provider-agnostic. ## Common Pitfalls - **Going through the raw collection (`GetCollectionAsync()`) unexpectedly bypasses ABP's global filters** (soft-delete, multi-tenancy). Use `GetQueryableAsync()` unless you deliberately need native driver operations. - **Expecting relational joins** — MongoDB has none; load related aggregates with separate queries or model them within the aggregate, and use `$lookup`/`GetAggregateAsync()` only for real aggregation pipelines. - **Expecting `dotnet ef migrations`** — MongoDB has none. The template's schema migrator calls `InitializeCollections` to create collections and configured indexes, and the `DbMigrator` (if present) additionally seeds data. - **Omitting `[MongoCollection]`** — the collection is then named after the property, which may not match your intended collection name.