Partilhar via

.NET Aspire MongoDB integração de banco de dados

Inclui:Integração de hospedagem incluída Integração de hospedagem —&— Client integração incluídaClient integração

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

Integração de hospedagem

O servidor MongoDB que hospeda a integração modela o servidor como o tipo MongoDBServerResource e o banco de dados como o tipo MongoDBDatabaseResource. Para aceder a estes tipos e APIs, adicione o 📦Aspire.Hosting.MongoDB pacote NuGet no projeto do host da aplicação.

dotnet add package Aspire.Hosting.MongoDB

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

Adicionar MongoDB recurso de servidor e recurso de banco de dados

No seu projeto de alojamento de aplicação, chame AddMongoDB para adicionar e retornar um construtor de recursos de servidor MongoDB. Encadeie uma chamada para o construtor de recursos retornado para AddDatabase, para 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...

Observação

O MongoDB contêiner pode ser lento para iniciar, por isso é mais indicado usar um tempo de vida útil persistente para evitar reinicializações desnecessárias. Para obter mais informações, consulte Tempo de vida do recurso do contêiner.

Quando .NET.NET Aspire adiciona uma imagem de contêiner ao host do aplicativo, como mostrado no exemplo anterior com a imagem docker.io/library/mongo, ele cria uma nova instância de MongoDB em sua máquina 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 da aplicação é executado, a senha é armazenada no repositório secreto do host da aplicação. 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 de aplicativos em desenvolvimento ASP.NET Core e Adicionar 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 mongodb esteja pronto.

Dica

Se você preferir se conectar a um servidor MongoDB existente, ligue para AddConnectionString em vez disso. Para obter mais informações, consulte Fazer referência a recursos existentes.

Adicionar o recurso do servidor MongoDB com volume de dados

Para adicionar um volume de dados ao recurso do servidor MongoDB, chame o método WithDataVolume no recurso do 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 manter 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 são preferidos em relação às montagens bind, consulte .

Advertência

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.

Importante

Algumas integrações de base de dados, incluindo a integração .NET AspireMongoDB, não conseguem usar com sucesso volumes de dados após a implementação no Azure Container Apps (ACA). Isso ocorre porque o ACA usa Server o Message Block (SMB) para conectar contêineres a volumes de dados e alguns sistemas não podem usar essa conexão. Aspire No Painel, um banco de dados afetado por este problema tem um status de Ativação ou Falha de Ativação, mas nunca é listado como Em execução.

Você pode resolver o problema ao desdobrar para um cluster Kubernetes, como os Serviços AzureKubernetes (AKS). Para obter mais informações, consulte .NET.NET Aspire implementações.

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

Para adicionar uma montagem de ligação de dados ao recurso do 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

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

As montagens de vínculo de dados dependem do sistema de arquivos da máquina host para manter os dados do servidor MongoDB durante reinicializações do contêiner. A montagem de associação de dados é montada no C:\MongoDB\Data no caminho do Windows (ou /MongoDB/Data no Unix) na máquina host no contêiner do servidor MongoDB. Para obter mais informações sobre montagens de associação de dados, consulte Docker documentação: montagens de associação.

Adicionar recurso de servidor MongoDB com montagem do ponto de ligação dos dados de inicialização

Para adicionar uma montagem de associação de dados da pasta de inicialização ao recurso do 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 da ligação de dados de inicialização é feita no caminho C:\MongoDB\Init no Windows, ou no caminho /MongoDB/Init no Unix, na máquina host. No contêiner do servidor MongoDB, este mapeamento é direcionado para o caminho /docker-entrypoint-initdb.d no contêiner do servidor MongoDB. MongoDB executa os scripts encontrados nesta pasta, o que é útil para carregar dados no banco de dados.

Adicionar MongoDB recurso do servidor com parâmetros

Quando quiser fornecer explicitamente a senha usada pela imagem do contêiner, você poderá 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 MongoDB Express

MongoDB Express é uma interface de usuário de administração baseada na MongoDB web. Para adicionar um recurso Express que corresponda à imagem do contentor, chame o método no recurso do servidor:

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 do host para o MongoExpressContainerResource encadeie uma chamada para a API do WithHostPort e forneça o número de porta desejado.

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

  • ME_CONFIG_MONGODB_SERVER: O nome atribuído ao pai MongoDBServerResource, neste caso seria mongo.
  • ME_CONFIG_BASICAUTH: Um valor de false.
  • ME_CONFIG_MONGODB_PORT: Atribuído à porta de destino do ponto final primário do pai MongoDBServerResource.
  • ME_CONFIG_MONGODB_ADMINUSERNAME: O mesmo nome de utilizador que está configurado no MongoDBServerResourcepai.
  • ME_CONFIG_MONGODB_ADMINPASSWORD: A mesma senha configurada no 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 da 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 do 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 .

Client integração

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

dotnet add package Aspire.MongoDB.Driver

Importante

O pacote NuGet Aspire.MongoDB.Driver depende do pacote NuGet MongoDB.Driver. Com o lançamento da versão 3.0.0 de MongoDB.Driver, foi introduzida uma alteração que quebra a compatibilidade binária. Para resolver isso, um novo pacote de integração de cliente, Aspire.MongoDB.Driver.v3, foi criado. O pacote original Aspire.MongoDB.Driver continua a fazer referência MongoDB.Driver à versão 2.30.0, garantindo a compatibilidade com versões anteriores da integração de cliente RabbitMQ. O novo Aspire.MongoDB.Driver.v3 pacote faz referência à MongoDB.Driver versão 3.0.0. Em uma versão futura do .NET.NET Aspire, o Aspire.MongoDB.Driver será atualizado para a versão 3.x e o pacote Aspire.MongoDB.Driver.v3 será preterido. Para obter mais informações, consulte Atualizar para a versão 3.0.

Adicionar MongoDB cliente

No arquivo de Program.cs do seu projeto cliente-consumidor, chame o método de extensão AddMongoDBClient em qualquer IHostApplicationBuilder para 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 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 MongoDB recurso de servidor e recurso de banco de dados.

Em seguida, você pode recuperar a instância IMongoClient usando a 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 MongoDB com chave

Pode haver situações em que você queira registrar várias instâncias de IMongoDatabase com nomes de conexão diferentes. Para registrar clientes MongoDB chaveados, 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 MongoDB configure dois bancos de dados nomeados, um para o mainDb e outro para o loggingDb.

Depois, podes recuperar as instâncias IMongoDatabase usando 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 com chave, consulte .NET injeção de dependência: serviços com chave.

Configuração

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

Usar uma cadeia de conexão

Ao usar uma cadeia de conexão da seção de configuração de 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 de exemplo MongoDBJSON:

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

Como alternativa, considere a seguinte configuração do 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 de ConnectionString.

Usar provedores de configuração

A integração .NET AspireMongoDB suporta Microsoft.Extensions.Configuration. Ele carrega o MongoDBSettings da configuração utilizando a chave Aspire:MongoDB:Driver. O trecho 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 Action<MongoDBSettings> delegado para configurar algumas ou todas as opções embutidas:

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 os valores padrão correspondentes:

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

Client verificações de saúde de integração

Por padrão, .NET.NET Aspireas integraçõ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 pontos de extremidade de verificação de integridade. Para 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 ativada, que assegura que uma conexão pode ser estabelecida e que comandos podem ser executados no banco de dados MongoDB dentro de um determinado período de tempo.
  • Integra-se com o endpoint HTTP /health, que especifica que todas as verificações de integridade registadas devem ser aprovadas para que a aplicação seja considerada pronta a aceitar tráfego.

Observabilidade e telemetria

.NET .NET Aspire As integrações configuram automaticamente as configurações de Logging, Trace e Metrics, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte .NET.NET Aspire Visão geral de integrações. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. As funcionalidades de telemetria também podem ser desativadas usando as técnicas apresentadas na secção de configuração .

Registo

A integração da base de dados .NET AspireMongoDB utiliza o registo padrão de .NET e você vê entradas de registo das seguintes categorias:

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

Rastreio

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

  • MongoDB.Driver.Core.Extensions.DiagnosticSources

Métricas

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

Ver também