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

Integração de hospedagem MongoDBserver modela o server como tipo MongoDBServerResource e o banco de dados como 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 MongoDBserver e recurso de banco de dados

No projeto de host do aplicativo, chame AddMongoDB para adicionar e retornar um construtor de recursos MongoDBserver. 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 MongoDBserver (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 MongoDBserver 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 no desenvolvimento em ASP.NET Core e Adicionar MongoDBserver recurso 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 MongoDBserverexistente, chame AddConnectionString em vez disso. Para obter mais informações, consulte Referenciar recursos existentes.

Adicionar os recursos MongoDBeserver com volume de dados

Para adicionar um volume de dados ao recurso MongoDBserver, chame o método WithDataVolume no recurso MongoDBserver:

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 MongoDBserver fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /data/db no contêiner MongoDBserver 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 o recurso MongoDBserver com montagem de vinculação de dados

Para adicionar uma montagem de associação de dados ao recurso MongoDBserver, 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 persistir os dados MongoDBserver entre reinicializações de contêiner. A montagem de ligação de dados está montada no caminho C:\MongoDB\Data no Windows (ou /MongoDB/Data no Unix) na máquina host no contêiner MongoDBserver. Para obter mais informações sobre montagens bind de dados, consulte a documentação Docker: Bind mounts.

Adicionar recurso MongoDBserver com montagem de bind de dados de inicialização

Para adicionar uma montagem de associação de dados de pasta de inicialização ao recurso MongoDBserver, 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 MongoDBserver com dados. A montagem de associação de dados de inicialização é montada no caminho C:\MongoDB\Init no Windows (ou /MongoDB/Init no Unix) no computador host no contêiner MongoDBserver e mapeia para o caminho /docker-entrypoint-initdb.d no contêiner MongoDBserver. MongoDB executa os scripts encontrados nessa pasta, o que é útil para carregar dados no banco de dados.

Adicionar MongoDBserver recurso 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 MongoDBserver:

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 MongoDBserver. 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 MongoDBserver. A verificação de integridade verifica se o recurso MongoDBserver está em execução e se uma conexão pode ser estabelecida com ele.

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

integração Client

Para começar a usar a integração .NET AspireMongoDBclient, instale o 📦Aspire.MongoDB. O driver pacote NuGet no projeto de consumo de client, ou seja, o projeto do aplicativo que usa o MongoDBclient. A integração MongoDBclient registra uma instância IMongoClient que você pode usar para interagir com o recurso MongoDBserver. 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 MongoDBclient

No arquivo Program.cs do projeto que consome client, chame o método de extensão AddMongoDBClient em qualquer IHostApplicationBuilder, para assim registrar um IMongoClient para uso através 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 MongoDBserver (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 MongoDBrecursoserver e recurso de banco de dados.

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

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

O IMongoClient é usado para interagir com o recurso MongoDBserver. 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 chave MongoDBclient

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.

Verificações de saúde

Por padrão, as integrações .NET.NET Aspire habilitam verificações de integridade para todos os serviços. Para obter mais informações, consulte .NET.NET Aspire visão geral de integrações.

Por padrão, a integração .NET AspireMongoDBclient 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