.NET Aspire MongoDB Datenbankintegration

Artikel
12/14/2024

umfasst:Hostingintegration und Client Integration

MongoDB ist eine NoSQL-Datenbank, die hohe Leistung, hohe Verfügbarkeit und einfache Skalierbarkeit bietet. Mit der .NET AspireMongoDB-Integration können Sie eine Verbindung mit vorhandenen MongoDB-Instanzen (einschließlich MongoDB Atlas) herstellen oder neue Instanzen aus .NET mit dem docker.io/library/mongo Container-Image erstellen.

Hosting-Integration

Die MongoDBserver hosten integrationsmodelle die server als MongoDBServerResource Typ und die Datenbank als MongoDBDatabaseResource Typ. Um auf diese Typen und APIs zuzugreifen, fügen Sie das NuGet-Paket 📦Aspire.Hosting.MongoDB im App-Host Projekt hinzu.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.MongoDB

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

Weitere Informationen finden Sie unter dotnet add package oder Verwalten Sie Paketabhängigkeiten in .NET Anwendungen.

Hinzufügen von MongoDBserver Ressourcen- und Datenbankressourcen

Rufen Sie in Ihrem App-Hostprojekt AddMongoDB auf, um einen MongoDBserver Ressourcen-Generator hinzuzufügen und zurückzugeben. Verketten Sie einen Aufruf des zurückgegebenen Ressourcen-Generators an AddDatabase, um eine MongoDB Datenbankressource hinzuzufügen.

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

Anmerkung

Der MongoDB Container kann langsam gestartet werden, daher ist es am besten, eine persistente Lebensdauer zu verwenden, um unnötige Neustarts zu vermeiden. Weitere Informationen finden Sie unter Lebensdauer von Containerressourcen.

Wenn .NET.NET Aspire dem App-Host ein Containerimage hinzufügt, wie im vorherigen Beispiel mit dem docker.io/library/mongo-Image gezeigt, wird eine neue MongoDB Instanz auf dem lokalen Computer erstellt. Ein Verweis auf den MongoDBserver Ressourcen-Generator (die mongo Variable) wird verwendet, um eine Datenbank hinzuzufügen. Die Datenbank wird mongodb benannt und dann dem ExampleProjecthinzugefügt. Die MongoDBserver-Ressource enthält Standardanmeldeinformationen:

MONGO_INITDB_ROOT_USERNAME: Ein Wert von admin.
MONGO_INITDB_ROOT_PASSWORD: Zufällige password mithilfe der CreateDefaultPasswordParameter-Methode generiert.

Wenn der App-Host ausgeführt wird, wird das Kennwort im geheimen Speicher des App-Hosts gespeichert. Sie wird dem Abschnitt Parameters hinzugefügt, z. B.:

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

Der Name des Parameters ist mongo-password, aber eigentlich wird der Ressourcenname nur mit dem Suffix -password formatiert. Weitere Informationen finden Sie unter sicherer Speicherung geheimer App-Schlüssel während der Entwicklung in ASP.NET Core und Hinzufügen einer MongoDBserver Ressource mit den Parametern.

Die Methode WithReference konfiguriert eine Verbindung in der mit dem Namen mongodb ausgestatteten ExampleProject, und die WaitFor weist den Anwendungs-Host an, den abhängigen Dienst erst zu starten, wenn die Ressource mongodb bereit ist.

Trinkgeld

Wenn Sie lieber eine Verbindung mit einem vorhandenen MongoDBserverherstellen möchten, rufen Sie stattdessen AddConnectionString auf. Weitere Informationen finden Sie unter Referenzieren vorhandener Ressourcen.

Fügen Sie MongoDBserver eine Ressource mit Datenvolumen hinzu

Rufen Sie die WithDataVolume-Methode für die MongoDBserver-Ressource auf, um der MongoDBserver Ressource ein Datenvolume hinzuzufügen:

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

Das Datenvolume wird verwendet, um die MongoDBserver Daten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolumen wird im /data/db Pfad im Container MongoDBserver bereitgestellt und wenn kein name Parameter angegeben wird, wird der Name zufällig generiert. Weitere Informationen zu Datenvolumes und Details dazu, warum sie gegenüber Bind-Mountsbevorzugt werden, finden Sie in der Docker-Dokumentation: Volumes.

Warnung

Das Kennwort wird im Datenvolume gespeichert. Wenn Sie ein Datenvolumen verwenden und sich das Kennwort ändert, funktioniert es nicht, bis Sie das Volumen löschen.

Füge Ressource MongoDBserver mit Datenbindemontage hinzu

Rufen Sie die WithDataBindMount-Methode auf, um der MongoDBserver-Ressource einen Daten-Bind-Mount hinzuzufügen:

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

Wichtig

Daten Binden von Bereitstellungen mit eingeschränkter Funktionalität im Vergleich zu Volumes, die eine bessere Leistung, Portabilität und Sicherheit bieten, wodurch sie für Produktionsumgebungen besser geeignet sind. Bind-Mounts ermöglichen jedoch direkten Zugriff und Bearbeitung von Dateien auf dem Hostsystem, ideal für die Entwicklung und Tests, bei denen Echtzeitänderungen erforderlich sind.

Datenbindungs-Bereitstellungen basieren auf dem Dateisystem des Hostcomputers, um die MongoDBserver Daten über Containerneustarts hinweg beizubehalten. Die Datenbindungsmontierung wird auf dem C:\MongoDB\Data unter Windows (oder /MongoDB/Data auf dem Unix) Pfad auf dem Hostcomputer im Container MongoDBserver montiert. Weitere Informationen zu Daten-Bind-Mounts finden Sie unter Docker Dokumentation: Bind-Mounts.

Hinzufügen MongoDBserver Ressource mit Initialisierungsdatenbindungs-Bereitstellung

Rufen Sie die WithInitBindMount-Methode auf, um der MongoDBserver-Ressource eine Initialisierungsordnerdatenbindung hinzuzufügen:

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

Das Einhängen der Initialisierungsdatenbindung wird verwendet, um die MongoDBserver mit Daten zu initialisieren. Das Initialisierungsdaten-Bind-Mount wird auf dem Windows-Pfad C:\MongoDB\Init (oder auf dem /MongoDB/Init auf Unix) auf dem Hostcomputer im Container MongoDBserver bereitgestellt und dem Pfad /docker-entrypoint-initdb.d im MongoDBserver-Container zugeordnet. MongoDB führt die in diesem Ordner gefundenen Skripts aus, was zum Laden von Daten in die Datenbank nützlich ist.

Hinzufügen MongoDBserver Ressource mit Parametern

Wenn Sie das vom Container-Image verwendete Kennwort explizit angeben möchten, können Sie die Zugangsdaten als Parameter übergeben. Betrachten Sie das folgende alternative Beispiel:

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

Weitere Informationen zum Bereitstellen von Parametern finden Sie unter externe Parameter.

Ressource MongoDB Express hinzufügen

MongoDB Express ist eine webbasierte MongoDB Administratorbenutzeroberfläche. Um eine MongoDB Express-Ressource hinzuzufügen, die dem docker.io/library/mongo-express Container-Imageentspricht, rufen Sie die WithMongoExpress-Methode für die MongoDBserver-Ressource auf.

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

Tipp

Führen Sie zur Konfiguration des Hostports für die MongoExpressContainerResource-Kette einen Aufruf an die WithHostPort-API durch und geben Sie die gewünschte Portnummer an.

Der vorangehende Code fügt eine MongoDB Express-Ressource hinzu, die für die Verbindung mit der MongoDBserver-Ressource konfiguriert ist. Die Standardanmeldeinformationen sind:

ME_CONFIG_MONGODB_SERVER: Der Name, der dem übergeordneten MongoDBServerResourcezugewiesen ist, wäre in diesem Fall mongo.
ME_CONFIG_BASICAUTH: Ein Wert von false.
ME_CONFIG_MONGODB_PORT: Vom Zielport des primären Endpunkts des übergeordneten MongoDBServerResourcezugewiesen.
ME_CONFIG_MONGODB_ADMINUSERNAME: Derselbe Benutzername wie im übergeordneten MongoDBServerResourcekonfiguriert.
ME_CONFIG_MONGODB_ADMINPASSWORD: Dasselbe Kennwort, wie es im übergeordneten MongoDBServerResourcekonfiguriert ist.

Darüber hinaus macht die WithMongoExpress-API einen optionalen configureContainer Parameter vom Typ Action<IResourceBuilder<MongoExpressContainerResource>> verfügbar, den Sie zum Konfigurieren der MongoDB Express-Containerressource verwenden.

Hosten von Integritätsprüfungen für Integration

Die MongoDB-Hosting-Integration fügt automatisch eine Integritätsprüfung für die MongoDB-server-Ressource hinzu. Die Gesundheitsprüfung überprüft, ob die MongoDBserver Ressource ausgeführt wird und ob eine Verbindung hergestellt werden kann.

Die Hostingintegration basiert auf den 📦 AspNetCore.HealthChecks.MongoDb NuGet-Paket.

Client integration

Um mit der .NET AspireMongoDBclient-Integration zu beginnen, installieren Sie das 📦Aspire.MongoDB.Treiber--NuGet-Paket im client-verbrauchenden Projekt, das heißt, dem Projekt für die Anwendung, die das MongoDBclientverwendet. Die MongoDBclient-Integration registriert eine IMongoClient- Instanz, die Sie für die Interaktion mit der MongoDBserver-Ressource verwenden können. Wenn dein App-Host MongoDB Datenbankressourcen hinzufügt, wird auch die IMongoDatabase Instanz registriert.

.NET CLI
PackageReference

dotnet add package Aspire.MongoDB.Driver

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

Hinzufügen von MongoDBclient

Rufen Sie in der Datei Program.cs Ihres client-verbrauchenden Projekts die AddMongoDBClient-Erweiterungsmethode an jedem IHostApplicationBuilder auf, um eine IMongoClient zur Verwendung mittels des Abhängigkeitsinjektionscontainers zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.

builder.AddMongoDBClient(connectionName: "mongodb");

Trinkgeld

Der parameter connectionName muss mit dem Namen übereinstimmen, der beim Hinzufügen der MongoDBserver-Ressource (oder der Datenbankressource, sofern angegeben) im App-Hostprojekt verwendet wird. Mit anderen Worten, wenn Sie AddDatabase aufrufen und einen Namen von mongodb angeben, sollte genau dieser Name beim Aufrufen von AddMongoDBClientverwendet werden. Weitere Informationen finden Sie unter MongoDBserver Ressource und Datenbankressourcehinzufügen.

Anschließend können Sie die IMongoClient Instanz mithilfe der Abhängigkeitseinfügung abrufen. Um beispielsweise die client aus einem Beispieldienst abzurufen:

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

Die IMongoClient wird verwendet, um mit der MongoDBserver Ressource zu interagieren. Es kann verwendet werden, um Datenbanken zu erstellen, die dem App-Hostprojekt noch nicht bekannt sind. Wenn Sie eine MongoDB-Datenbankressource in Ihrem App-Host definieren, können Sie stattdessen erfordern, dass der Container zum Einfügen von Abhängigkeiten eine IMongoDatabase Instanz bereitstellt. Weitere Informationen zur Abhängigkeitsinjektion finden Sie unter .NET Abhängigkeitsinjektion.

Füge keyed MongoDBclient hinzu

Es kann Situationen geben, in denen Sie mehrere IMongoDatabase Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Rufen Sie die AddKeyedMongoDBClient-Methode auf, um MongoDB-Clients mit Schlüssel zu registrieren.

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

Wichtig

Bei der Verwendung von Schlüsseldiensten wird erwartet, dass Ihre MongoDB Ressource zwei benannte Datenbanken konfiguriert hat, eine für die mainDb und eine für die loggingDb.

Anschließend können Sie mithilfe der Dependency Injection die IMongoDatabase Instanzen abrufen. So rufen Sie beispielsweise die Verbindung aus einem Beispieldienst ab:

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

Weitere Informationen zu schlüsselbasierten Diensten finden Sie unter .NET Abhängigkeitsinjektion: schlüsselbasierte Dienste.

Konfiguration

Die .NET AspireMongoDB Datenbankintegration bietet mehrere Konfigurationsmethoden und Optionen, um die Anforderungen und Konventionen Ihres Projekts zu erfüllen.

Verwenden einer Verbindungszeichenfolge

Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, können Sie beim Aufrufen von builder.AddMongoDBClient()den Namen der Verbindungszeichenfolge angeben:

builder.AddMongoDBClient("mongo");

Aus dem Konfigurationsabschnitt ConnectionStrings wird die Verbindungszeichenfolge abgerufen. Betrachten Sie das folgende MongoDB Beispiel JSON Konfiguration:

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

Betrachten Sie alternativ die folgende MongoDB Atlas-Beispielkonfiguration JSON.

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

Weitere Informationen zum Formatieren dieser Verbindungszeichenfolge finden Sie unter MongoDB: ConnectionString-Dokumentation.

Verwenden Sie Konfigurationsanbieter

Die .NET Aspire-MongoDB-Integration unterstützt Microsoft.Extensions.Configuration. Sie lädt die MongoDBSettings mithilfe des Aspire:MongoDB:Driver Schlüssels aus der Konfiguration. Der folgende Codeausschnitt ist ein Beispiel für eine appsettings.json Datei, die einige der Optionen konfiguriert:

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

Verwenden Sie Inlinekonfigurationen

Sie können auch den Action<MongoDBSettings> Delegat übergeben, um einige oder alle Optionen inline einzurichten:

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

Konfigurationsoptionen

Hier sind die konfigurierbaren Optionen mit entsprechenden Standardwerten:

Name	Beschreibung
`ConnectionString`	Die Verbindungszeichenfolge der MongoDB-Datenbank, mit der eine Verbindung hergestellt werden soll.
`DisableHealthChecks`	Ein boolescher Wert, der angibt, ob die Datenbankintegritätsprüfung deaktiviert ist oder nicht.
`HealthCheckTimeout`	Ein `int?` Wert, der das Timeout der MongoDB Gesundheitsprüfung in Millisekunden angibt.
`DisableTracing`	Ein boolescher Wert, der angibt, ob die OpenTelemetry Ablaufverfolgung deaktiviert ist oder nicht.

Gesundheitsprüfungen

Standardmäßig aktivieren .NET.NET Aspire Integrationen Integritätsprüfungen für alle Dienste. Weitere Informationen finden Sie unter .NET.NET Aspire Integrationsübersicht.

Standardmäßig behandelt die .NET AspireMongoDBclient-Integration die folgenden Szenarien:

Fügt eine Integritätsprüfung hinzu, die bei Aktivierung überprüft, ob eine Verbindung hergestellt und Befehle innerhalb einer bestimmten Zeitspanne gegen die MongoDB-Datenbank ausgeführt werden können.
Wird in den /health HTTP-Endpunkt integriert, der angibt, dass alle registrierten Gesundheitsprüfungen bestehen müssen, damit die App als bereit zur Annahme von Datenverkehr gilt.

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als den Säulen der Observabilitybezeichnet werden. Weitere Informationen zur Integrations-Observability und Telemetrie finden Sie unter .NET.NET Aspire Integrationsübersicht. Abhängig vom unterstützenden Dienst unterstützen Integrationen möglicherweise nur bestimmte dieser Features. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetrie-Funktionen können auch mithilfe der Techniken deaktiviert werden, die im Abschnitt Configuration beschrieben werden.

Protokollierung

Die .NET AspireMongoDB-Datenbankintegration verwendet die Protokollierung nach dem Standard .NET, wobei Protokolleinträge aus den folgenden Kategorien angezeigt werden:

MongoDB[.*]: Alle Protokolleinträge aus dem MongoDB Namespace.

Nachverfolgung

Die .NET AspireMongoDB Datenbankintegration gibt die folgenden Tracing-Aktivitäten mithilfe von OpenTelemetryaus.

MongoDB.Driver.Core.Extensions.DiagnosticSources

Metriken

Die .NET AspireMongoDB Datenbankintegration macht derzeit keine OpenTelemetry Metriken verfügbar.

Freigeben über