Partilhar via


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

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

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

Integração de hospedagem

A integração de hospedagem MongoDBserver modela o server 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 de host do aplicativo .

dotnet add package Aspire.Hosting.MongoDB

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

Adicionar o recurso MongoDB, o recursoserver e o recurso de banco de dados

Em seu projeto de host de aplicativo, chame AddMongoDB para adicionar e retornar um MongoDBserver construtor de recursos. 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 contêiner MongoDB pode ser lento para iniciar, por isso é melhor usar um ciclo de vida persistente para evitar reinicializações desnecessárias. Para obter mais informações, consulte Tempo de vida do recurso de 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 seu MongoDBserver construtor de recursos (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 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 no 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 mongodb esteja pronto.

Dica

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

Adicionar recurso MongoDBserver 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 manter os MongoDBserver dados 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 relação a montagens bind , consulte a documentação Docker: Volumes.

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.

Adicionar recurso MongoDBserver com montagem de ligação de dados

Para adicionar uma montagem de ligaçã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 suportes de ligação de de dados 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, 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 associação de dados dependem do sistema de arquivos da máquina host para manter os dados MongoDBserver nas reinicializações do contêiner. A montagem da associação de dados é 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 de associação de dados, consulte Docker docs: Bind mounts.

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

Para adicionar uma montagem de vínculo de dados do diretório 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 dados de inicialização é efetuada no caminho C:\MongoDB\Init no Windows (ou /MongoDB/Init no Unix) na máquina host no contentor MongoDBserver e é mapeada para o caminho /docker-entrypoint-initdb.d no contentor MongoDBserver. MongoDB executa os scripts encontrados nesta 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 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 de MongoDB baseada na Web. Para adicionar um recurso do 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 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 MongoDB Express configurado para se conectar ao recurso MongoDBserver. 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 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 📦 AspNetCore.HealthChecks.MongoDb pacote NuGet.

Client integração

Para começar com a integração .NET AspireMongoDBclient, instale o pacote NuGet 📦Aspire.MongoDB.Driver no projeto que consome client, ou seja, o projeto para a aplicação que usa o MongoDBclient. A integração registra uma instância de IMongoClient que você pode usar para interagir com o recurso . Se o host da aplicação adicionar recursos de base de dados MongoDB, a instância IMongoDatabase também será registada.

dotnet add package Aspire.MongoDB.Driver

Adicionar MongoDBclient

No arquivo Program.cs do seu projeto que consome client, chamar o método de extensão AddMongoDBClient em qualquer IHostApplicationBuilder para registar um IMongoClient para uso através do container 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 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 o recurso MongoDBserver e o 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 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 a injeção de dependência, consulte .NET injeção de dependência.

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

Controlos sanitários

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 das integrações.

Por padrão, a integração .NET AspireMongoDBclient 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 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 Visão geral de integrações .NET.NET Aspire. 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. Os recursos de telemetria também podem ser desativados usando as técnicas apresentadas na seção 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