Compartilhar via

integração de banco de dados .NET AspireMongoDB

  • Artigo

Inclui:integração de hospedagem e Client integração

MongoDB é um banco de dados NoSQL que fornece alto desempenho, alta disponibilidade e escalabilidade fácil. A integração .NET AspireMongoDB permite que você se conecte a instâncias MongoDB existentes (incluindo MongoDB Atlas) ou crie novas instâncias de .NET com a imagem de contêiner docker.io/library/mongo

Integração de hospedagem

O MongoDB servidor de integração de hospedagem modela o servidor como o tipo de MongoDBServerResource e o banco de dados como o tipo MongoDBDatabaseResource. Para acessar esses tipos e APIs, adicione o pacote NuGet 📦Aspire.Hosting.MongoDB no projeto do host do aplicativo .

dotnet add package Aspire.Hosting.MongoDB

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em aplicações .NET.

Adicionar recurso de servidor MongoDB e recurso de banco de dados

No projeto de host do aplicativo, chame AddMongoDB para adicionar e retornar um construtor de recursos do servidor MongoDB. Encadear uma chamada ao construtor de recursos retornado para AddDatabase, a fim de adicionar um recurso de banco de dados 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

O contêiner de pode ser lento para começar, portanto, é melhor usar um ciclo de vida persistente para evitar reinicializações desnecessárias. Para obter mais informações, consulte vida útil do recurso de contêiner.

Quando .NET.NET Aspire adiciona uma imagem de contêiner ao host do aplicativo, conforme mostrado no exemplo anterior com a imagem docker.io/library/mongo, ele cria uma nova instância de MongoDB em seu computador local. Uma referência ao construtor de recursos do servidor MongoDB (a variável mongo) é usada para adicionar um banco de dados. O banco de dados é nomeado mongodb e, em seguida, adicionado ao ExampleProject. O recurso de servidor MongoDB inclui credenciais padrão:

  • MONGO_INITDB_ROOT_USERNAME: um valor de admin.
  • MONGO_INITDB_ROOT_PASSWORD: password aleatório gerado usando o método CreateDefaultPasswordParameter.

Quando o host do aplicativo é executado, a senha é armazenada no repositório secreto do host do aplicativo. Ele é adicionado à seção Parameters, por exemplo:

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

O nome do parâmetro é mongo-password, mas na verdade é apenas formatar o nome do recurso com um sufixo -password. Para obter mais informações, consulte Armazenamento seguro de segredos do aplicativo em desenvolvimento em ASP.NET Core e Adicione MongoDB recurso de servidor com parâmetros.

O método WithReference configura uma conexão no ExampleProject chamado mongodb e o WaitFor instrui o host do aplicativo a não iniciar o serviço dependente até que o recurso de mongodb esteja pronto.

Dica

Se você preferir se conectar a um servidor MongoDB existente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Referenciar recursos existentes.

Adicionar MongoDB recurso de servidor com volume de dados

Para adicionar um volume de dados ao recurso de servidor MongoDB, chame o método WithDataVolume no recurso de servidor 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...

O volume de dados é usado para persistir os dados do servidor MongoDB fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /data/db no contêiner do servidor MongoDB e, quando um parâmetro name não é fornecido, o nome é gerado aleatoriamente. Para obter mais informações sobre volumes de dados e detalhes sobre por que eles são preferidos em vez de montagens de vinculadores, consulte a Docker documentação: Volumes.

Aviso

A senha é armazenada no volume de dados. Ao usar um volume de dados e se a senha for alterada, ela não funcionará até que você exclua o volume.

Adicionar recurso de servidor MongoDB com montagem de dados com vinculação

Para adicionar uma montagem de associação de dados ao recurso de servidor MongoDB, chame o 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

Os de dados associam montagens têm funcionalidade limitada em comparação com volumes, que oferecem melhor desempenho, portabilidade e segurança, tornando-os mais adequados para ambientes de produção. No entanto, os bind mounts permitem acesso direto e modificação de arquivos no sistema host, ideal para desenvolvimento e testes em que as alterações em tempo real são necessárias.

As montagens de associação de dados dependem do sistema de arquivos do computador host para manter os dados do servidor MongoDB em reinicializações de contêiner. O ponto de montagem de dados está montado no C:\MongoDB\Data no caminho do Windows (ou /MongoDB/Data no Unix) no contêiner de servidor da máquina host MongoDB. Para obter mais informações sobre montagens bind de dados, consulte a documentação Docker: Bind mounts.

Adicionar o recurso de servidor MongoDB com montagem bind de dados de inicialização

Para adicionar uma montagem de associação de dados de pasta de inicialização ao recurso de servidor MongoDB, chame o 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...

A montagem de associação de dados de inicialização é usada para inicializar o servidor MongoDB com dados. A montagem de bind mount dos dados de inicialização é realizada no caminho C:\MongoDB\Init no Windows (ou /MongoDB/Init no Unix) na máquina host dentro do contêiner do servidor MongoDB e mapeia para o caminho /docker-entrypoint-initdb.d no contêiner do servidor MongoDB. MongoDB executa os scripts encontrados nessa pasta, o que é útil para carregar dados no banco de dados.

Adicionar MongoDB recurso de servidor com parâmetros

Quando quiser fornecer explicitamente a senha usada pela imagem de contêiner, você pode fornecer essas credenciais como parâmetros. Considere o seguinte exemplo 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 obter mais informações sobre como fornecer parâmetros, consulte Parâmetros externos.

Adicionar recurso Expresso MongoDB

MongoDB Express é uma interface do usuário MongoDB administrador baseada na Web. Para adicionar um recurso MongoDB Express que corresponda à imagem de contêiner docker.io/library/mongo-express, chame o método WithMongoExpress no recurso do servidor 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...

Dica

Para configurar a porta host para a cadeia MongoExpressContainerResource, faça uma chamada à API de WithHostPort e forneça o número de porta desejado.

O código anterior adiciona um recurso MongoDB Express configurado para se conectar ao recurso de servidor MongoDB. As credenciais padrão são:

  • ME_CONFIG_MONGODB_SERVER: o nome atribuído ao MongoDBServerResourcepai e, nesse caso, seria mongo.
  • ME_CONFIG_BASICAUTH: um valor de false.
  • ME_CONFIG_MONGODB_PORT: Atribuído à porta de destino do ponto de extremidade primário do pai MongoDBServerResource.
  • ME_CONFIG_MONGODB_ADMINUSERNAME: o mesmo nome de usuário configurado no pai MongoDBServerResource.
  • ME_CONFIG_MONGODB_ADMINPASSWORD: a mesma senha configurada no pai MongoDBServerResource.

Além disso, a API WithMongoExpress expõe um parâmetro configureContainer opcional do tipo Action<IResourceBuilder<MongoExpressContainerResource>> que você usa para configurar o recurso de contêiner do MongoDB Express.

Verificações de integridade de integração de hospedagem

A integração de hospedagem MongoDB adiciona automaticamente uma verificação de integridade para o recurso de servidor MongoDB. A verificação de integridade verifica se o recurso de servidor MongoDB está em execução e se uma conexão pode ser estabelecida com ele.

A integração de hospedagem depende do pacote NuGet 📦 AspNetCore.HealthChecks.MongoDb.

integração Client

Para começar a usar a integração do cliente .NET AspireMongoDB, instale o pacote NuGet do driver 📦AspireMongoDB no projeto que consome o cliente, ou seja, o projeto do aplicativo que usa o cliente MongoDB. A integração do cliente MongoDB registra uma instância IMongoClient que você pode usar para interagir com o recurso de servidor MongoDB. Se o host do aplicativo adicionar os recursos de banco de dados MongoDB, a instância IMongoDatabase também será registrada.

dotnet add package Aspire.MongoDB.Driver

Adicionar MongoDB cliente

No arquivo Program.cs do projeto que consome o cliente, chame o método de extensão AddMongoDBClient em qualquer IHostApplicationBuilder para registrar um IMongoClient para uso por meio do contêiner de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddMongoDBClient(connectionName: "mongodb");

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso de servidor MongoDB (ou o recurso de banco de dados quando fornecido) no projeto de host do aplicativo. Em outras palavras, quando você chama AddDatabase e fornece um nome de mongodb esse mesmo nome deve ser usado ao chamar AddMongoDBClient. Para obter mais informações, consulte Adicionar recurso de servidor e recurso de banco de dados MongoDB.

Em seguida, você pode recuperar a instância IMongoClient usando injeção de dependência. Por exemplo, para recuperar o cliente de um serviço de exemplo:

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

O IMongoClient é usado para interagir com o recurso de servidor MongoDB. Ele pode ser usado para criar bancos de dados que ainda não são conhecidos pelo projeto de host do aplicativo. Ao definir um recurso de banco de dados MongoDB no host do aplicativo, você pode exigir que o contêiner de injeção de dependência forneça uma instância IMongoDatabase. Para obter mais informações sobre injeção de dependência, consulte .NET injeção de dependência.

Adicionar cliente chaveado MongoDB

Pode haver situações em que você deseja registrar várias instâncias de IMongoDatabase com nomes de conexão diferentes. Para registrar clientes chaveados MongoDB, chame o método AddKeyedMongoDBClient:

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

Importante

Ao usar serviços com chave, espera-se que seu recurso de MongoDB configure dois bancos de dados nomeados, um para o mainDb e outro para o loggingDb.

Em seguida, você pode recuperar as instâncias de IMongoDatabase usando a injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

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

Para obter mais informações sobre serviços chaveados, consulte .NET injeção de dependência: serviços chaveados.

Configuração

A integração de banco de dados .NET AspireMongoDB fornece várias abordagens de configuração e opções para atender aos requisitos e convenções do seu projeto.

Usar uma string de conexão

Ao usar uma cadeia de conexão da seção de configuração ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar builder.AddMongoDBClient():

builder.AddMongoDBClient("mongo");

A cadeia de conexão é recuperada da seção de configuração ConnectionStrings. Considere a seguinte configuração do exemplo MongoDBJSON:

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

Como alternativa, considere a seguinte configuração de exemplo MongoDB Atlas JSON:

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

Para obter mais informações sobre como formatar essa cadeia de conexão, consulte MongoDB: documentação do ConnectionString.

Usar provedores de configuração

A integração .NET AspireMongoDB dá suporte a Microsoft.Extensions.Configuration. Ele carrega a MongoDBSettings da configuração usando a chave Aspire:MongoDB:Driver. O snippet a seguir é um exemplo de um arquivo de appsettings.json que configura algumas das opções:

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

Usar configurações embutidas

Você também pode passar o delegado Action<MongoDBSettings> para configurar algumas ou todas as opções em linha:

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

Opções de configuração

Aqui estão as opções configuráveis com valores padrão correspondentes:

Nome Descrição
ConnectionString A cadeia de conexão do banco de dados MongoDB ao qual se conectar.
DisableHealthChecks Um valor booliano que indica se a verificação de integridade do banco de dados está desabilitada ou não.
HealthCheckTimeout Um valor int? que indica o tempo limite de verificação de integridade MongoDB em milissegundos.
DisableTracing Um valor booliano que indica se o rastreamento de OpenTelemetry está desabilitado ou não.

Client checagens de saúde de integração

Por padrão, .NET.NET Aspireintegrações de cliente têm verificações de integridade habilitadas para todos os serviços. Da mesma forma, muitas integrações de hospedagem .NET.NET Aspire também habilitam endpoints para verificação de saúde. Para obter mais informações, consulte:

Por padrão, a integração do cliente .NET AspireMongoDB lida com os seguintes cenários:

  • Adiciona uma verificação de integridade, quando habilitada, que verifica se uma conexão pode ser feita e comandos podem ser executados no banco de dados MongoDB dentro de um determinado período de tempo.
  • Integra-se ao endpoint HTTP /health, que especifica que todas as verificações de integridade registradas devem ser aprovadas para que o aplicativo esteja pronto para aceitar tráfego.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente configurações de Log, Rastreamento e Métricas, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.

Registro

A integração de banco de dados .NET AspireMongoDB usa o log de .NET padrão e você vê entradas de log das seguintes categorias:

  • MongoDB[.*]: todas as entradas de log do namespace MongoDB.

Rastreamento

A integração de banco de dados .NET AspireMongoDB emite as seguintes atividades de rastreamento usando OpenTelemetry:

  • MongoDB.Driver.Core.Extensions.DiagnosticSources

Métricas

No momento, a integração do banco de dados .NET AspireMongoDB não expõe nenhuma métrica OpenTelemetry.

Consulte também