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

2025-02-19

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

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

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

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

.NET интерфейс командной строки
СсылкаНаПакет

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: Объемы.

Предупреждение

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

Важный

Некоторые интеграции баз данных, включая интеграцию .NET AspireMongoDB, не могут успешно использовать тома данных после развертывания в Azure Container Apps (ACA). Это связано с тем, что ACA использует Server блок сообщений (SMB) для подключения контейнеров к томам данных, а некоторые системы не могут использовать это подключение. Aspire На панели мониторинга база данных, затронутая этой проблемой, имеет состояние "Активация" или "Сбой активации", но никогда не отображается как "Запущен".

Проблему можно устранить, развернув в Kubernetes кластере, например AzureKubernetes службы (AKS). Для получения дополнительной информации см. развертывания .NET.NET Aspire.

Добавление ресурса сервера 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 интерфейс командной строки
СсылкаНаПакет

dotnet add package Aspire.MongoDB.Driver

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

Важный

Пакет NuGet Aspire.MongoDB.Driver зависит от пакета NuGet MongoDB.Driver. С выпуском версии 3.0.0 MongoDB.Driver произошло изменение, нарушающее совместимость бинарных данных. Для решения этой проблемы был создан новый пакет интеграции клиента Aspire.MongoDB.Driver.v3. Исходный Aspire.MongoDB.Driver пакет продолжает ссылаться на MongoDB.Driver версию 2.30.0, обеспечивая совместимость с предыдущими версиями RabbitMQ интеграции клиента. Новый Aspire.MongoDB.Driver.v3 пакет ссылается на MongoDB.Driver версию 3.0.0. В будущей версии .NET.NET AspireAspire.MongoDB.Driver будет обновлен до версии 3.x, а пакет Aspire.MongoDB.Driver.v3 будет выведен из употребления. Дополнительные сведения см. в разделе "Обновление до версии 3.0".

Добавить клиента 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.

Client контроль состояния интеграции

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

.NET проверки работоспособности приложения на C#
проверка состояния в ASP.NET Core

По умолчанию интеграция клиента .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

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

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

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

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

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

Client контроль состояния интеграции

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

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

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

Метрика

См. также

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