Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Inclui: Integração de hospedagem —&—
Client 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.
- .NET CLI
- PackageReference
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 deadmin
. -
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
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
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 paiMongoDBServerResource
, neste caso seriamongo
. -
ME_CONFIG_BASICAUTH
: Um valor defalse
. -
ME_CONFIG_MONGODB_PORT
: Atribuído à porta de destino do ponto final primário do paiMongoDBServerResource
. -
ME_CONFIG_MONGODB_ADMINUSERNAME
: O mesmo nome de utilizador que está configurado noMongoDBServerResource
pai. -
ME_CONFIG_MONGODB_ADMINPASSWORD
: A mesma senha configurada noMongoDBServerResource
.
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
- .NET CLI
- PackageReference
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.