.NET Aspire MongoDB 数据库集成

包含： - Client 集成

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

托管集成

托管集成 MongoDB 服务器将服务器建模为 MongoDBServerResource 类型和数据库作为 MongoDBDatabaseResource 类型。 若要访问这些类型和 API，请在 📦 项目中添加 AspireMongoDB.Hosting. NuGet 包。

dotnet add package Aspire.Hosting.MongoDB

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

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

添加 MongoDB 服务器资源和数据库资源

在应用主机项目中，调用 AddMongoDB 添加并返回 MongoDB 服务器资源生成器。 将对返回的资源构建器的调用链接到 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...

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

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

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

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

参数的名称是 mongo-password，但实际上只是给资源名称添加 -password 后缀以进行格式化。 有关详细信息，请查看 开发环境中应用程序机密的安全存储在ASP.NET Core 和 添加 MongoDB参数的服务器资源。

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

添加带有数据卷的 MongoDB 服务器资源

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

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...

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

通过数据绑定装载添加 MongoDB 服务器资源

若要将数据绑定安装添加到 MongoDB 服务器资源，请调用 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...

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

使用初始化数据绑定挂载来添加 MongoDB 服务器资源

若要将初始化文件夹的数据绑定装载添加到 MongoDB 服务器资源中，请调用 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...

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

用参数添加 MongoDB 服务器资源

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

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 管理员用户界面。 若要添加与 MongoDB相对应的 docker.io/library/mongo-express Express 资源，请在 服务器资源上调用 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...

前面的代码将添加配置为连接到 MongoDB 服务器资源的 MongoDB Express 资源。 默认凭据为：

• 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 会自动为 MongoDB 服务器资源添加运行状况检查。 运行状况检查确保MongoDB 服务器资源正常运行，从而可以建立连接。

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

Client 集成

若要开始 .NET AspireMongoDB 客户端整合，请在客户端消费项目中安装 📦Aspire。MongoDB。驱动程序 的 NuGet 包，也就是使用 MongoDB 客户端的应用程序项目。 MongoDB 客户端集成注册 IMongoClient 实例，该实例可用于与 MongoDB 服务器资源交互。 如果应用主机添加了 MongoDB 数据库资源，则还会注册 IMongoDatabase 实例。

dotnet add package Aspire.MongoDB.Driver

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

添加 MongoDB 客户端

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

builder.AddMongoDBClient(connectionName: "mongodb");

然后，可以使用依赖项注入检索 IMongoClient 实例。 例如，若要从示例服务检索客户端：

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

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

添加键控 MongoDB 客户端

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

builder.AddKeyedMongoDBClient(name: "mainDb");
builder.AddKeyedMongoDBClient(name: "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。 它使用 MongoDBSettings 键从配置加载 Aspire:MongoDB:Driver。 以下代码片段是用于配置某些选项的 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");

配置选项

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

Client 整合健康检查

默认情况下，所有服务的.NET.NET Aspire客户端集成 都启用了 状态检查。 同样，许多托管集成 .NET.NET Aspire 也启用健康检查端点。 有关详细信息，请参阅：

• 在 C# .NET 应用运行状况检查
• 运行状况检查在 ASP.NET Core 中

默认情况下，.NET AspireMongoDB 客户端集成处理以下方案：

• 启用后，添加一个运行状况检查，以验证是否能在一定时间内建立连接并对 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 存储库