.NET Aspire MongoDB database-integratie

2025-06-11

Inclusief: —&— Client integratie

MongoDB is een NoSQL-database die hoge prestaties, hoge beschikbaarheid en eenvoudige schaalbaarheid biedt. Met de .NET AspireMongoDB-integratie kunt u verbinding maken met bestaande MongoDB exemplaren (inclusief MongoDB Atlas) of nieuwe exemplaren maken vanuit .NET met de docker.io/library/mongo containerinstallatiekopieën

Hostingintegratie

De MongoDB-server, die integratiemodellen host, modelleert de server als het MongoDBServerResource-type en de database als het MongoDBDatabaseResource-type. Als u toegang wilt krijgen tot deze typen en API's, voegt u het 📦Aspire.Hosting.MongoDB NuGet-pakket toe in het app-hostproject.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.MongoDB

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

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

MongoDB serverresource en databaseresource toevoegen

Roep in uw app-host-project AddMongoDB aan om een MongoDB server-resource-bouwer toe te voegen en te retourneren. Koppel een aanroep aan de geretourneerde resourcebouwer bij AddDatabaseom een databaseresource MongoDB toe te voegen.

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

Notitie

De MongoDB container kan traag opstarten, dus kunt u het beste een persistente levensduur gebruiken om onnodige herstarts te voorkomen. Zie Levensduur van containerresourcesvoor meer informatie.

Wanneer .NET.NET Aspire een containerinstallatiekopie toevoegt aan de app-host, zoals wordt weergegeven in het vorige voorbeeld met de docker.io/library/mongo-installatiekopie, wordt er een nieuw MongoDB exemplaar op uw lokale computer gemaakt. Een verwijzing naar de server-resourcebouwer MongoDB (de variabele mongo) wordt gebruikt om een database toe te voegen. De database heeft de naam mongodb en wordt vervolgens toegevoegd aan de ExampleProject. De MongoDB-server-resource bevat standaard-inloggegevens.

MONGO_INITDB_ROOT_USERNAME: een waarde van admin.
MONGO_INITDB_ROOT_PASSWORD: Willekeurige password gegenereerd met behulp van de methode CreateDefaultPasswordParameter.

Wanneer de app-host draait, wordt het wachtwoord opgeslagen in de geheime opslag van de app-host. Deze wordt toegevoegd aan de sectie Parameters, bijvoorbeeld:

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

De naam van de parameter is mongo-password, maar eigenlijk is het alleen het opmaken van de resourcenaam met een -password achtervoegsel. Zie Veilige opslag van app-geheimen in ASP.NET Core en MongoDB serverresource toevoegen met parametersvoor meer informatie.

De methode WithReference configureert een verbinding in de ExampleProject met de naam mongodb en de WaitFor geeft de app-host opdracht om de afhankelijke service pas te starten als de mongodb resource gereed is.

Aanbeveling

Als u liever verbinding wilt maken met een bestaande MongoDB-server, roept u in plaats daarvan AddConnectionString aan. Raadpleeg Bestaande bronnenvoor meer informatie.

MongoDB serverresource toevoegen met gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de MongoDB serverresource, roept u de WithDataVolume methode aan op de MongoDB serverresource:

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

Het gegevensvolume wordt gebruikt om de MongoDB servergegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /data/db pad in de MongoDB servercontainer en wanneer er geen name parameter wordt opgegeven, wordt de naam willekeurig gegenereerd. Zie voor meer informatie over datavolumes en waarom zij de voorkeur krijgen boven Docker.

Waarschuwing

Het wachtwoord wordt opgeslagen in het gegevensvolume. Wanneer u een gegevensvolume gebruikt en als het wachtwoord wordt gewijzigd, werkt het pas als u het volume verwijdert.

Belangrijk

Sommige databaseintegraties, inclusief de .NET AspireMongoDB integratie, kunnen geen gegevensvolumes gebruiken na de implementatie naar Azure Container Apps (ACA). Dit komt doordat ACA gebruikmaakt van Server Message Block (SMB) om containers te verbinden met gegevensvolumes, en sommige systemen kunnen deze verbinding niet gebruiken. In het Aspire dashboard heeft een database die wordt beïnvloed door dit probleem de status Activeren of Activeren is mislukt , maar wordt nooit vermeld als Actief.

U kunt het probleem oplossen door te implementeren in een Kubernetes cluster, zoals AzureKubernetes Services (AKS). Zie .NET.NET Aspire implementatiesvoor meer informatie.

MongoDB serverbron toevoegen met data-bind mount

Als u een gegevensbindingskoppeling wilt toevoegen aan de MongoDB-serverresource, roept u de methode WithDataBindMount aan:

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

Belangrijk

Gegevens koppelpunten hebben beperkte functionaliteit vergeleken met volumes, die betere prestaties, draagbaarheid en beveiliging bieden, waardoor ze meer geschikt zijn voor productieomgevingen. "Bind mounts bieden echter directe toegang tot en wijziging van bestanden op het hostsysteem, ideaal voor ontwikkeling en testen waar wijzigingen in real-time nodig zijn."

Gegevensbind-mounts zijn afhankelijk van het bestandssysteem van de hostcomputer om de MongoDB servergegevens bij het herstarten van containers te behouden. De koppeling voor gegevensbinding wordt gekoppeld aan de C:\MongoDB\Data in Windows (of /MongoDB/Data op Unix) op de hostcomputer in de MongoDB servercontainer. Zie Docker docs: Bindingskoppelingenvoor meer informatie over koppelingskoppelingen voor gegevens.

MongoDB server resource toevoegen met koppeling voor het binden van initialisatiegegevens

Als u een bindmount van initialisatiemapgegevens aan de MongoDB-serverresource wilt toevoegen, roept u de WithInitBindMount-methode aan.

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

Het koppelingspunt voor initialisatiegegevens wordt gebruikt om de MongoDB-server met gegevens te initialiseren. De bindmount voor de initialisatiegegevens is gemonteerd bij de C:\MongoDB\Init op Windows (of /MongoDB/Init op Unix) in de hostmachine binnen de MongoDB servercontainer en wordt toegewezen aan het /docker-entrypoint-initdb.d pad in de MongoDB servercontainer. MongoDB voert de scripts uit die in deze map zijn gevonden. Dit is handig voor het laden van gegevens in de database.

MongoDB serverresource toevoegen met parameters

Wanneer u expliciet het wachtwoord wilt opgeven dat wordt gebruikt door de container-afbeelding, kunt u deze inloggegevens opgeven als parameters. Bekijk het volgende alternatieve voorbeeld:

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

Zie Externe parametersvoor meer informatie over het opgeven van parameters.

MongoDB Express-resource toevoegen

MongoDB Express is een webgebaseerde beheerders gebruikersinterface voor MongoDB. Als u een MongoDB Express-resource wilt toevoegen die overeenkomt met de docker.io/library/mongo-express containerimage, roep dan de WithMongoExpress-methode aan op de MongoDB-serverresource.

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

Aanbeveling

Om de hostpoort voor de MongoExpressContainerResource-keten te configureren, roept u de WithHostPort-API aan en geeft u het gewenste poortnummer op.

Met de voorgaande code wordt een MongoDB Express-resource toegevoegd die is geconfigureerd om verbinding te maken met de MongoDB serverresource. De standaard inloggegevens zijn:

ME_CONFIG_MONGODB_SERVER: de naam die is toegewezen aan de bovenliggende MongoDBServerResource, in dit geval zou dit mongozijn.
ME_CONFIG_BASICAUTH: een waarde van false.
ME_CONFIG_MONGODB_PORT: Toegekend aan de doelpoort van het primaire eindpunt van de moeder MongoDBServerResource.
ME_CONFIG_MONGODB_ADMINUSERNAME: Dezelfde gebruikersnaam als geconfigureerd in de bovenliggende MongoDBServerResource.
ME_CONFIG_MONGODB_ADMINPASSWORD: hetzelfde wachtwoord als geconfigureerd in de bovenliggende MongoDBServerResource.

Bovendien bevat de WithMongoExpress-API een optionele configureContainer parameter van het type Action<IResourceBuilder<MongoExpressContainerResource>> dat u gebruikt om de MongoDB Express-containerresource te configureren.

Gezondheidscontroles voor hostingintegratie

De MongoDB hostingintegratie voegt automatisch een statuscontrole toe voor de MongoDB serverresource. De gezondheidscontrole controleert of de MongoDB-serverresource in werking is en of er een verbinding tot stand kan worden gebracht.

De hostingintegratie is afhankelijk van het 📦 AspNetCore.HealthChecks.MongoDb NuGet-pakket.

integratie Client

Om aan de slag te gaan met de .NET AspireMongoDB-clientintegratie, installeer het 📦AspireMongoDB-Driver NuGet-pakket in het project dat door de applicatie wordt gebruikt en van de MongoDB-client gebruikmaakt. De MongoDB-clientintegratie registreert een IMongoClient exemplaar dat u kunt gebruiken om te communiceren met de MongoDB-serverresource. Als uw app-host MongoDB databaseresources toevoegt, wordt de IMongoDatabase-instantie ook geregistreerd.

.NET CLI
PackageReference

dotnet add package Aspire.MongoDB.Driver

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

Belangrijk

Het Aspire.MongoDB.Driver NuGet-pakket is afhankelijk van het MongoDB.Driver NuGet-pakket. Met de release van versie 3.0.0 van MongoDB.Driver werd een binaire brekende wijziging geïntroduceerd. Hiervoor is een nieuw clientintegratiepakket, Aspire.MongoDB.Driver.v3, gemaakt. Het oorspronkelijke Aspire.MongoDB.Driver pakket blijft verwijzen naar MongoDB.Driver versie 2.30.0, waardoor compatibiliteit met eerdere versies van de RabbitMQ clientintegratie wordt gewaarborgd. Het nieuwe Aspire.MongoDB.Driver.v3 pakket verwijst naar MongoDB.Driver versie 3.0.0. In een toekomstige versie van .NET.NET Aspirewordt de Aspire.MongoDB.Driver bijgewerkt naar versie 3.x en wordt het Aspire.MongoDB.Driver.v3-pakket afgeschaft. Zie Upgraden naar versie 3.0 voor meer informatie.

MongoDB-client toevoegen

Roep in het Program.cs bestand van het clientgebruikte project de AddMongoDBClient-extensiemethode aan op een IHostApplicationBuilder om een IMongoClient te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

builder.AddMongoDBClient(connectionName: "mongodb");

Aanbeveling

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de MongoDB serverresource (of de databaseresource wanneer deze is opgegeven) in het app-hostproject. Met andere woorden, wanneer u AddDatabase aanroept en een naam opgeeft van mongodb diezelfde naam moet worden gebruikt bij het aanroepen van AddMongoDBClient. Voor meer informatie, zie server-resource en database-resource toevoegen MongoDB.

Vervolgens kunt u het IMongoClient exemplaar ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de client wilt ophalen uit een voorbeeldservice:

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

De IMongoClient wordt gebruikt om te communiceren met de MongoDB serverresource. Het kan worden gebruikt om databases te maken die nog niet bekend zijn bij het app-hostproject. Wanneer u een MongoDB databaseresource in uw app-host definieert, kunt u in plaats daarvan vereisen dat de container voor afhankelijkheidsinjectie een IMongoDatabase exemplaar biedt. Voor meer informatie over afhankelijkheidsinjectie, zie .NET afhankelijkheidsinjectie.

Keyed MongoDB-client toevoegen

Er kunnen situaties zijn waarin u meerdere IMongoDatabase exemplaren met verschillende verbindingsnamen wilt registreren. Als u keyed MongoDB-clients wilt registreren, roept u de methode AddKeyedMongoDBClient aan:

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

Belangrijk

Wanneer u sleutelservices gebruikt, wordt verwacht dat uw MongoDB resource twee benoemde databases heeft geconfigureerd, één voor de mainDb en één voor de loggingDb.

Vervolgens kunt u de IMongoDatabase exemplaren ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:

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

Voor meer informatie over gesleutelde services, zie .NET afhankelijkheidsinjectie: gesleutelde services.

Configuratie

De .NET AspireMongoDB-databaseintegratie biedt meerdere configuratiemethoden en opties om te voldoen aan de vereisten en conventies van uw project.

Een verbindingsreeks gebruiken

Wanneer u een verbindingsreeks uit de sectie ConnectionStrings configuratie gebruikt, kunt u de naam van de verbindingsreeks opgeven bij het aanroepen van builder.AddMongoDBClient():

builder.AddMongoDBClient("mongo");

De verbindingsreeks wordt opgehaald uit de sectie ConnectionStrings configuratie. Bekijk het volgende MongoDB voorbeeld van JSON configuratie:

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

U kunt ook het volgende MongoDB Atlas-voorbeeld JSON configuratie overwegen:

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

Zie MongoDB: ConnectionString-documentatievoor meer informatie over het opmaken van deze verbindingsreeks.

Configuratieproviders gebruiken

De .NET AspireMongoDB-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de MongoDBSettings vanuit de configuratie met behulp van de Aspire:MongoDB:Driver-sleutel. Het volgende codefragment is een voorbeeld van een appsettings.json-bestand waarmee een aantal van de opties wordt geconfigureerd:

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

Inlineconfiguraties gebruiken

U kunt de Action<MongoDBSettings> delegate ook doorgeven om bepaalde of alle opties in-line in te stellen:

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

Configuratieopties

Dit zijn de configureerbare opties met bijbehorende standaardwaarden:

Naam	Beschrijving
`ConnectionString`	De verbindingsreeks van de MongoDB databasedatabase waarmee verbinding moet worden gemaakt.
`DisableHealthChecks`	Een Booleaanse waarde die aangeeft of de databasestatuscontrole is uitgeschakeld of niet.
`HealthCheckTimeout`	Een `int?` waarde die de time-out voor de MongoDB statuscontrole in milliseconden aangeeft.
`DisableTracing`	Een booleaanse waarde die aangeeft of de OpenTelemetry tracering is uitgeschakeld of niet.

Gezondheidscontroles voor Client-integratie

.NET .NET Aspire clientintegraties hebben standaard gezondheidscontroles ingeschakeld voor alle diensten. Evenzo, schakelen veel .NET.NET Aspirehostingintegraties ook eindpunten voor gezondheidscontrole in. Zie voor meer informatie:

De .NET AspireMongoDB clientintegratie verwerkt standaard de volgende scenario's:

Voegt een gezondheidscontrole toe die, wanneer ingeschakeld, controleert of een verbinding tot stand kan worden gebracht en commando's binnen een bepaalde tijd kunnen worden uitgevoerd tegen de MongoDB-database.
Integreert met het /health HTTP-eindpunt, waarbij alle geregistreerde gezondheidscontroles moeten slagen zodat de app als gereed wordt beschouwd voor het accepteren van verkeer.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties stellen automatisch configuraties in voor logging, tracing en metrics, die soms ook wel bekend staan als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De .NET AspireMongoDB-databaseintegratie maakt gebruik van standaard .NET logboekregistratie en u ziet logboekvermeldingen uit de volgende categorieën:

MongoDB[.*]: logboekvermeldingen uit de MongoDB naamruimte.

Opsporen

De integratie van de .NET AspireMongoDB database verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

MongoDB.Driver.Core.Extensions.DiagnosticSources

Statistieken

De .NET AspireMongoDB-databaseintegratie bevat momenteel geen OpenTelemetry metrische gegevens.

Delen via

.NET Aspire MongoDB database-integratie

Hostingintegratie

MongoDB serverresource en databaseresource toevoegen

MongoDB serverresource toevoegen met gegevensvolume

MongoDB serverbron toevoegen met data-bind mount

MongoDB server resource toevoegen met koppeling voor het binden van initialisatiegegevens

MongoDB serverresource toevoegen met parameters

MongoDB Express-resource toevoegen

Gezondheidscontroles voor hostingintegratie

integratie Client

MongoDB-client toevoegen

Keyed MongoDB-client toevoegen

Configuratie

Een verbindingsreeks gebruiken

Configuratieproviders gebruiken

Inlineconfiguraties gebruiken

Configuratieopties

Gezondheidscontroles voor Client-integratie

Waarneembaarheid en telemetrie

Loggen

Opsporen

Statistieken

Zie ook

Feedback

Aanvullende resources