Compartir a través de

.NET Aspire MongoDB integración de bases de datos

  • Artículo

Incluye:integración de hospedaje y integraciónClient

MongoDB es una base de datos NoSQL que proporciona alto rendimiento, alta disponibilidad y escalabilidad fácil. La integración de .NET AspireMongoDB permite conectarse a instancias de MongoDB existentes (incluidas MongoDB Atlas) o crear nuevas instancias desde .NET con la imagen de contenedor docker.io/library/mongo

Integración de hospedaje

El servidor MongoDB que hospeda la integración modela el servidor como el tipo de MongoDBServerResource y la base de datos como el tipo de MongoDBDatabaseResource. Para acceder a estos tipos y API, agregue el paquete NuGet 📦Aspire.Hosting.MongoDB en el proyecto del host de la aplicación de .

dotnet add package Aspire.Hosting.MongoDB

Para obtener más información, consulte dotnet add package o Administrar dependencias de paquetes en aplicaciones .NET.

Agregar MongoDB recurso de servidor y recurso de base de datos

En el proyecto host de la aplicación, llame a AddMongoDB para agregar y devolver un generador MongoDB de recursos de servidor. Enlaza una llamada al generador de recursos devuelto a AddDatabasepara agregar un recurso de base de datos 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...

Nota

El contenedor de MongoDB puede ser lento para iniciarse, por lo que es mejor usar un duración de persistente para evitar reinicios innecesarios. Para obtener más información, consulte duración de los recursos de contenedor.

Cuando .NET.NET Aspire agrega una imagen de contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de docker.io/library/mongo, crea una nueva instancia de MongoDB en el equipo local. Se usa una referencia al generador de recursos del servidor MongoDB (la variable mongo) para agregar una base de datos. La base de datos se denomina mongodb y, a continuación, se agrega al ExampleProject. El recurso de servidor MongoDB incluye credenciales predeterminadas:

  • MONGO_INITDB_ROOT_USERNAME: valor de admin.
  • MONGO_INITDB_ROOT_PASSWORD: password generados aleatoriamente mediante el método CreateDefaultPasswordParameter.

Cuando se ejecuta el host de la aplicación, la contraseña se almacena en el almacén de secretos del host de la aplicación. Se agrega a la sección Parameters, por ejemplo:

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

El nombre del parámetro es mongo-password, pero realmente solo da formato al nombre del recurso con un sufijo -password. Para obtener más información, consulte Almacenamiento seguro de secretos de aplicación en desarrollo en ASP.NET Core y Agregar recurso de servidor de MongoDB con parámetros.

El método WithReference configura una conexión en el ExampleProject denominado mongodb y el WaitFor indica al host de la aplicación que no inicie el servicio dependiente hasta que el recurso de mongodb esté listo.

Propina

Si prefiere conectarse a un servidor MongoDB existente, llame a AddConnectionString en su lugar. Para obtener más información, consulte Consulte los recursos existentes.

Agregar MongoDB recurso de servidor con volumen de datos

Para agregar un volumen de datos al recurso del servidor de MongoDB, llame al método WithDataVolume en el recurso del servidor de 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...

El volumen de datos se usa para conservar los datos del servidor de MongoDB fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta /data/db en el contenedor del servidor MongoDB y cuando no se proporciona un parámetro name, el nombre se genera al azar. Para obtener más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren a montajes de enlace, consulte la documentación de Docker: Volúmenes.

Advertencia

La contraseña se almacena en el volumen de datos. Al usar un volumen de datos y si cambia la contraseña, no funcionará hasta que elimine el volumen.

Añadir recurso del servidor MongoDB con montaje de vinculación de datos

Para agregar un montaje de vínculos de datos al recurso del servidor de MongoDB, llame al método 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...

Importante

Los montajes de enlace de datos tienen una funcionalidad limitada en comparación con los volúmenes , que ofrecen mejor rendimiento, portabilidad y seguridad, haciéndolos más adecuados para entornos de producción. Sin embargo, los montajes de enlace permiten el acceso directo y la modificación de archivos en el sistema host, ideal para el desarrollo y las pruebas donde se necesitan cambios en tiempo real.

Los montajes de enlace de datos dependen del sistema de archivos del equipo host para conservar los datos del servidor de MongoDB en los reinicios del contenedor. El montaje de enlace de datos está montado en la ruta C:\MongoDB\Data en Windows (o /MongoDB/Data en Unix) en la máquina host, dentro del contenedor del servidor MongoDB. Para obtener más información sobre los montajes de enlace de datos, consulte los Docker documentos: montajes enlazados.

Adición del recurso de servidor MongoDB con montaje unido de datos de inicialización

Para agregar un montaje de enlace de datos de carpeta de inicialización al recurso del servidor de MongoDB, llame al método 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...

El montaje de enlace de datos de inicialización se utiliza para inicializar el servidor MongoDB con datos. El montaje de enlace de datos de inicialización se coloca en la ruta C:\MongoDB\Init en Windows (o /MongoDB/Init en Unix) en la máquina host dentro del contenedor del servidor MongoDB y se mapea a la ruta /docker-entrypoint-initdb.d en el contenedor del servidor MongoDB. MongoDB ejecuta los scripts que se encuentran en esta carpeta, lo que resulta útil para cargar datos en la base de datos.

Agregar recurso del servidor MongoDB con parámetros

Cuando quiera proporcionar explícitamente la contraseña usada por la imagen de contenedor, puede proporcionar estas credenciales como parámetros. Considere el siguiente ejemplo alternativo:

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

Para obtener más información sobre cómo proporcionar parámetros, consulte Parámetros externos.

Agregar el recurso MongoDB Express

MongoDB Express es una interfaz de usuario de administración de MongoDB basada en web. Para agregar un recurso MongoDB Express que corresponda a la imagen de contenedor de docker.io/library/mongo-express, llame al método WithMongoExpress en el recurso del servidor de MongoDB:

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

Propina

Para configurar el puerto de host para el MongoExpressContainerResource encadene una llamada a la API de WithHostPort y proporcione el número de puerto deseado.

El código anterior agrega un recurso MongoDB Express que está configurado para conectarse al recurso de servidor de MongoDB. Las credenciales predeterminadas son:

  • ME_CONFIG_MONGODB_SERVER: el nombre asignado al MongoDBServerResourceprimario, en este caso sería mongo.
  • ME_CONFIG_BASICAUTH: valor de false.
  • ME_CONFIG_MONGODB_PORT: asignado desde el puerto de destino del punto de conexión principal del MongoDBServerResourceprimario.
  • ME_CONFIG_MONGODB_ADMINUSERNAME: el mismo nombre de usuario que se configuró en el MongoDBServerResourceprimario.
  • ME_CONFIG_MONGODB_ADMINPASSWORD: la misma contraseña que se ha configurado en el MongoDBServerResourceprimario.

Además, la API de WithMongoExpress expone un parámetro opcional configureContainer de tipo Action<IResourceBuilder<MongoExpressContainerResource>> que se usa para configurar el recurso de contenedor de MongoDB Express.

Integración de pruebas de salud del hospedaje

La integración de hospedaje de MongoDB agrega automáticamente una comprobación de estado para el recurso del servidor de MongoDB. La comprobación de estado comprueba que el recurso MongoDB servidor se está ejecutando y que se puede establecer una conexión a él.

La integración de hospedaje se basa en el paquete NuGet 📦 AspNetCore.HealthChecks.MongoDb.

integración de Client

Para empezar a trabajar con la integración del cliente , instale el paquete NuGet Driver .en el proyecto que consume el cliente, es decir, el proyecto de la aplicación que usa el cliente. La integración de cliente MongoDB registra una instancia de IMongoClient que puede usar para interactuar con el recurso de servidor MongoDB. Si el host de la aplicación agrega los recursos de base de datos MongoDB, la instancia IMongoDatabase también se registra.

dotnet add package Aspire.MongoDB.Driver

Agregar cliente MongoDB

En el archivo Program.cs del proyecto cliente, llame al método de extensión AddMongoDBClient en cualquier IHostApplicationBuilder para registrar un IMongoClient para su uso a través del contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddMongoDBClient(connectionName: "mongodb");

Propina

El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso de servidor MongoDB (o el recurso de base de datos cuando se proporciona) en el proyecto host de la aplicación. Es decir, cuando se llama a AddDatabase y se proporciona un nombre de mongodb ese mismo nombre se debe usar al llamar a AddMongoDBClient. Para obtener más información, consulte Añadir MongoDB recurso de servidor y recurso de base de datos.

A continuación, puede recuperar la instancia de IMongoClient usando inyección de dependencias. Por ejemplo, para recuperar el cliente de un servicio de ejemplo:

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

El IMongoClient se usa para interactuar con el recurso de servidor MongoDB. Se puede usar para crear bases de datos que aún no se conocen en el proyecto host de la aplicación. Al definir un recurso de base de datos MongoDB en el host de la aplicación, podría requerir que el contenedor de inserción de dependencias proporcione una instancia de IMongoDatabase. Para obtener más información sobre la inserción de dependencias, consulte .NET inserción de dependencias.

Adición de un cliente de MongoDB con clave

Puede haber situaciones en las que quiera registrar varias instancias de IMongoDatabase con nombres de conexión diferentes. Para registrar clientes de MongoDB con clave, llame al método AddKeyedMongoDBClient:

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

Importante

Cuando se usan servicios con claves, se espera que el recurso de MongoDB configure dos bases de datos con nombre, una para el mainDb y otra para la loggingDb.

A continuación, puede recuperar las instancias de IMongoDatabase usando inyección de dependencias. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:

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

Para obtener más información sobre los servicios con claves, consulte .NET inserción de dependencias: Servicios con claves.

Configuración

La integración de base de datos .NET AspireMongoDB proporciona varios enfoques de configuración y opciones para cumplir los requisitos y convenciones del proyecto.

Uso de una cadena de conexión

Al usar una cadena de conexión de la sección de configuración de ConnectionStrings, puede proporcionar el nombre de la cadena de conexión al llamar a builder.AddMongoDBClient():

builder.AddMongoDBClient("mongo");

La cadena de conexión se obtiene de la sección de configuración de ConnectionStrings. Tenga en cuenta los siguientes MongoDB ejemplo JSON configuración:

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

Como alternativa, considere el siguiente ejemplo de MongoDB Atlas JSON configuración:

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

Para obtener más información sobre cómo dar formato a esta cadena de conexión, consulte MongoDB: documentación de ConnectionString.

Uso de proveedores de configuración

La integración de .NET AspireyMongoDB es compatible con Microsoft.Extensions.Configuration. Carga el MongoDBSettings desde la configuración mediante la clave Aspire:MongoDB:Driver. El fragmento de código siguiente es un ejemplo de un archivo appsettings.json que configura algunas de las opciones:

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

Utilice configuraciones en línea

También puede pasar el delegado de Action<MongoDBSettings> para configurar algunas o todas las opciones en línea.

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

Opciones de configuración

Estas son las opciones configurables con los valores predeterminados correspondientes:

Nombre Descripción
ConnectionString Cadena de conexión de la base de datos de MongoDB a la que se va a conectar.
DisableHealthChecks Valor booleano que indica si la comprobación de estado de la base de datos está deshabilitada o no.
HealthCheckTimeout Valor int? que indica el tiempo de espera del chequeo de estado MongoDB en milisegundos.
DisableTracing Valor booleano que indica si el seguimiento de OpenTelemetry está deshabilitado o no.

Client comprobaciones de salud de integración

De forma predeterminada, las integraciones de cliente .NET.NET Aspire tienen las comprobaciones de estado habilitadas para todos los servicios. Del mismo modo, muchas .NET.NET Aspireintegraciones de hospedaje también habilitan los puntos de conexión de comprobación de estado. Para obtener más información, consulte:

De forma predeterminada, la integración de cliente de .NET AspireMongoDB controla los escenarios siguientes:

  • Agrega una comprobación de estado que, cuando está habilitada, verifica que se pueda realizar una conexión y se puedan ejecutar comandos en la base de datos MongoDB dentro de un período de tiempo determinado.
  • Se integra con el endpoint HTTP de /health, que especifica que todas las comprobaciones de estado registradas deben aprobarse para que la aplicación se considere lista para aceptar el tráfico.

Observabilidad y telemetría

.NET .NET Aspire integraciones configuran automáticamente las configuraciones de registro, seguimiento y métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las características de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección Configuración.

Registro

La integración de la base de datos de .NET AspireMongoDB usa el registro estándar de .NET, y se ven entradas de registro de las siguientes categorías:

  • MongoDB[.*]: cualquier entrada de registro del espacio de nombres MongoDB.

Rastreo

La integración de la base de datos de .NET AspireMongoDB emite las siguientes actividades de seguimiento mediante OpenTelemetry:

  • MongoDB.Driver.Core.Extensions.DiagnosticSources

Métricas

La integración de la base de datos de .NET AspireMongoDB no expone actualmente ninguna métrica de OpenTelemetry.

Consulte también