.NET Aspire MongoDB 数据库集成

包括：、、托管集成 和 、、Client 集成

MongoDB 是一种 NoSQL 数据库，可提供高性能、高可用性和轻松的可伸缩性。 通过 .NET AspireMongoDB 集成，可以连接到现有 MongoDB 实例（包括 MongoDB Atlas），或使用 docker.io/library/mongo 容器映像从 .NET 创建新实例

托管集成

托管集成 MongoDBserver 将 server 建模为 MongoDBServerResource 类型和数据库作为 MongoDBDatabaseResource 类型。 若要访问这些类型和 API，请在 应用主机 项目中添加 📦Aspire.Hosting.MongoDB NuGet 包。

.NET CLI

dotnet add package Aspire.Hosting.MongoDB

PackageReference

<PackageReference Include="Aspire.Hosting.MongoDB"
                  Version="*" />

有关详细信息，请参阅 dotnet add package 或 在 .NET 应用程序中管理软件包依赖项。

添加 MongoDBserver 资源和数据库资源

在应用主机项目中，调用 AddMongoDB 添加并返回 MongoDBserver 资源生成器。 将对返回的资源构建器的调用链接到 AddDatabase，以添加 MongoDB 数据库资源。

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithLifetime(ContainerLifetime.Persistent);

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

// After adding all resources, run the app...

注意

MongoDB 容器启动速度可能较慢，因此，最好使用 的持久 生存期，以避免不必要的重启。 有关详细信息，请参阅 容器资源生存期。

当 .NET.NET Aspire 向应用主机添加容器映像时，如上例中所示的 docker.io/library/mongo 映像，它会在本地计算机上创建新的 MongoDB 实例。 对 MongoDBserver 资源生成器（mongo 变量）的引用用于添加数据库。 数据库命名为 mongodb，然后添加到 ExampleProject。 MongoDB server 资源包括默认凭据：

• MONGO_INITDB_ROOT_USERNAME：值 admin。
• MONGO_INITDB_ROOT_PASSWORD：使用 CreateDefaultPasswordParameter 方法生成的随机 password。

应用主机运行时，密码存储在应用主机的机密存储中。 它被添加到 Parameters 部分，例如：

{
  "Parameters:mongo-password": "<THE_GENERATED_PASSWORD>"
}

参数的名称是 mongo-password，但实际上只是给资源名称添加 -password 后缀以进行格式化。 有关详细信息，请参阅 ASP.NET Core 开发中的应用机密的安全存储，使用参数添加 MongoDBserver 资源。

WithReference 方法在名为 mongodb 的 ExampleProject 中配置连接，WaitFor 指示应用主机在 mongodb 资源准备就绪之前不启动依赖服务。

提示

如果想要连接到现有 MongoDBserver，请改为调用 AddConnectionString。 如需更多信息，请参阅 现有资源参考。

添加具有数据卷的 MongoDBserver 资源

若要将数据卷添加到 MongoDBserver 资源，请在 MongoDBserver 资源上调用 WithDataVolume 方法：

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithDataVolume();

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

// After adding all resources, run the app...

数据卷用于在容器的生命周期之外保留 MongoDBserver 数据。 数据卷装载在 MongoDBserver 容器中的 /data/db 路径上，如果未提供 name 参数，则会随机生成名称。 有关数据卷的更多信息以及它们为何优于 绑定挂载的原因，请参阅 Docker 文档：卷。

警告

密码存储在数据卷中。 使用数据卷时，如果密码发生更改，则在删除卷之前，它将无法正常工作。

通过数据绑定挂载添加 MongoDBserver 资源

若要将数据绑定装载添加到 MongoDBserver 资源，请调用 WithDataBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithDataBindMount(@"C:\MongoDB\Data");

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

// After adding all resources, run the app...

重要

与 卷相比，绑定 装载的数据 功能有限，从而提供更好的性能、可移植性和安全性，使它们更适用于生产环境。 但是，绑定装载允许直接访问和修改主机系统上的文件，非常适合在需要实时更改的情况下进行开发和测试。

数据绑定装载依赖于主机的文件系统在容器重启时保留 MongoDBserver 数据。 数据绑定挂载在主机 MongoDB的 Windows C:\MongoDB\Data（或 Unix上的 /MongoDB/Data）路径中的server 容器上。 有关数据绑定装载的详细信息，请参阅 Docker 文档：绑定装载。

添加带有初始化数据的绑定挂载 MongoDBserver 资源

若要将初始化文件夹数据绑定装载添加到 MongoDBserver 资源，请调用 WithInitBindMount 方法：

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithInitBindMount(@"C:\MongoDB\Init");

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

// After adding all resources, run the app...

初始化数据绑定装载用于使用数据初始化 MongoDBserver。 初始化数据绑定装载安装在 Windows 上的 C:\MongoDB\Init（或 Unix上的 /MongoDB/Init）路径，该主机路径在 MongoDBserver 容器中映射到 MongoDBserver 容器中的 /docker-entrypoint-initdb.d 路径。 MongoDB 执行此文件夹中找到的脚本，这对于将数据加载到数据库中很有用。

使用带参数的方式添加 MongoDBserver 资源

如果要显式提供容器映像使用的密码，可以将这些凭据作为参数提供。 请考虑以下替代示例：

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username");
var password = builder.AddParameter("password", secret: true);

var mongo = builder.AddMongoDB("mongo", username, password);
var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

// After adding all resources, run the app...

有关提供参数的详细信息，请参阅 外部参数。

添加 MongoDB Express 资源

MongoDB Express 是基于 Web 的 MongoDB 管理员用户界面。 若要添加与 docker.io/library/mongo-express 容器映像对应的 MongoDB Express 资源，请在 MongoDBserver 资源上调用 WithMongoExpress 方法：

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithMongoExpress();

var mongodb = mongo.AddDatabase("mongodb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(mongodb)
       .WaitFor(mongodb);

// After adding all resources, run the app...

提示

请调用 WithHostPort API 配置 MongoExpressContainerResource 主机端口，并提供所需的端口号。

前面的代码添加了一个 MongoDB Express 资源，该资源被配置为连接到 MongoDBserver 资源。 默认凭据为：

• ME_CONFIG_MONGODB_SERVER：分配给父 MongoDBServerResource的名称，在本例中，它将是 mongo。
• ME_CONFIG_BASICAUTH：值 false。
• ME_CONFIG_MONGODB_PORT：从父 MongoDBServerResource的主终结点目标端口进行分配。
• ME_CONFIG_MONGODB_ADMINUSERNAME：与父 MongoDBServerResource中配置的用户名相同。
• ME_CONFIG_MONGODB_ADMINPASSWORD：父 MongoDBServerResource中配置的相同密码。

此外，WithMongoExpress API 公开了一个可选的 configureContainer 参数，其类型为 Action<IResourceBuilder<MongoExpressContainerResource>>，可用于配置 MongoDB Express 容器资源。

托管集成运行状况检查

托管集成 MongoDB 会自动为 MongoDBserver 资源添加运行状况检查。 健康检查验证了MongoDBserver资源是否在运行，以及是否可以建立连接。

托管集成依赖于 📦 AspNetCore.HealthChecks 和MongoDb NuGet 包。

Client 集成

若要开始 .NET AspireMongoDBclient 集成，请在 client消费项目中安装 📦Aspire。MongoDB。Driver NuGet包，该项目是使用 MongoDBclient的应用程序的项目。 在MongoDBclient 集成中注册了一个用于与MongoDBserver 资源交互的IMongoClient 实例。 如果应用主机添加了 MongoDB 数据库资源，则还会注册 IMongoDatabase 实例。

.NET CLI

dotnet add package Aspire.MongoDB.Driver

PackageReference

<PackageReference Include="Aspire.MongoDB.Driver"
                  Version="*" />

添加 MongoDBclient

在你的 client使用项目的 Program.cs 文件中，对任何 IHostApplicationBuilder 调用 AddMongoDBClient 扩展方法，以便通过依赖注入容器注册 IMongoClient 供使用。 该方法采用连接名称参数。

builder.AddMongoDBClient(connectionName: "mongodb");

提示

connectionName 参数必须与在应用主机项目中添加 MongoDBserver 资源（或数据库资源）时使用的名称匹配。 换句话说，在调用 AddDatabase 时提供一个名为 mongodb 的名称，该名称在调用 AddMongoDBClient时应使用。 有关详细信息，请参阅 添加 MongoDBserver 资源和数据库资源。

然后，可以使用依赖项注入检索 IMongoClient 实例。 例如，若要从一个示例服务中获取 client，

public class ExampleService(IMongoClient client)
{
    // Use client...
}

IMongoClient 用于与 MongoDBserver 资源交互。 它可用于创建应用主机项目尚未识别的数据库。 在应用主机中定义 MongoDB 数据库资源时，可以改为要求依赖项注入容器提供 IMongoDatabase 实例。 有关依赖项注入的详细信息，请参阅 .NET 依赖项注入。

添加带键 MongoDBclient

在某些情况下，可能需要使用不同的连接名称注册多个 IMongoDatabase 实例。 若要注册密钥 MongoDB 客户端，请调用 AddKeyedMongoDBClient 方法：

builder.AddKeyedMongoDBClient(name: "mainDb");
builder.AddKeyedMongoDBClient(name: "loggingDb");

重要

使用密钥服务时，预期 MongoDB 资源应配置两个命名数据库，一个用于 mainDb，一个用于 loggingDb。

然后，可以使用依赖项注入检索 IMongoDatabase 实例。 例如，若要从示例服务检索连接，

public class ExampleService(
    [FromKeyedServices("mainDb")] IMongoDatabase mainDatabase,
    [FromKeyedServices("loggingDb")] IMongoDatabase loggingDatabase)
{
    // Use databases...
}

有关密钥服务的详细信息，请参阅 .NET 依赖项注入：键式服务。

配置

.NET Aspire MongoDB 数据库集成提供了多种配置方法和选项，以满足项目的要求和约定。

使用连接字符串

使用 ConnectionStrings 配置部分中的连接字符串时，可以在调用 builder.AddMongoDBClient()时提供连接字符串的名称：

builder.AddMongoDBClient("mongo");

从 ConnectionStrings 配置部分检索连接字符串。 请考虑以下 MongoDB 示例 JSON 配置：

{
  "ConnectionStrings": {
    "mongo": "mongodb://server:port/test",
  }
}

或者，请考虑以下 MongoDB Atlas 示例 JSON 配置：

{
  "ConnectionStrings": {
    "mongo": "mongodb+srv://username:password@server.mongodb.net/",
  }
}

有关如何设置此连接字符串格式的详细信息，请参阅 MongoDB：ConnectionString 文档。

使用配置提供程序

.NET Aspire MongoDB 集成支持 Microsoft.Extensions.Configuration。 它使用 Aspire:MongoDB:Driver 键从配置加载 MongoDBSettings。 以下代码片段是用于配置某些选项的 appsettings.json 文件示例：

{
  "Aspire": {
    "MongoDB": {
      "Driver": {
        "ConnectionString": "mongodb://server:port/test",
        "DisableHealthChecks": false,
        "HealthCheckTimeout": 10000,
        "DisableTracing": false
      },
    }
  }

使用内联配置

还可以传递 Action<MongoDBSettings> 委托来设置部分或全部内联选项：

builder.AddMongoDBClient("mongodb",
    static settings => settings.ConnectionString = "mongodb://server:port/test");

配置选项

下面是具有相应默认值的可配置选项：

名字	描述
ConnectionString	要连接到 MongoDB 数据库数据库的连接字符串。
DisableHealthChecks	一个布尔值，该值指示是否禁用数据库运行状况检查。
HealthCheckTimeout	一个 int? 值，指示 MongoDB 运行状况检查超时（以毫秒为单位）。
DisableTracing	一个布尔值，用于指示 OpenTelemetry 跟踪是否被禁用。

健康检查

默认情况下，.NET.NET Aspire 集成为所有服务启用 运行状况检查。 有关详细信息，请参阅 .NET.NET Aspire 集成概述。

默认情况下，.NET AspireMongoDBclient 集成处理以下方案：

• 启用后，添加一个运行状况检查，以验证是否能在一定时间内建立连接并对 MongoDB 数据库运行命令。
• 与 /health HTTP 终结点集成，该终结点要求所有已注册的健康检查都必须通过，应用才能被视为可以接受流量。

可观测性和遥测

.NET .NET Aspire 集成会自动完成日志记录、追踪和指标的配置，这些配置有时被称为 观测性的核心支柱。 有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。 根据支持服务，某些集成可能仅支持其中一些功能。 例如，某些集成支持日志记录和跟踪，但不支持指标。 也可以使用 配置 部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire MongoDB 数据库集成使用标准 .NET 日志记录，并且会看到以下类别中的日志条目：

• MongoDB[.*]：来自 MongoDB 命名空间的任何日志条目。

追踪

.NET Aspire MongoDB 数据库集成系统使用 OpenTelemetry发出以下跟踪活动：

• MongoDB.Driver.Core.Extensions.DiagnosticSources

指标

.NET Aspire MongoDB 数据库集成目前不会公开任何 OpenTelemetry 指标。

另请参阅

• MongoDB 数据库
• .NET .NET Aspire 集成
• .NET Aspire GitHub 存储库