MongoDB 与 EF Core 深度整合实战：打造结构清晰的 Web API 应用

题纲

• • [MongoDB 字符串](#MongoDB 字符串)
  • • [连接 URI](#连接 URI)
    • [C# 连接字符串实例](# 连接字符串实例)
  • [实现一个电影信息查询 demo](#实现一个电影信息查询 demo)
  • • 创建项目
    • 创建实体
    • [实现 DbContext 上下文](#实现 DbContext 上下文)
    • 仓储实现
    • 服务实现
    • 控制器实现
    • 服务注册
    • 快照注入数据库连接配置
    • • [1. 注册配置类](#1. 注册配置类)
      • [2. 注入 `IOptionsSnapshot<MongoDbSettings>`](#2. 注入 IOptionsSnapshot<MongoDbSettings>)
      • [3. 配置文件 appsettings.json 示例](#3. 配置文件 appsettings.json 示例)
  • 总结

• 过去，C# 开发者可以使用 MongoDB.Driver（MongoDB 的 C# 驱动程序），但无法获得针对 EF Core 的第一方支持。

• 现在，随着 MongoDB.EntityFrameworkCore（适用于 EF Core 的官方 MongoDB 提供程序） 的正式发布，开发者在使用 MongoDB 构建生产级工作负载时可以放心地使用 C# 和 EF Core。

链接 .NET/C# MongoDB.Driver MongoDB.EntityFrameworkCore MongoDB

• .NET Nuget 包发布情况：

2024-01-01 2024-04-01 2024-07-01 2024-10-01 2025-01-01 2025-04-01 7.0.0-preview.1 8.0.0---8.3.0 9.0.0-preview.1---9.0.0 .net nuget package Adding GANTT diagram functionality to MongoDB.EntityFrameworkCore

github 项目地址，https://github.com/mongodb/mongo-efcore-provider

MongoDB 字符串

接下来介绍如何使用 MongoDB.Driver 连接到 MongoDB 实例或副本集部署。

连接 URI

连接 URI（也称为连接字符串）可告知驱动程序如何连接到 MongoDB 部署，以及连接后如何进行操作。

标准连接字符串包括以下部分：

字段	说明
mongodb://	必需。将其标识为标准连接格式中字符串的前缀。
username:password@	可选。身份验证凭证。如果包含这些内容，客户端将根据 authSource 中指定的数据库对用户进行身份验证。
host[:port]	必需。运行 MongoDB 的主机和可选端口号。如果未包含端口号，则驱动程序将使用默认端口 27017。
/defaultauthdb	可选。如果连接字符串包含 username:password@ 身份验证档案但未指定 authSource 选项，则要使用的身份验证数据库。如果您不包含这一内容，客户端将根据 admin 数据库对用户进行身份验证。
?<options>	可选。将连接特定选项指定为 = 对的查询字符串。有关这些选项的完整说明，请参阅连接选项。

连接选项 参考，https://www.mongodb.com/zh-cn/docs/drivers/csharp/current/fundamentals/connection/connection-options/#std-label-csharp-connection-options

C# 连接字符串实例

1. 连接字符串语法

mongodb://<username>:<password>@<host1>:<port1>,<host2>:<port2>,<host3>:<port3>/?replicaSet=<replicaSetName>

2. 参数说明

• <username>：MongoDB 的认证用户名（如果没有认证可省略）
• <password>：MongoDB 的用户密码（如果没有认证可省略）
• <host1>, <host2>, <host3>：MongoDB 副本集的各个节点 IP 或主机名;
• <port>：MongoDB 实例的端口号，默认为 27017
• <replicaSetName>：MongoDB 副本集的名称

3. 示例代码

var connectionString = "mongodb://admin:password@host1:27017,host2:27017,host3:27017/?replicaSet=myReplicaSet";

var client = new MongoClient(connectionString);
var database = client.GetDatabase("test");

4. 其他常用选项

你还可以添加额外参数到连接字符串中，例如：

• ssl=true：启用 SSL 加密连接
• authSource=admin：指定认证数据库
• readPreference=secondaryPreferred：优先读取从节点

示例：

mongodb://admin:password@host1:27017,host2:27017,host3:27017/test?replicaSet=myReplicaSet&ssl=true&authSource=admin

实现一个电影信息查询 demo

• 添加 nuget 包

dotnet add package MongoDB.EntityFrameworkCore --version 9.0.0

• 当前包版本为 9.0.0

MongoDB EF Core 提供程序需要启用实体框架核心8或9。.NET 8或更高版本以及 MongoDB数据库服务器5.0或更高级别，最好是在 支持事务 的配置中。

创建项目

使用 .NET CLI 创建一个名为 MongoDbExample 的 Web API 项目，可以使用以下命令：

dotnet new webapi -n MongoDbExample
# 进入项目
cd MongoDbExample
dotnet run

创建实体

创建两个实体类，分别模拟电影信息和电影商品，定义如下：

• Movie 电影信息

using MongoDB.Bson.Serialization.Attributes;
using MongoDB.Bson;

namespace MongoDbExample.Database.Collections;

public sealed class Movie
{
    [BsonId]
    [BsonElement("_id")]
    public ObjectId Id { get; set; }

    [BsonElement("title")]
    public string Title { get; set; } = null!;

    [BsonElement("rated")]
    public string Rated { get; set; } = null!;

    [BsonElement("plot")]
    public string Plot { get; set; } = null!;
}

• Product 电影商品

using MongoDB.Bson.Serialization.Attributes;
using MongoDB.Bson;

namespace MongoDbExample.Database.Collections;

public sealed class Product
{
    [BsonId]
    [BsonElement("_id")]
    public ObjectId Id { get; set; } 

    [BsonElement("name")]
    public string? Name { get; set; }

    [BsonElement("price")]
    public decimal Price { get; set; }
}

实现 DbContext 上下文

• CinemaAppDbContext

using Microsoft.EntityFrameworkCore;
using MongoDB.Driver;
using MongoDB.EntityFrameworkCore.Extensions;
using MongoDbExample.Database.Collections;

namespace MongoDbExample;

public sealed class CinemaAppDbContext(ILogger<CinemaAppDbContext> logger,
    DbContextOptions<CinemaAppDbContext> options) : DbContext(options)
{
    public DbSet<Product> Products { get; init; }

    public DbSet<Movie> Movies { get; init; }

    public static CinemaAppDbContext Create(
        ILogger<CinemaAppDbContext> logger,
        IMongoDatabase database)
    {
        var options = new DbContextOptionsBuilder<CinemaAppDbContext>()
            .UseMongoDB(database.Client, database.DatabaseNamespace.DatabaseName)
            .Options;

        return new CinemaAppDbContext(logger, options);
    }

    public static IMongoDatabase GetDatabase(MongoClientSettings clientSettings, string name, MongoDatabaseSettings? dbSettings = null)
    {
        var client = new MongoClient(clientSettings);
        return dbSettings is null ? client.GetDatabase(name) : client.GetDatabase(name, dbSettings);
    }

    public static IMongoDatabase GetDatabase(string connectionString, string name, MongoDatabaseSettings? dbSettings = null)
    {
        var client = new MongoClient(connectionString);
        return dbSettings is null ? client.GetDatabase(name) : client.GetDatabase(name, dbSettings);
    }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        logger.LogInformation("Configuring entity mappings..."); 
        // 实体映射到集合
        modelBuilder.Entity<Product>().ToCollection("products");
        modelBuilder.Entity<Movie>().ToCollection("movies");
    }
}

仓储实现

创建仓储模式，实现上面实体的 crud 操作，实现如下：

• ICinemaAppRepository，定义仓储规范

using MongoDB.Bson;
using MongoDbExample.Database.Collections;

namespace MongoDbExample.Database.Repositorys;

public interface ICinemaAppRepository
{
    #region Movie
    IAsyncEnumerable<Movie> GetMoviesAsync();
    Task<Movie?> GetMovieByIdAsync(ObjectId id);
    Task<(bool isOk, ObjectId id)> AddMovieAsync(Movie movie);
    Task<(bool isOk, ObjectId id)> UpdateMovieAsync(Movie movie);
    Task<bool> DeleteMovieAsync(ObjectId id);
    #endregion

    #region Product
    IAsyncEnumerable<Product> GetProductsAsync();
    Task<Product?> GetProductByIdAsync(ObjectId id);
    Task<(bool isOk, ObjectId id)> AddProductAsync(Product product);
    Task<(bool isOk, ObjectId id)> UpdateProductAsync(Product product);
    Task<bool> DeleteProductAsync(ObjectId id);
    #endregion
}

• CinemaAppRepository 仓储实现

此处使用 partial class (部分类)模拟工程化结构，分别拆分为两个独立的文件 CinemaAppRepository.Movie.cs 和 CinemaAppRepository.Product.cs。

using MongoDbExample.Database.Repositorys;

namespace MongoDbExample.Repositorys;

// 实现接口 ICinemaAppRepository
public partial class CinemaAppRepository(ILogger<CinemaAppRepository> logger, 
    CinemaAppDbContext dbContext) : ICinemaAppRepository
{
    // CinemaAppRepository.Movie.cs
    // CinemaAppRepository.Product.cs
}

• CinemaAppRepository.Movie.cs

using Microsoft.EntityFrameworkCore;
using MongoDB.Bson;
using MongoDbExample.Database.Collections;

namespace MongoDbExample.Repositorys;

public partial class CinemaAppRepository
{
    #region IMovieRepository
    public async IAsyncEnumerable<Movie> GetMoviesAsync()
    {
        var movies = await dbContext.Movies.ToListAsync();
        foreach (var movie in movies)
        {
            yield return movie;
        }
    }

    public Task<Movie?> GetMovieByIdAsync(ObjectId id) 
       => dbContext.Movies.FindAsync(id).AsTask();

    public async Task<(bool isOk, ObjectId id)> AddMovieAsync(Movie movie)
    {
        if (movie.Id == ObjectId.Empty)
        {
            movie.Id = ObjectId.GenerateNewId(); // 确保生成新的 ObjectId
        }
        
        await dbContext.Movies.AddAsync(movie);
        int rcount = await dbContext.SaveChangesAsync();
        return (rcount > 0, movie.Id);
    }

    public async Task<(bool isOk, ObjectId id)> UpdateMovieAsync(Movie movie)
    {
        dbContext.Movies.Update(movie);
        int rcount = await dbContext.SaveChangesAsync();
        return (rcount > 0, movie.Id);
    }

    public async Task<bool> DeleteMovieAsync(ObjectId id)
    {
        int rcount = 0;
        var movie = await dbContext.Movies.FindAsync(id);
        if (movie != null)
        {
            dbContext.Movies.Remove(movie);
            rcount = await dbContext.SaveChangesAsync();
        }

        return rcount > 0;
    }
    #endregion
}

• CinemaAppRepository.Product.cs

using Microsoft.EntityFrameworkCore;
using MongoDB.Bson;
using MongoDbExample.Database.Collections;

namespace MongoDbExample.Repositorys;

public partial class CinemaAppRepository
{
    #region Product
    public async IAsyncEnumerable<Product> GetProductsAsync()
    {
        var products = await dbContext.Products.ToListAsync();
        foreach (var product in products)
        {
            yield return product;
        }
    }

    public async Task<Product?> GetProductByIdAsync(ObjectId id)
    {
        return await dbContext.Products.FindAsync(id);
    }

    public async Task<(bool isOk, ObjectId id)> AddProductAsync(Product product)
    {
        if (product.Id == ObjectId.Empty)
        {
            product.Id = ObjectId.GenerateNewId(); // 确保生成新的 ObjectId
        }

        await dbContext.Products.AddAsync(product);
        int rcount = await dbContext.SaveChangesAsync();
        return (rcount > 0, product.Id);
    }

    public async Task<(bool isOk, ObjectId id)> UpdateProductAsync(Product product)
    {
        dbContext.Products.Update(product);
        int rcount = await dbContext.SaveChangesAsync();
        return (rcount > 0, product.Id);
    }

    public async Task<bool> DeleteProductAsync(ObjectId id)
    {
        int rcount = 0;
        var product = await dbContext.Products.FindAsync(id);
        if (product != null)
        {
            dbContext.Products.Remove(product);
            rcount = await dbContext.SaveChangesAsync();
        }

        return rcount > 0;
    }
    #endregion
}

服务实现

定义服务接口，分别实现如下：

• IMovieService

using MongoDB.Bson;
using MongoDbExample.Database.Collections;

namespace MongoDbExample.Services;

public interface IMovieService
{
    IAsyncEnumerable<Movie> GetMoviesAsync();
    Task<(bool success, string msg, Movie? data)> GetMovieByIdAsync(ObjectId id);
    Task<(bool success, string msg, ObjectId id)> CreateMovieAsync(Movie movie);
    Task<(bool success, string msg, ObjectId id)> UpdateMovieAsync(Movie movie);
    Task<(bool success, string msg)> DeleteMovieAsync(ObjectId id);
}

• IProductService

using MongoDB.Bson;
using MongoDbExample.Database.Collections;

namespace MongoDbExample.Services;

public interface IProductService
{
    IAsyncEnumerable<Product> GetProductsAsync();
    Task<(bool success, string msg, Product? Data)> GetProductByIdAsync(ObjectId id);
    Task<(bool success, string msg, ObjectId Id)> CreateProductAsync(Product product);
    Task<(bool success, string msg, ObjectId Id)> UpdateProductAsync(Product product);
    Task<(bool success, string msg)> DeleteProductAsync(ObjectId id);
}

实现接口规范，代码如下：

• MovieService

using MongoDB.Bson;
using MongoDbExample.Database.Collections;
using MongoDbExample.Database.Repositorys;

namespace MongoDbExample.Services;

public class MovieService(ICinemaAppRepository _repository) : IMovieService
{
    #region Movie

    public IAsyncEnumerable<Movie> GetMoviesAsync() => _repository.GetMoviesAsync();

    public async Task<(bool success, string msg, Movie? data)> GetMovieByIdAsync(ObjectId id)
    {
        var movie = await _repository.GetMovieByIdAsync(id);
        if (movie == null) return (false, "Movie not found", null);

        return (true, "Success", movie);
    }

    public async Task<(bool success, string msg, ObjectId id)> CreateMovieAsync(Movie movie)
    {
        if (string.IsNullOrWhiteSpace(movie.Title))
            return (false, "Movie title is required.", ObjectId.Empty);

        var (isOk, id) = await _repository.AddMovieAsync(movie);
        if (!isOk) return (false, "Failed to add movie.", ObjectId.Empty);

        return (true, "Movie added successfully.", id);
    }

    public async Task<(bool success, string msg, ObjectId id)> UpdateMovieAsync(Movie movie)
    {
        var existing = await _repository.GetMovieByIdAsync(movie.Id);
        if (existing == null) return (false, "Movie not found.", ObjectId.Empty);

        var (isOk, id) = await _repository.UpdateMovieAsync(movie);
        if (!isOk) return (false, "Failed to update movie.", ObjectId.Empty);

        return (true, "Movie updated successfully.", id);
    }

    public async Task<(bool success, string msg)> DeleteMovieAsync(ObjectId id)
    {
        var exists = await _repository.GetMovieByIdAsync(id);
        if (exists == null) return (false, "Movie not found.");

        var success = await _repository.DeleteMovieAsync(id);
        if (!success) return (false, "Failed to delete movie.");

        return (true, "Movie deleted successfully.");
    }

    #endregion
}

• ProductService

using MongoDB.Bson;
using MongoDbExample.Database.Collections;
using MongoDbExample.Database.Repositorys;

namespace MongoDbExample.Services;

public class ProductService(ICinemaAppRepository repository) : IProductService
{
    #region Product

    public IAsyncEnumerable<Product> GetProductsAsync() => repository.GetProductsAsync();

    public async Task<(bool success, string msg, Product? Data)> GetProductByIdAsync(ObjectId id)
    {
        var product = await repository.GetProductByIdAsync(id);
        if (product == null) return (false, "Product not found", null);

        return (true, "Success", product);
    }

    public async Task<(bool success, string msg, ObjectId Id)> CreateProductAsync(Product product)
    {
        if (string.IsNullOrWhiteSpace(product.Name))
            return (false, "Product name is required.", ObjectId.Empty);

        var (isOk, id) = await repository.AddProductAsync(product);
        if (!isOk) return (false, "Failed to add product.", ObjectId.Empty);

        return (true, "Product added successfully.", id);
    }

    public async Task<(bool success, string msg, ObjectId Id)> UpdateProductAsync(Product product)
    {
        var existing = await repository.GetProductByIdAsync(product.Id);
        if (existing == null) return (false, "Product not found.", ObjectId.Empty);

        var (isOk, id) = await repository.UpdateProductAsync(product);
        if (!isOk) return (false, "Failed to update product.", ObjectId.Empty);

        return (true, "Product updated successfully.", id);
    }

    public async Task<(bool success, string msg)> DeleteProductAsync(ObjectId id)
    {
        var exists = await repository.GetProductByIdAsync(id);
        if (exists == null) return (false, "Product not found.");

        var success = await repository.DeleteProductAsync(id);
        if (!success) return (false, "Failed to delete product.");

        return (true, "Product deleted successfully.");
    }

    #endregion
}

控制器实现

此处只给出 Products 接口实现（Movies类似）。

using Microsoft.AspNetCore.Mvc;
using MongoDB.Bson;
using MongoDbExample.Database.Collections;
using MongoDbExample.Services;

namespace MongoDbExample.Controllers;

[Route("api/[controller]")]
[ApiController]
public class ProductsController(IProductService productService) : ControllerBase
{
    [HttpGet]
    public IAsyncEnumerable<Product> GetProducts() => productService.GetProductsAsync();

    [HttpGet("{id}")]
    public async Task<IActionResult> GetProduct(ObjectId id)
    {
        var (success, msg, data) = await productService.GetProductByIdAsync(id);
        return success ? Ok(data) : NotFound(new { message = msg });
    }

    [HttpPost]
    public async Task<IActionResult> CreateProduct(Product product)
    {
        var (success, msg, id) = await productService.CreateProductAsync(product);
        return success
            ? CreatedAtAction(nameof(GetProduct), new { id }, new { message = msg, id })
            : BadRequest(new { message = msg });
    }

    [HttpPut]
    public async Task<IActionResult> UpdateProduct(Product product)
    {
        var (success, msg, id) = await productService.UpdateProductAsync(product);
        return success
            ? Ok(new { message = msg, id })
            : BadRequest(new { message = msg });
    }

    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteProduct(ObjectId id)
    {
        var (success, msg) = await productService.DeleteProductAsync(id);
        return success ? Ok(new { message = msg }) : NotFound(new { message = msg });
    }
}

服务注册

在 Program.cs 中实现服务注册。

using MongoDB.Driver;
using MongoDbExample;
using MongoDbExample.Database.Repositorys;
using MongoDbExample.Repositorys;

var builder = WebApplication.CreateBuilder(args);

// 添加日志等基础服务
// 创建 ILoggerFactory
var loggerFactory = LoggerFactory.Create(loggingBuilder =>
{
    loggingBuilder.AddConsole();
});

var logger = loggerFactory.CreateLogger<CinemaAppDbContext>();

// Add services to the container.

// 从环境变量获取连接字符串
var connectionString = Environment.GetEnvironmentVariable("MONGODB_URI");
if (connectionString == null)
{
    Console.WriteLine("You must set your 'MONGODB_URI' environment variable. To learn how to set it, see https://www.mongodb.com/docs/drivers/csharp/current/quick-start/#set-your-connection-string");
    Environment.Exit(0);
}

// 创建 DbContext 实例
var database = CinemaAppDbContext.GetDatabase(connectionString, "sample_mflix");
var cinemaContext = CinemaAppDbContext.Create(logger, database);

{
    var movie = cinemaContext.Movies.First(m => m.Title == "Back to the Future");
    Console.WriteLine(movie.Plot);
}

// 将实例注册为服务
builder.Services.AddSingleton(cinemaContext);
// 注册 ICinemaAppRepository 仓储
builder.Services.AddScoped<ICinemaAppRepository, CinemaAppRepository>();

// 添加控制器
builder.Services.AddControllers();
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseAuthorization();
app.MapControllers();

await app.RunAsync();

快照注入数据库连接配置

以上就是使用 MongoDB.EntityFrameworkCore 示例的 demo 实现，获取数据库连接字符串可以使用 快照方式注入，改进如下：

• MongoDbSettings

public class MongoDbSettings
{
    public string ConnectionString { get; set; } = "mongodb://localhost:27017";
    public string DatabaseName { get; set; } = "cinema_app";
}

1. 注册配置类

在 Program.cs 中将 MongoDbSettings 注册为服务，并绑定到配置。

var builder = WebApplication.CreateBuilder(args);

// 从 appsettings.json 或其他配置源绑定 MongoDbSettings
builder.Services.Configure<MongoDbSettings>(builder.Configuration.GetSection("MongoDbSettings"));

2. 注入 IOptionsSnapshot<MongoDbSettings>

在需要使用的类中，通过构造函数注入 IOptionsSnapshot<MongoDbSettings>，并获取当前配置快照。

public class SomeService
{
    private readonly MongoDbSettings _mongoDbSettings;

    public SomeService(IOptionsSnapshot<MongoDbSettings> optionsSnapshot)
    {
        _mongoDbSettings = optionsSnapshot.Value;
    }

    public void PrintSettings()
    {
        Console.WriteLine($"ConnectionString: {_mongoDbSettings.ConnectionString}");
        Console.WriteLine($"DatabaseName: {_mongoDbSettings.DatabaseName}");
    }
}

3. 配置文件 appsettings.json 示例

添加 MongoDbSettings 配置：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "MongoDbSettings": {
    "ConnectionString": "mongodb://localhost:27017",
    "DatabaseName": "cinema_app"
  }
}

关于 MongoDB 更多信息，请查看官方文档

• https://www.mongodb.com/zh-cn/docs/

总结

本文详细讲解了如何在 .NET/C# 项目中使用 MongoDB.EntityFrameworkCore 这一官方提供程序，轻松地连接并操作 MongoDB 数据库。文章从基础讲起，介绍了 MongoDB 连接字符串的格式和用法，并通过具体的 C# 示例演示了如何连接到 MongoDB 副本集。随后，通过构建一个完整的电影票信息查询 Web API 应用，逐步展示了基于 EF Core 的数据库上下文（DbContext）、实体类设计、仓储模式（Repository）、服务逻辑以及控制器的具体实现方式。最后，还补充了如何通过配置快照的方式动态注入 MongoDB 的连接配置信息。整篇文章内容由浅入深，结构清晰，适合希望将 .NET 应用与 MongoDB 结合使用的开发者参考学习。