интеграция базы данных .NET AspireMongoDB

Статья
01/22/2025

Включает:интеграция хостинга и Client интеграция

MongoDB — это база данных NoSQL, которая обеспечивает высокую производительность, высокую доступность и простую масштабируемость. Интеграция .NET AspireMongoDB позволяет подключаться к существующим экземплярам MongoDB (включая MongoDB Atlas) или создавать новые экземпляры из .NET с помощью образа контейнера docker.io/library/mongo

Интеграция хостинга

Сервер MongoDB, на котором размещена интеграция, моделирует сервер в качестве типа MongoDBServerResource и базы данных в качестве типа MongoDBDatabaseResource. Чтобы получить доступ к этим типам и API, добавьте пакет NuGet 📦Aspire. Хостинг.MongoDB в проект хоста приложения .

.NET CLI
PackageReference

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

Заметка

Контейнер MongoDB может медленно запускаться, поэтому рекомендуется использовать постоянный срок службы для, чтобы избежать ненужных перезапусков. Дополнительные сведения см. в разделе время существования ресурса контейнера.

Когда .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, вызовите AddConnectionString вместо этого. Дополнительные сведения см. в статье Справочник по существующим ресурсам.

Добавление ресурса сервера 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 во время перезапуска контейнера. Монтаж привязки данных осуществляется в точке C:\MongoDB\Data на Windows (или /MongoDB/Data на Unix) на хост-компьютере внутри контейнера сервера MongoDB. Подробную информацию о монтировании привязки данных см. в документации по Docker: монтирование привязки.

Добавление ресурса сервера MongoDB с привязкой данных инициализации через bind mount

Чтобы добавить подключение данных папки инициализации к ресурсу сервера 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 — это веб-интерфейс MongoDB администратора. Чтобы добавить ресурс Express, соответствующий образу контейнера, вызовите метод в ресурсе сервера .

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

Совет

Чтобы настроить порт узла для цепочки MongoExpressContainerResource, выполните вызов к API WithHostPort и укажите нужный номер порта.

Приведенный выше код добавляет ресурс MongoDB Express, настроенный для подключения к ресурсу сервера MongoDB. Учетные данные по умолчанию:

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.

Кроме того, API WithMongoExpress предоставляет необязательный параметр configureContainer типа Action<IResourceBuilder<MongoExpressContainerResource>>, который используется для настройки ресурса контейнера MongoDB Express.

Проверка работоспособности интеграции

Интеграция размещения MongoDB автоматически добавляет проверку работоспособности для ресурса сервера MongoDB. Проверка работоспособности проверяет, запущен ли ресурс сервера MongoDB и что подключение можно установить к нему.

Интеграция с системой хостинга зависит от пакета NuGet 📦 AspNetCore.HealthChecks.MongoDb.

интеграция Client

Чтобы приступить к работе с интеграцией клиента .NET AspireMongoDB, установите пакет NuGet 📦Aspire.MongoDB.Драйвер в проект, использующий клиент, то есть в проект приложения, использующего клиент MongoDB. Интеграция клиента MongoDB регистрирует экземпляр IMongoClient, который можно использовать для взаимодействия с ресурсом сервера MongoDB. Если хост приложения добавляет ресурсы базы данных MongoDB, то регистрируется также и экземпляр IMongoDatabase.

.NET CLI
PackageReference

dotnet add package Aspire.MongoDB.Driver

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

Добавить клиента MongoDB

В файле Program.cs проекта, используемого клиентом, вызовите метод расширения AddMongoDBClient для любой IHostApplicationBuilder, чтобы зарегистрировать IMongoClient для использования с помощью контейнера внедрения зависимостей. Метод принимает параметр имени подключения.

builder.AddMongoDBClient(connectionName: "mongodb");

Совет

Параметр connectionName должен соответствовать имени, используемому при добавлении ресурса сервера MongoDB (или ресурса базы данных при указании) в проекте узла приложения. Другими словами, при вызове AddDatabase и указании имени mongodb то же имя следует использовать при вызове AddMongoDBClient. Дополнительные сведения см. в статье Добавление 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");

Важный

При использовании ключевых служб ожидается, что ресурс MongoDB настраивает две именованные базы данных, одну для mainDb и одну для loggingDb.

Затем можно извлечь экземпляры IMongoDatabase с помощью инъекции зависимостей. Например, чтобы извлечь подключение из примерного сервиса:

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

Дополнительные сведения о ключевых службах см. в разделе .NET внедрение зависимостей: ключевыеслужбы.

Конфигурация

Интеграция .NET AspireMongoDB базы данных обеспечивает несколько подходов к конфигурации и вариантов для удовлетворения требований и соглашений вашего проекта.

Используйте строку подключения

При использовании строки подключения из раздела конфигурации ConnectionStrings можно указать имя строки подключения при вызове builder.AddMongoDBClient():

builder.AddMongoDBClient("mongo");

Строка подключения извлекается из раздела конфигурации ConnectionStrings. Рассмотрим следующий пример MongoDB конфигурации JSON:

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

В качестве альтернативы рассмотрим следующий пример конфигурации Atlas: MongoDBJSON.

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

Дополнительные сведения о форматировании этой строки подключения см. в MongoDB: документации по ConnectionString.

Использование поставщиков конфигураций

Интеграция .NET AspireMongoDB поддерживает 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");

Параметры конфигурации

Ниже приведены настраиваемые параметры с соответствующими значениями по умолчанию:

Имя	Описание
`ConnectionString`	Строка подключения базы данных MongoDB для подключения к ней.
`DisableHealthChecks`	Логическое значение, указывающее, отключена ли проверка работоспособности базы данных.
`HealthCheckTimeout`	Значение `int?`, указывающее время ожидания проверки работоспособности MongoDB в миллисекундах.
`DisableTracing`	Логическое значение, указывающее, отключена ли трассировка OpenTelemetry.

Проверки здоровья

По умолчанию .NET.NET Aspire интеграции позволяют проверки работоспособности для всех служб. Дополнительные сведения см. в обзоре интеграции .NET.NET Aspire.

По умолчанию интеграция клиента .NET AspireMongoDB обрабатывает следующие сценарии:

Добавляет проверку работоспособности при включении, которая проверяет, можно ли выполнять команды подключения к базе данных MongoDB в течение определенного периода времени.
Интегрируется с HTTP-узлом /health, который указывает, что все зарегистрированные проверки работоспособности должны быть успешными, чтобы приложение считалось готовым принимать трафик.

Наблюдаемость и телеметрия

.NET .NET Aspire интеграции автоматически настраивают конфигурации для ведения журналов, трассировки и метрик, которые иногда называются столпами наблюдаемости. Дополнительные сведения об наблюдаемости интеграции и телеметрии см. в .NET.NET Aspire обзоре интеграции. В зависимости от резервной службы некоторые интеграции могут поддерживать только некоторые из этих функций. Например, некоторые интеграции поддерживают ведение журнала и трассировку, но не метрики. Функции телеметрии также можно отключить с помощью методов, представленных в разделе конфигурации .

Лесозаготовка

Интеграция с базой данных .NET AspireMongoDB использует стандартное ведение журнала .NET, и вы увидите записи журнала из следующих категорий:

MongoDB[.*]: все записи журнала из пространства имен MongoDB.

Отслеживание

Интеграция базы данных .NET AspireMongoDB выдает следующие действия трассировки с помощью OpenTelemetry:

MongoDB.Driver.Core.Extensions.DiagnosticSources

Метрика

Интеграция .NET AspireMongoDB базы данных в настоящее время не предоставляет никаких OpenTelemetry метрик.

Поделиться через

интеграция базы данных .NET AspireMongoDB

Интеграция хостинга

Добавить серверный ресурс MongoDB и ресурс базы данных

Добавление ресурса сервера MongoDB с объемом данных

Добавление ресурса сервера MongoDB с подключением привязки данных

Добавление ресурса сервера MongoDB с привязкой данных инициализации через bind mount

Добавление ресурса сервера MongoDB с параметрами

Добавить ресурс MongoDB Express

Проверка работоспособности интеграции

интеграция Client

Добавить клиента MongoDB

Добавить клиент с ключом MongoDB

Конфигурация

Используйте строку подключения

Использование поставщиков конфигураций

Использование встроенных конфигураций

Параметры конфигурации

Проверки здоровья

Наблюдаемость и телеметрия

Лесозаготовка

Отслеживание

Метрика

См. также

Дополнительные ресурсы