.NET Aspire MongoDB Datenbankintegration

Artikel
01/23/2025

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 MongoDB-Servermodellierung stellt den Server als MongoDBServerResource-Typ und die Datenbank als MongoDBDatabaseResource-Typ dar. 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 MongoDB Serverressource und Datenbankressource

Rufen Sie in Ihrem App-Hostprojekt AddMongoDB auf, um einen MongoDB Serverressourcen-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 MongoDB Serverressourcen-Generator (die mongo Variable) wird verwendet, um eine Datenbank hinzuzufügen. Die Datenbank wird mongodb benannt und dann dem ExampleProjecthinzugefügt. Die MongoDB Serverressource 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 Sichere Speicherung von App-Geheimnissen in der Entwicklung in ASP.NET Core und Serverressource MongoDB mit Parameternhinzufügen.

Die Methode WithReference konfiguriert eine Verbindung in der mit dem Namen ExampleProject ausgestatteten mongodb, 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 MongoDB Server herstellen möchten, rufen Sie stattdessen AddConnectionString auf. Weitere Informationen finden Sie unter Referenzieren vorhandener Ressourcen.

Hinzufügen MongoDB Serverressource mit Datenvolume

Um der MongoDB Serverressource ein Datenvolume hinzuzufügen, rufen Sie die WithDataVolume Methode für die MongoDB Serverressource auf:

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 MongoDB Serverdaten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolume wird am /data/db Pfad im MongoDB Servercontainer 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.

Hinzufügen der MongoDB-Serverressource mit Daten-Bindemontage

Rufen Sie die WithDataBindMount-Methode auf, um ein Datenbindemount zur MongoDB-Serverressource 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 MongoDB Serverdaten über Containerneustarts hinweg beizubehalten. Die Daten-Bind-Mount ist bei C:\MongoDB\Data unter Windows (oder bei /MongoDB/Data auf Unix) auf dem Host-Rechner im MongoDB Server-Container eingehängt. Weitere Informationen zu Daten-Bind-Mounts finden Sie unter Docker Dokumentation: Bind-Mounts.

Hinzufügen der Serverressource MongoDB mit Initialisierungsdaten-Bindemontage

Rufen Sie die WithInitBindMount-Methode auf, um eine Initialisierungsordner-Datenbindung zu der MongoDB-Serverressource 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...

Der Initialisierungsdaten-Bind-Mount dient dazu, den MongoDB-Server mit Daten zu initialisieren. Die Initialisierungsdaten-Bindung wird auf dem C:\MongoDB\Init unter Windows (oder /MongoDB/Init auf Unix) auf dem Hostcomputer im MongoDB-Servercontainer eingehängt und entspricht dem /docker-entrypoint-initdb.d-Pfad im MongoDB-Servercontainer. MongoDB führt die in diesem Ordner gefundenen Skripts aus, was zum Laden von Daten in die Datenbank nützlich ist.

Fügen Sie MongoDB Server-Ressource mit Parametern hinzu

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 Containerimageentspricht, rufen Sie die WithMongoExpress-Methode für die MongoDB Serverressource 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...

Trinkgeld

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 MongoDB Serverressource 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 Hostingintegration fügt automatisch eine Integritätsprüfung für die MongoDB Serverressource hinzu. Die Gesundheitsprüfung überprüft, ob die MongoDB Serverressource ausgeführt wird und ob eine Verbindung hergestellt werden kann.

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

Client integration

Um mit der .NET AspireMongoDB-Clientintegration zu beginnen, installieren Sie das 📦Aspire.MongoDB.Driver NuGet-Paket im clientnutzenden Projekt, das heißt, dem Projekt für die Anwendung, die den MongoDB-Client verwendet. Die MongoDB Clientintegration registriert eine IMongoClient- Instanz, die Sie für die Interaktion mit der MongoDB Serverressource 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 des MongoDB-Kunden

Rufen Sie in der Program.cs Datei Ihres clientnutzenden Projekts die AddMongoDBClient Erweiterungsmethode an jedem IHostApplicationBuilder auf, um eine IMongoClient zur Verwendung mit dem Abhängigkeitsinjektionscontainer 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 MongoDB Serverressource (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 Hinzufügen von MongoDB der Serverressource und der Datenbankressource.

Anschließend können Sie die IMongoClient Instanz mithilfe der Abhängigkeitseinfügung abrufen. So rufen Sie beispielsweise den Client aus einem Beispieldienst ab:

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

Die IMongoClient wird verwendet, um mit der MongoDB Serverressource 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.

Hinzufügen des Schlüssel-Clients MongoDB

Es kann Situationen geben, in denen Sie mehrere IMongoDatabase Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Rufen Sie die MongoDB-Methode auf, um AddKeyedMongoDBClient-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 AspireMongoDB Clientintegration 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

.NET Aspire MongoDB Datenbankintegration

Hosting-Integration

Hinzufügen MongoDB Serverressource und Datenbankressource

Hinzufügen MongoDB Serverressource mit Datenvolume

Hinzufügen der MongoDB-Serverressource mit Daten-Bindemontage

Hinzufügen der Serverressource MongoDB mit Initialisierungsdaten-Bindemontage

Fügen Sie MongoDB Server-Ressource mit Parametern hinzu

Ressource MongoDB Express hinzufügen

Hosten von Integritätsprüfungen für Integration

Client integration

Hinzufügen des MongoDB-Kunden

Hinzufügen des Schlüssel-Clients MongoDB

Konfiguration

Verwenden einer Verbindungszeichenfolge

Verwenden Sie Konfigurationsanbieter

Verwenden Sie Inlinekonfigurationen

Konfigurationsoptionen

Gesundheitsprüfungen

Observability und Telemetrie

Protokollierung

Nachverfolgung

Metriken

Siehe auch

Zusätzliche Ressourcen