integrazione del database .NET AspireMongoDB

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

I modelli di integrazione di hosting MongoDBserver modellano 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

<PackageReference Include="Aspire.Hosting.MongoDB"
                  Version="*" />

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

Aggiungere la risorsa MongoDBeserver e la risorsa di database

Nel progetto host dell'app, utilizza AddMongoDB per aggiungere e restituire un generatore di risorse MongoDBserver. 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...

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 MongoDBserver (la variabile mongo). Il database viene denominato mongodb e quindi aggiunto al ExampleProject. La risorsa MongoDBserver 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 MongoDBserver 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.

Aggiungi la risorsa MongoDBserver con volume di dati

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

Il volume di dati viene usato per rendere persistenti i dati MongoDBserver al di fuori del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /data/db nel contenitore MongoDBserver 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.

Aggiungere la risorsa MongoDBserver con il mount di associazione dati

Per aggiungere un punto di montaggio per l'associazione dei dati alla risorsa MongoDBserver, chiamare 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...

I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati MongoDBserver tra i riavvii del contenitore. Il montaggio dell'associazione dati viene montato nel C:\MongoDB\Data in Windows (o /MongoDB/Data in Unix) percorso del computer host nel contenitore MongoDBserver. Per altre informazioni sui montaggi di associazione dati, vedere Docker docs: Bind mounts.

Aggiungere MongoDBserver risorsa con il montaggio dell'associazione dati di inizializzazione

Per aggiungere un montaggio di associazione dati della cartella di inizializzazione alla risorsa MongoDBserver, 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 montaggio bind dei dati di inizializzazione viene utilizzato per inizializzare il MongoDBserver con dati. Il montaggio dell'associazione dati di inizializzazione viene montato nel percorso di C:\MongoDB\Init in Windows (o /MongoDB/Init su Unix) nel computer host nel contenitore MongoDBserver ed esegue il mapping al percorso /docker-entrypoint-initdb.d nel contenitore MongoDBserver. MongoDB esegue gli script presenti in questa cartella, utile per caricare i dati nel database.

Aggiungere MongoDBserver risorsa 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 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...

Il codice precedente aggiunge una risorsa MongoDB Express configurata per la connessione alla risorsa MongoDBserver. 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 una verifica dell'integrità per la risorsa MongoDBserver. Il controllo di integrità verifica che la risorsa MongoDBserver sia in esecuzione e che sia possibile stabilire una connessione ad essa.

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

integrazione Client

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

dotnet add package Aspire.MongoDB.Driver

<PackageReference Include="Aspire.MongoDB.Driver"
                  Version="*" />

Aggiungere MongoDBclient

Nel file Program.cs del progetto client, chiama il metodo di estensione AddMongoDBClient su qualsiasi IHostApplicationBuilder per registrare un IMongoClient da utilizzare tramite il contenitore di iniezione delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddMongoDBClient(connectionName: "mongodb");

È 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 MongoDBserver. 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 MongoDBclient 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");

È 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:

Controlli della salute

Per impostazione predefinita, le integrazioni di .NET.NET Aspire abilitano controlli di integrità per tutti i servizi. Per altre informazioni, vedere panoramica delle integrazioni .NET.NET Aspire.

Per impostazione predefinita, l'integrazione .NET AspireMongoDBclient 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

• MongoDB database
• .NET .NET Aspire integrazioni
• .NET Aspire GitHub repo