Condividi tramite

integrazione del database .NET AspireMongoDB

  • Articolo

include:integrazione dell'hosting e Client integrazione

MongoDB è un database NoSQL che offre prestazioni elevate, disponibilità elevata e scalabilità semplificata. L'integrazione .NET AspireMongoDB consente di connettersi alle istanze esistenti di MongoDB (incluso MongoDB Atlas) oppure di creare nuove istanze da .NET utilizzando l'immagine del contenitore docker.io/library/mongo.

Integrazione dell'hosting

Il server MongoDB che ospita l'integrazione modella il server come tipo di MongoDBServerResource e il database come tipo di MongoDBDatabaseResource. Per accedere a questi tipi e API, aggiungere il pacchetto NuGet 📦Aspire.Hosting.MongoDB nel progetto host dell'app.

dotnet add package Aspire.Hosting.MongoDB

Per ulteriori informazioni, vedere dotnet add package o Gestire le dipendenze dei pacchetti nelle applicazioni .NET.

Aggiungere MongoDB risorsa server e risorsa di database

Nel progetto host dell'app chiamare AddMongoDB per aggiungere e restituire un generatore di risorse server MongoDB. Concatenare una chiamata al generatore di risorse restituito per AddDatabase, per aggiungere una risorsa di database 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

L'avvio del contenitore MongoDB può essere lento, quindi è consigliabile usare una durata permanente per evitare riavvii non necessari. Per altre informazioni, vedere durata della risorsa del contenitore.

Quando .NET.NET Aspire aggiunge un'immagine del contenitore all'host dell'app, come illustrato nell'esempio precedente con l'immagine docker.io/library/mongo, crea una nuova istanza MongoDB nel computer locale. Per aggiungere un database viene usato un riferimento al generatore di risorse del server MongoDB (la variabile mongo). Il database viene denominato mongodb e quindi aggiunto al ExampleProject. La risorsa server MongoDB include le credenziali predefinite:

  • MONGO_INITDB_ROOT_USERNAME: valore di admin.
  • MONGO_INITDB_ROOT_PASSWORD: password generati casualmente usando il metodo CreateDefaultPasswordParameter.

Quando viene eseguito l'host dell'app, la password viene archiviata nell'archivio dei segreti dell'host dell'app. Viene aggiunto alla sezione Parameters, ad esempio:

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

Il nome del parametro è mongo-password, ma in realtà è sufficiente formattare il nome della risorsa con un suffisso -password. Per altre informazioni, vedere Archiviazione sicura dei segreti dell'app in fase di sviluppo in ASP.NET Core e Aggiungere una risorsa server MongoDB con parametri.

Il metodo WithReference imposta una connessione nella ExampleProject denominata mongodb e il WaitFor indica al server dell'app di non avviare il servizio dipendente fino a che la risorsa mongodb non sia pronta.

Consiglio

Se preferisci connetterti a un server MongoDB esistente, chiama AddConnectionString. Per altre informazioni, vedere Fare riferimento alle risorse esistenti.

Aggiungere MongoDB risorsa server con volume di dati

Per aggiungere un volume di dati alla risorsa server MongoDB, chiamare il metodo WithDataVolume nella risorsa server 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...

Il volume di dati viene usato per rendere persistenti i dati del server MongoDB al di fuori del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /data/db nel contenitore del server MongoDB e quando non viene specificato un parametro name, il nome viene generato in modo casuale. Per altre informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto a associare i montaggi, vedere la documentazione Docker: Volumi.

Avvertimento

La password viene archiviata nel volume di dati. Quando si usa un volume di dati e se la password viene modificata, non funzionerà fino a quando non si elimina il volume.

Aggiungi la risorsa server MongoDB con il bind mount dei dati

Per aggiungere un bind mount di dati alla risorsa server MongoDB, utilizzare il metodo 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

I montaggi di bind dei dati hanno funzionalità limitate rispetto ai volumi , che offrono prestazioni, portabilità e sicurezza migliori, rendendoli più adatti per gli ambienti di produzione. Tuttavia, i bind mount consentono l'accesso diretto e la modifica dei file nel sistema host, ideale per lo sviluppo e il test in cui sono richieste modifiche in tempo reale.

I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati del server MongoDB tra i riavvii del contenitore. Il bind mount dei dati è montato sul percorso C:\MongoDB\Data su Windows (o /MongoDB/Data su Unix) sul computer host nel contenitore server MongoDB. Per altre informazioni sui montaggi di associazione dati, vedere Docker docs: Bind mounts.

Aggiungere la risorsa del server MongoDB con il mount di binding per i dati di inizializzazione.

Per aggiungere un montaggio di associazione dati della cartella di inizializzazione alla risorsa server MongoDB, chiamare il metodo 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...

Il mount di associazione dati di inizializzazione viene montato per inizializzare il server MongoDB con i dati. Il montaggio dell'associazione dati di inizializzazione è montato al percorso C:\MongoDB\Init su Windows (o /MongoDB/Init su Unix) sul computer host nel contenitore del server MongoDB e si mappa al percorso /docker-entrypoint-initdb.d nel contenitore del server MongoDB. MongoDB esegue gli script presenti in questa cartella, utile per caricare i dati nel database.

Aggiungere MongoDB risorsa server con parametri

Quando si vuole specificare in modo esplicito la password usata dall'immagine del contenitore, è possibile specificare queste credenziali come parametri. Si consideri l'esempio alternativo seguente:

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

Per altre informazioni sulla fornitura di parametri, vedere Parametri esterni.

Aggiungere la risorsa MongoDB Express

MongoDB Express è un'interfaccia utente amministratore MongoDB basata sul Web. Per aggiungere una risorsa MongoDB Express corrispondente all'immagine del contenitore docker.io/library/mongo-express, chiamare il metodo WithMongoExpress nella risorsa server 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...

Consiglio

Per configurare la porta host per la catena MongoExpressContainerResource è necessario effettuare una chiamata all'API WithHostPort e specificare il numero di porta desiderato.

Il codice precedente aggiunge una risorsa MongoDB Express configurata per la connessione alla risorsa server MongoDB. Le credenziali predefinite sono:

  • ME_CONFIG_MONGODB_SERVER: Il nome assegnato al genitore MongoDBServerResource, in questo caso sarebbe mongo.
  • ME_CONFIG_BASICAUTH: valore di false.
  • ME_CONFIG_MONGODB_PORT: assegnato dalla porta di destinazione dell'endpoint primario del padre MongoDBServerResource.
  • ME_CONFIG_MONGODB_ADMINUSERNAME: lo stesso nome utente configurato nel MongoDBServerResourceprincipale.
  • ME_CONFIG_MONGODB_ADMINPASSWORD: la stessa password come configurata nel MongoDBServerResourcepadre.

Inoltre, l'API WithMongoExpress espone un parametro facoltativo di tipo configureContainer di tipo Action<IResourceBuilder<MongoExpressContainerResource>> usato per configurare la risorsa contenitore MongoDB Express.

Hosting dei controlli di integrità dell'integrazione

L'integrazione dell'hosting MongoDB aggiunge automaticamente un controllo di integrità per la risorsa server MongoDB. Il controllo integrità verifica che la risorsa del server MongoDB sia in esecuzione e che sia possibile stabilire una connessione.

L'integrazione dell'hosting si basa sul pacchetto NuGet 📦 AspNetCore.HealthChecks.MongoDb.

integrazione Client

Per iniziare a utilizzare l'integrazione client .NET AspireMongoDB, installare il pacchetto NuGet 📦Aspire.MongoDB.Driver nel progetto client-consumatore, cioè il progetto per l'applicazione che utilizza il client MongoDB. L'integrazione client MongoDB registra un'istanza di IMongoClient che è possibile usare per interagire con la risorsa server MongoDB. Se l'host dell'app aggiunge risorse di database MongoDB, viene registrata anche l'istanza di IMongoDatabase.

dotnet add package Aspire.MongoDB.Driver

Aggiungere MongoDB client

Nel file Program.cs del progetto cliente, chiamate il metodo di estensione AddMongoDBClient su qualsiasi IHostApplicationBuilder per registrare un IMongoClient da usare tramite il container per l'inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddMongoDBClient(connectionName: "mongodb");

Consiglio

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa server MongoDB (o la risorsa di database, se specificata) nel progetto host dell'app. In altre parole, quando si chiama AddDatabase e si specifica un nome di mongodb lo stesso nome deve essere usato quando si chiama AddMongoDBClient. Per altre informazioni, vedere Aggiungere MongoDB risorsa server e risorsa del database.

È quindi possibile recuperare l'istanza di IMongoClient usando l'iniezione delle dipendenze. Ad esempio, per recuperare il client da un servizio di esempio:

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

Il IMongoClient viene usato per interagire con la risorsa server MongoDB. Può essere usato per creare database che non sono già noti al progetto host dell'app. Quando si definisce una risorsa di database MongoDB nell'host dell'app, è invece possibile richiedere che il contenitore per l'iniezione delle dipendenze fornisca un'istanza IMongoDatabase. Per ulteriori informazioni su dependency injection, vedere .NET dependency injection.

Aggiungere il client MongoDB con chiave

In alcuni casi potrebbe essere necessario registrare più istanze di IMongoDatabase con nomi di connessione diversi. Per registrare i client MongoDB con chiave, chiamare il metodo AddKeyedMongoDBClient:

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

Importante

Quando si usano i servizi con chiave, è previsto che la risorsa MongoDB sia configurata con due database denominati, uno per il mainDb e uno per l'loggingDb.

È quindi possibile recuperare le istanze di IMongoDatabase tramite iniezione delle dipendenze. Ad esempio, per recuperare la connessione da un servizio di esempio:

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

Per ulteriori informazioni sui servizi con chiave, vedere .NET Inserimento delle Dipendenze: Servizi con Chiave.

Configurazione

L'integrazione del database .NET AspireMongoDB offre più approcci di configurazione e opzioni per soddisfare i requisiti e le convenzioni del progetto.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla sezione di configurazione ConnectionStrings, è possibile specificare il nome della stringa di connessione quando si chiama builder.AddMongoDBClient():

builder.AddMongoDBClient("mongo");

La stringa di connessione viene recuperata dalla sezione di configurazione ConnectionStrings. Si consideri la configurazione di esempio MongoDB seguente JSON.

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

In alternativa, considerare la seguente configurazione dell'esempio Atlas MongoDBJSON.

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

Per altre informazioni su come formattare questa stringa di connessione, vedere MongoDB: documentazione di ConnectionString.

Usare i provider di configurazione

L'integrazione .NET AspireMongoDB supporta Microsoft.Extensions.Configuration. Carica il MongoDBSettings dalla configurazione usando la chiave Aspire:MongoDB:Driver. Il frammento di codice seguente è un esempio di un file appsettings.json che configura alcune delle opzioni:

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

Usare configurazioni inline

È anche possibile passare il delegato Action<MongoDBSettings> per configurare alcune o tutte le opzioni in linea.

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

Opzioni di configurazione

Ecco le opzioni configurabili con i valori predefiniti corrispondenti:

Nome Descrizione
ConnectionString Stringa di connessione del database di MongoDB a cui connettersi.
DisableHealthChecks Valore booleano che indica se il controllo integrità del database è disabilitato o meno.
HealthCheckTimeout Un valore int? che indica il timeout del controllo dello stato di salute MongoDB in millisecondi.
DisableTracing Valore booleano che indica se la traccia OpenTelemetry è disabilitata o meno.

Client verifiche di integrità dell'integrazione

Per impostazione predefinita, le integrazioni client .NET.NET Aspire hanno i controlli di integrità abilitati per tutti i servizi. Analogamente, molte integrazioni di hosting .NET.NET Aspire abilitano anche gli endpoint di controllo dell'integrità. Per altre informazioni, vedere:

Per impostazione predefinita, l'integrazione client .NET AspireMongoDB gestisce gli scenari seguenti:

  • Aggiunge un controllo di integrità quando abilitato, che verifica che sia possibile stabilire una connessione e eseguire comandi sul database MongoDB entro un determinato periodo di tempo.
  • Si integra con l'endpoint HTTP /health, che specifica che tutti i controlli di integrità registrati devono essere superati affinché l'app sia considerata pronta ad accettare il traffico.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente configurazioni di registrazione, traccia e metriche, talvolta note come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione del database .NET AspireMongoDB utilizza il logging standard .NET e vengono visualizzate le voci di registro delle seguenti categorie:

  • MongoDB[.*]: tutte le voci di log dello spazio dei nomi MongoDB.

Tracciatura

L'integrazione del database .NET AspireMongoDB genera le attività di traccia seguenti usando OpenTelemetry:

  • MongoDB.Driver.Core.Extensions.DiagnosticSources

Metriche

L'integrazione del database .NET AspireMongoDB attualmente non espone alcuna metrica OpenTelemetry.

Vedere anche