# MongoDB Entity Framework Core Provider

[![MongoDB.EntityFrameworkCore](https://img.shields.io/nuget/v/MongoDB.EntityFrameworkCore.svg)](https://www.nuget.org/packages/MongoDB.EntityFrameworkCore/)

The MongoDB EF Core Provider enables MongoDB interaction with Entity Framework Core 8 or 9 on .NET 8.0 or later, and Entity Framework Core 10 on .NET 10.0 or later.

It supports MongoDB database server 5.0 or later, preferably in a transaction-enabled configuration.

## Getting Started

### Basic Setup
First, create a DbContext with the desired entities and configuration:

```csharp
internal class PlanetDbContext : DbContext
{
    public DbSet<Planet> Planets { get; init; }

    public static PlanetDbContext Create(IMongoDatabase database) =>
        new(new DbContextOptionsBuilder<PlanetDbContext>()
            .UseMongoDB(database.Client, database.DatabaseNamespace.DatabaseName)
            .Options);

    public PlanetDbContext(DbContextOptions options)
        : base(options)
    {
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        modelBuilder.Entity<Planet>().ToCollection("planets");
    }
}
```

### Connection Options

#### Option 1: Direct Database Connection
```csharp
var mongoConnectionString = Environment.GetEnvironmentVariable("MONGODB_URI");
var mongoClient = new MongoClient(mongoConnectionString);
var db = PlanetDbContext.Create(mongoClient.GetDatabase("planets"));
db.Database.EnsureCreated();
var planet = db.Planets.FirstOrDefault(x => x.Name == "Earth");
```

#### Option 2: Using Dependency Injection
```csharp
var mongoConnectionString = builder.Configuration.GetConnectionString("MongoDbUri")!;
builder.Services.AddDbContext<PlanetDbContext>(options =>
{
    options.UseMongoDB(mongoConnectionString, DatabaseName);
});
```

If you need some more configuration, you can create the `MongoClient` and inject it into the DbContext:

```csharp
var mongoConnectionString = builder.Configuration.GetConnectionString("MongoDbUri")!;
var mongoUrl = new MongoUrl(mongoConnectionString);
var mongoClient = new MongoClient(mongoUrl);
builder.Services.AddSingleton<IMongoClient>(mongoClient);
builder.Services.AddDbContext<PlanetDbContext>((provider, options) =>
{
    var client = provider.GetRequiredService<IMongoClient>();
    options.UseMongoDB(client, DatabaseName);
});
```

Later on, simply inject `PlanetDbContext` where it's needed and continue as you would normally.

## Supported Features

Entity Framework Core and MongoDB have a wide variety of features. This provider supports a subset of the functionality available in both, specifically:

- Querying with `Where`, `Find`, `First`, `Single`, `OrderBy`, `ThenBy`, `Skip`, `Take` etc.
- Vector search with the `VectorSearch` extension method on DbSet and fluent vector index configuration
- Top-level aggregate `Any`, `Count`, `LongCount`, `Sum`, `Min`, `Max`, `Average`, `All`
- Mapping properties to BSON elements using `[Column]` or `[BsonElement]` attributes or `HasElementName("name")` method
- Mapping entities to collections via `[Table("name")]`,  `ToCollection("name")` or by convention from the DbSet property name
- Single or composite keys of standard types including string, `Guid` and `ObjectId` etc.
- Properties with typical CLR types (`int`, `string`, `Guid`, `decimal`, `DateOnly` etc.) & MongoDB types (`ObjectId`, `Decimal128`)
- Properties that are arrays, lists, dictionaries (string keys) of simple CLR types including binary `byte[]`
- Owned entities (aka value types, sub-documents, embedded documents) both directly and in collection properties
- `BsonIgnore`, `BsonId`, `BsonDateTimeOptions`, `BsonElement`, `BsonRepresentation` and `BsonRequired` support
- Storage type configuration through EF ValueConverters or BSON representation attributes and fluent APIs
- Query and update logging of MQL (sensitive logging must be enabled)
- `EnsureCreated` & `EnsureDeleted` to ensure collections and the database created at app start-up
- Optimistic concurrency support through `IsConcurrencyToken`/`ConcurrencyCheckAttribute` & `IsRowVersion`/`TimestampAttribute`
- AutoTransactional `SaveChanges` & `SaveChangesAsync` - all changes committed or rolled-back together
- `CamelCaseElementNameConvention` for helping map Pascal-cased C# properties to camel-cased BSON elements
- Type discriminators including `OfType<T>` and `Where(e => e is T)`
- Support for EF shadow properties and EF.Proxy for navigation traversal
- MongoDB full text search (Previously known as Atlas Search)
- MongoDB vector search (Previously known as Atlas Vector Search)
- [Client Side Field Level Encryption](https://www.mongodb.com/docs/manual/core/csfle/quick-start/) and [Queryable Encryption](https://www.mongodb.com/docs/manual/core/queryable-encryption/) compatibility
- Bulk `ExecuteUpdate` and `ExecuteDelete` (EF 9+) on a single collection; supports constant and self-referencing setters; bypasses the change tracker (concurrency tokens are not checked)
  - `Where`-scoped sources execute as a single atomic `deleteMany` / `updateMany` server command
  - Sources that also use `OrderBy`/`ThenBy`/`Skip`/`Take`/`Distinct` are supported via a transactional two-phase execution (phase 1 collects the target `_id`s; phase 2 acts on them via `{ _id: { $in: [...] } }`); requires a transaction-capable deployment (replica set or sharded cluster); under `AutoTransactionBehavior.Never` the caller must open an explicit transaction
  - If a transaction is already open on the context, the operation enlists in it rather than starting its own — MongoDB does not support nested transactions, so a two-phase bulk op cannot open an inner transaction the way some relational providers do
  - Not supported: joins, `GroupBy`, `SelectMany`, set operations, cross-document navigation predicates, or multiple-collection updates

## Limitations

A number of Entity Framework Core features are not currently supported but planned for future release. If you require use of these facilities
in the mean-time consider using the existing [MongoDB C# Driver's](https://github.com/mongodb/mongo-csharp-driver) LINQ provider which may support them.

### Planned for future releases

- Select projections with client-side operations
- GroupBy operations
- Includes/joins
- Geospatial

### Not supported, out-of-scope features

- Keyless entity types
- Migrations
- Database-first & model-first
- Document (table) splitting
- Temporal tables
- Timeseries
- GridFS

## Breaking changes

This project's version-numbers are aligned with Entity Framework Core and as-such we can not use the semver convention of constraining breaking changes solely to major version numbers. Please keep an eye on our [Breaking Changes](/BREAKING-CHANGES.md) document before upgrading to a new version of this provider.

## Documentation

- [MongoDB](https://www.mongodb.com/docs)
- [EF Core Provider Guide](https://www.mongodb.com/docs/entity-framework/current/)
- [EF Core Provider API Docs](https://mongodb.github.io/mongo-efcore-provider/10.0.0/api/index.html)

## Questions/Bug Reports

- [Forums](https://www.mongodb.com/community/forums/)
- [Jira](https://jira.mongodb.org/projects/EF/)

If you've identified a security vulnerability in a driver or any other MongoDB project, please report it according to the [instructions here](https://www.mongodb.com/docs/manual/tutorial/create-a-vulnerability-report).

## Contributing

Please see our [guidelines](CONTRIBUTING.md) for contributing to the driver.

Thank you to [everyone](https://github.com/mongodb/mongo-efcore-provider/graphs/contributors) who has contributed to this project.